graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! #416: two-phase MCP tool exposure — names and a one-line description up
//! front, the full JSON Schema on demand.
//!
//! mcp.zig used to put every tool's whole `inputSchema` into the root catalog
//! at connect time, so a session paid for every schema of every configured
//! server on every request. With #345 (a user-level `~/.codegraff/mcp.json`
//! whose servers follow you into every checkout) that is a standing tax: one
//! companion server measured at +2,568 input tokens per call, whether or not
//! the model ever touched it. Measured against the bundled 13-tool Smolify
//! manifest (tool_schema_tests.zig): the catalog served for that one server
//! drops from 10,505 to 3,696 bytes, ~1,700 tokens off EVERY request.
//!
//! The deferred half of the catalog therefore carries `name` + a shortened
//! description + a placeholder schema, and `load_tool_schemas` hands back the
//! real schemas and ENABLES those tools for the rest of the session. A call to
//! a tool whose schema was never loaded is refused with instructions rather
//! than run (exec.zig, layer 2 — see `blocked`).
//!
//! Two invariants this module must never break:
//!
//! - **Consent is untouched.** Deferral is about context cost, not permission.
//! Nothing here reads or writes approvals, and the layer-2 refusal lives
//! INSIDE execToolInner, i.e. downstream of agent_tool_gate.gateTool: the
//! consent prompt is reached in exactly the cases it was reached before, in
//! the same order, and deferral can only ever subtract a call that consent
//! already allowed — never add one it did not.
//! - **Deferral is universal.** Every server's tools ship as placeholders
//! until `load_tool_schemas` unfolds them — the measured interactive
//! anatomy (#476) is that most sessions never call most servers, so eager
//! bytes are re-sent cost with no payoff, and discovery has proven
//! reliable. `GRAFF_MCP_SCHEMA_BUDGET` restores the old size-based
//! threshold; `GRAFF_MCP_EAGER` pins specific servers either way.
//!
//! Session state (which schemas have been loaded) is an append-only list in
//! its own process arena: writers lock (a direct MCP call auto-loads from a
//! pool thread), and readers follow the atomically published head.
const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;
const mcp = @import("mcp.zig");
const mcp_config = @import("mcp_config.zig");
const tools_mod = @import("tools.zig");
const util = @import("util.zig");
const tool_surface = @import("tool_surface.zig");
pub const omitMcp = tool_surface.omitMcp;
const ExecResult = tools_mod.ExecResult;
/// Per-server budget, in bytes of description + serialized schema, under which
/// a server is served eagerly. Zero by default: EVERY server defers. The old
/// 4 KiB threshold assumed the load round trip was a wash below ~1,000 tokens,
/// but that only holds for sessions that call the tool — the measured
/// interactive anatomy (#476) is that most sessions never touch most servers,
/// so eager bytes are pure re-sent cost and discovery via load_tool_schemas
/// has proven reliable (the codedbpro pin removal shipped with zero discovery
/// turns). GRAFF_MCP_SCHEMA_BUDGET restores a size threshold;
/// GRAFF_MCP_EAGER pins specific servers.
pub const default_budget: usize = 0;
/// How much of an MCP tool's description survives into the deferred listing.
/// Enough for a model to tell tools apart and decide what to load; a real MCP
/// description runs to paragraphs (codedbpro's `read` is over 400 bytes).
pub const desc_cap: usize = 180;
/// What a deferred tool advertises as its schema. Valid, permissive, and
/// self-describing, so a model that ignores the tool description still gets
/// told what to do — and `serde.defaultRootObjectType` has nothing to fix up.
/// Kept terse on purpose: it is repeated once per deferred tool, so every byte
/// here is paid N times against the savings it exists to buy. The full
/// protocol lives once, in `tool_desc`.
pub const placeholder_schema =
\\{"type": "object", "description": "Deferred - load_tool_schemas first."}
;
pub const env_enabled = "GRAFF_MCP_LAZY_SCHEMAS"; // "0" turns deferral off entirely
pub const env_budget = "GRAFF_MCP_SCHEMA_BUDGET"; // per-server byte threshold; 0 defers everything
pub const env_eager = "GRAFF_MCP_EAGER"; // comma-separated server names; "*" pins them all
/// The `load_tool_schemas` tool's name/description/schema, kept here as plain
/// strings (the skill_docs.zig pattern) so schema.zig's catalog needs one
/// entry and no import cycle. The description is spliced into a raw JSON
/// string, so it must stay free of characters needing JSON escapes.
pub const tool_name = "load_tool_schemas";
pub const tool_desc = "Load the full JSON input schemas for deferred tools and enable them for the rest of this session. Deferred tools — MCP and folded native — ship without their schemas so those bytes stay out of every request; what is deferred right now is listed at the end of this description. A tool whose schema has not been loaded CANNOT be called: load it first. Pass tools with exact names (mcp__server__tool for MCP, a bare name like workflow for native), server to load one whole MCP server, or query with keywords to search deferred tools; no arguments lists everything deferred. Loading is permanent for this session and free to repeat.";
pub const tool_schema =
\\{"type": "object", "properties": {"tools": {"type": "array", "items": {"type": "string"}, "description": "Exact qualified MCP tool names to load, e.g. mcp__deepwiki__ask_question"}, "server": {"type": "string", "description": "Load every deferred tool on this MCP server instead of naming them one by one"}, "query": {"type": "string", "description": "Search deferred tools by keyword (matches name and description, loads the top 8 matches) — use when you know what you need but not the exact tool name"}}}
;
/// How this session decides eager vs deferred. Set once by `configure`.
pub const Policy = struct {
enabled: bool = true,
budget: usize = default_budget,
/// Server names always served eagerly. A single "*" entry pins every
/// server, which is the escape hatch back to pre-#416 behavior.
eager: []const []const u8 = &.{},
};
pub var g_policy: Policy = .{};
/// Default on (ADR 0011, 2026-08-25): a loaded tool's schema rides the
/// load_tool_schemas RESULT, so the catalog does not re-render it. Skipping
/// policy-deferred tools even after load keeps the request prefix
/// byte-identical all session — what provider prefix caching charges
/// against. A load otherwise busts the cache (measured: 0% cache on the
/// calls right after each load). `GRAFF_STABLE_CATALOG=0` /
/// `GRAFF_NO_STABLE_CATALOG=1` restore the mutating catalog.
pub var g_stable_catalog = true;
/// Deferred by POLICY, ignoring load state — the stable-catalog render rule
/// and (in stable mode) the listing, which must not change as tools load.
pub fn policyDeferred(all: []const mcp.Tool, tool: mcp.Tool) bool {
if (!g_policy.enabled) return false;
const server = tool.serverName();
if (pinnedEager(server)) return false;
return serverCost(all, server) > g_policy.budget;
}
// --- session state: which schemas have been loaded -------------------------
const Node = struct {
name: []const u8,
/// The rendered `{"name":…,"description":…,"input_schema":…}` block, kept
/// so a repeated load is a pointer copy rather than a re-serialization.
/// This is the per-session schema cache the issue asks for.
rendered: []const u8,
/// Load order (0 = never loaded): the stable-catalog tail appends in this
/// order so a new load changes only the catalog's tail bytes (#476).
seq: usize,
next: ?*Node,
};
var g_head: std.atomic.Value(?*Node) = .init(null);
/// Test seam: how many schemas this session has actually serialized. A second
/// `load_tool_schemas` for the same tool must not move it.
var g_renders: usize = 0;
/// Drop every loaded schema. A new session, and every test that touches the
/// gate.
pub fn reset() void {
g_head.store(null, .release);
g_renders = 0;
}
pub fn rendersForTest() usize {
return g_renders;
}
fn find(name: []const u8) ?*Node {
var cur = g_head.load(.acquire);
while (cur) |node| : (cur = node.next) {
if (std.mem.eql(u8, node.name, name)) return node;
}
return null;
}
pub fn isLoaded(name: []const u8) bool {
return find(name) != null;
}
/// Nodes outlive every turn arena (a scripted REPL freed its conversation arena
/// before the final save walked the list); `reset` only drops the head. The
/// spin-lock serializes writers: exec.zig auto-loads from pool threads.
var g_nodes: std.heap.ArenaAllocator = .init(std.heap.page_allocator);
var g_nodes_lock: std.atomic.Value(bool) = .init(false);
/// Publish a copy of one loaded schema (its name is the registry's, `rendered`
/// the caller's); the release store makes it visible to pool threads.
fn publish(name: []const u8, rendered: []const u8) !*Node {
while (g_nodes_lock.cmpxchgWeak(false, true, .acquire, .monotonic) != null) std.atomic.spinLoopHint();
defer g_nodes_lock.store(false, .release);
if (find(name)) |node| return node; // another thread got there first
const a = g_nodes.allocator();
const node = try a.create(Node);
node.* = .{ .name = try a.dupe(u8, name), .rendered = try a.dupe(u8, rendered), .seq = nextSeq(), .next = g_head.load(.acquire) };
g_head.store(node, .release);
return node;
}
var g_seq: usize = 0;
pub fn nextSeq() usize {
g_seq += 1;
return g_seq;
}
/// A loaded tool's position in load order; null when not loaded. schema.zig's
/// stable-catalog tail sorts by this so loads are append-only.
pub fn loadSeq(qualified: []const u8) ?usize {
var cur = g_head.load(.acquire);
while (cur) |n| : (cur = n.next) if (std.mem.eql(u8, n.name, qualified)) return n.seq;
return null;
}
// --- policy ----------------------------------------------------------------
/// Resolve the session policy from the environment and the merged MCP config.
/// A server object may carry `"eager": true` to pin itself; unknown keys are
/// ignored by `mcp.Registry.startServer`, so the flag costs that path nothing.
/// Best-effort: an unparseable knob falls back to the default rather than
/// failing a session over a typo.
pub fn configure(arena: Allocator, merged: mcp_config.Merged, environ_map: anytype) void {
var policy: Policy = .{};
if (environ_map.get(env_enabled)) |v| policy.enabled = !std.mem.eql(u8, std.mem.trim(u8, v, " \t"), "0");
if (environ_map.get(env_budget)) |v| {
policy.budget = std.fmt.parseInt(usize, std.mem.trim(u8, v, " \t"), 10) catch default_budget;
}
var eager: std.ArrayList([]const u8) = .empty;
if (environ_map.get(env_eager)) |v| {
var it = std.mem.tokenizeScalar(u8, v, ',');
while (it.next()) |raw| {
const name = std.mem.trim(u8, raw, " \t");
if (name.len > 0) eager.append(arena, arena.dupe(u8, name) catch continue) catch {};
}
}
var it = merged.servers.iterator();
while (it.next()) |entry| {
if (entry.value_ptr.* != .object) continue;
const flag = entry.value_ptr.object.get("eager") orelse continue;
if (flag != .bool or !flag.bool) continue;
eager.append(arena, arena.dupe(u8, entry.key_ptr.*) catch continue) catch {};
}
policy.eager = eager.items;
g_policy = policy;
}
/// Startup-only promotion after configure(): a post-connect capability probe
/// (the codedb-pro license check) lands AFTER the registry starts, so it
/// appends here rather than arriving through env/config. Single-threaded
/// startup contract — call it from main() before the first catalog render,
/// never at request time (pool threads read g_policy concurrently).
pub fn pinEagerRuntime(arena: Allocator, server: []const u8) void {
if (pinnedEager(server)) return;
var list: std.ArrayList([]const u8) = .empty;
list.appendSlice(arena, g_policy.eager) catch return;
list.append(arena, arena.dupe(u8, server) catch return) catch return;
g_policy.eager = list.items;
}
/// --lean: fold EVERY MCP server behind load_tool_schemas rather than skip
/// MCP entirely — capability survives (a load call away), prefix cost drops
/// to names + shortened descriptions. Clears eager pins too: a licensed
/// companion's runtime pin is worth its bytes in an interactive session, not
/// in a one-shot counting every token. GRAFF_MCP_SCHEMA_BUDGET=0 is the same
/// policy reached by env; this is the flag's path to it.
pub fn deferAllRuntime() void {
g_policy.budget = 0;
g_policy.eager = &.{};
}
/// The server half of `mcp__<server>__<tool>`; "" for a name that is not one.
pub const serverOf = @import("mcp_names.zig").serverOf;
pub fn pinnedEager(server: []const u8) bool {
for (g_policy.eager) |p| {
if (std.mem.eql(u8, p, "*")) return true;
if (std.mem.eql(u8, p, server)) return true;
}
return false;
}
/// What one server costs the catalog: every one of its tools' descriptions
/// plus its serialized schema. Descriptions count because they are half the
/// bill on a verbose server, and deferral shortens them too.
pub fn serverCost(all: []const mcp.Tool, server: []const u8) usize {
var total: usize = 0;
for (all) |t| {
if (!std.mem.eql(u8, t.serverName(), server)) continue;
total += t.description.len + jsonBytes(t.input_schema, 0);
}
return total;
}
/// Whether this tool is advertised with a placeholder schema instead of its
/// own. Pure: the same inputs always give the same answer, and nothing here
/// consults approvals.
pub fn isDeferred(all: []const mcp.Tool, tool: mcp.Tool) bool {
if (!g_policy.enabled) return false;
if (isLoaded(tool.qualified_name)) return false;
const server = tool.serverName();
if (pinnedEager(server)) return false;
return serverCost(all, server) > g_policy.budget;
}
pub fn anyDeferred(all: []const mcp.Tool) bool {
for (all) |t| if (isDeferred(all, t)) return true;
return false;
}
/// Whether a built-in spec should be dropped from the rendered root catalog.
/// `load_tool_schemas` is only useful while something is deferred, so a
/// session with no MCP (or with everything eager) is never charged for it —
/// the same "advertise only what can be used" rule #330/#352 apply.
pub fn hiddenSpec(name: []const u8, all: []const mcp.Tool) bool {
const progressive = std.mem.eql(u8, name, tool_name) or
std.mem.eql(u8, name, "mcp_search_tools") or
std.mem.eql(u8, name, "mcp_select_tool");
if (!progressive) return false;
// Lean used to hide this even when MCP was connected, which made
// default `-p` unable to unfold `.mcp.json`. Show it whenever
// something is deferred; hide it when the listing would be empty.
return !anyDeferred(all);
}
/// The description a deferred tool advertises: the first line (or paragraph)
/// of the real one, capped on a codepoint boundary.
pub fn shortDesc(desc: []const u8) []const u8 {
var line = desc;
if (std.mem.indexOfScalar(u8, line, '\n')) |nl| line = line[0..nl];
line = std.mem.trim(u8, line, " \t\r");
return util.utf8Prefix(line, desc_cap);
}
// --- layer 2: refuse a call whose schema was never loaded -------------------
/// exec.zig's MCP dispatch calls this where it used to refuse: a confident
/// call to a deferred tool renders + publishes its schema and proceeds (user
/// direction — same rule as the native fold's markIfFolded). The catalog's
/// zero-stub listing is unchanged; the call itself was already provider-legal.
pub fn autoLoad(arena: Allocator, all: []const mcp.Tool, qualified: []const u8) void {
if (omitMcp(qualified)) return;
if (!blocked(all, qualified)) return;
for (all) |t| {
if (std.mem.eql(u8, t.qualified_name, qualified)) {
_ = enable(arena, t) catch {};
return;
}
}
}
/// Whether calling `qualified` right now must be refused. False for an eager
/// tool, for one already loaded, and for a name the registry does not know
/// (mcp.Registry.call owns that error, unchanged).
pub fn blocked(all: []const mcp.Tool, qualified: []const u8) bool {
for (all) |t| {
if (!std.mem.eql(u8, t.qualified_name, qualified)) continue;
return isDeferred(all, t);
}
return false;
}
// --- the load tool ---------------------------------------------------------
pub const Loaded = struct {
text: []const u8,
is_error: bool = false,
/// How many tools this call newly enabled (0 for a listing or an error).
loaded: usize = 0,
};
/// Serialize one tool as `{"name":…,"description":…,"input_schema":…}`.
fn renderEntry(arena: Allocator, tool: mcp.Tool) ![]const u8 {
var aw: Io.Writer.Allocating = .init(arena);
var s: std.json.Stringify = .{ .writer = &aw.writer };
try s.beginObject();
try s.objectField("name");
try s.write(tool.qualified_name);
try s.objectField("description");
try s.write(tool.description);
try s.objectField("input_schema");
try s.write(tool.input_schema);
try s.endObject();
g_renders += 1;
return aw.writer.buffered();
}
/// Render, or reuse this session's cached render, and mark the tool enabled.
fn enable(arena: Allocator, tool: mcp.Tool) ![]const u8 {
if (find(tool.qualified_name)) |node| return node.rendered;
return (try publish(tool.qualified_name, try renderEntry(arena, tool))).rendered;
}
/// The pure core of the `load_tool_schemas` tool: everything except touching
/// the Agent. `input` is the model-supplied argument object.
pub fn loadInto(arena: Allocator, all: []const mcp.Tool, input: Value) !Loaded {
var wanted: std.ArrayList(usize) = .empty;
var missing: std.ArrayList([]const u8) = .empty;
const server = tools_mod.strField(input, "server");
if (server) |want| {
for (all, 0..) |t, i| if (std.mem.eql(u8, t.serverName(), want)) try wanted.append(arena, i);
if (wanted.items.len == 0) try missing.append(arena, want);
}
if (input == .object) if (input.object.get("tools")) |list| if (list == .array) {
for (list.array.items) |item| {
if (item != .string) continue;
const found = for (all, 0..) |t, i| {
if (std.mem.eql(u8, t.qualified_name, item.string)) break i;
} else null;
if (found) |i| try wanted.append(arena, i) else try missing.append(arena, item.string);
}
};
// codex tool_search pattern: keyword discovery when the exact name is not
// known — top matches join `wanted` and load exactly like named tools.
if (tools_mod.strField(input, "query")) |q| {
const matched = try matchQuery(arena, all, q);
if (matched.len == 0) {
const rest = try listing(arena, all, &.{});
return .{ .text = try std.fmt.allocPrint(arena, "no deferred tool matched query '{s}'. {s}", .{ q, rest }), .is_error = true };
}
for (matched) |i| try wanted.append(arena, i);
}
if (missing.items.len > 0) return .{ .text = try listing(arena, all, missing.items), .is_error = true };
if (wanted.items.len == 0) return .{ .text = try listing(arena, all, &.{}), .is_error = false };
var aw: Io.Writer.Allocating = .init(arena);
var emitted: usize = 0;
var fresh: usize = 0;
for (wanted.items, 0..) |i, k| {
// Named twice in one call (`server` plus its own name, say), or loaded
// by an earlier call: neither is an error, both are the cache working.
if (std.mem.indexOfScalar(usize, wanted.items[0..k], i) != null) continue;
if (omitMcp(all[i].qualified_name)) continue;
const first_time = !isLoaded(all[i].qualified_name);
try aw.writer.print("{s}\n", .{try enable(arena, all[i])});
emitted += 1;
if (first_time) fresh += 1;
}
var head: Io.Writer.Allocating = .init(arena);
try head.writer.print(
"{d} tool schema(s) below are now loaded and callable for the rest of this session ({d} newly enabled). " ++
"Call them with arguments matching input_schema.\n",
.{ emitted, fresh },
);
try head.writer.writeAll(aw.writer.buffered());
return .{ .text = head.writer.buffered(), .loaded = fresh };
}
/// The short tool name within its server: mcp__codedbpro__read -> read.
fn shortName(qualified: []const u8) []const u8 {
if (!std.mem.startsWith(u8, qualified, "mcp__")) return qualified;
const rest = qualified[5..];
const sep = std.mem.indexOf(u8, rest, "__") orelse return qualified;
return rest[sep + 2 ..];
}
/// Case-insensitive substring search (std.ascii has no indexOfIgnoreCase in
/// this toolchain): windowed eqlIgnoreCase, fine at description sizes.
pub fn containsIgnoreCase(haystack: []const u8, needle: []const u8) bool {
if (needle.len > haystack.len) return false;
var i: usize = 0;
while (i + needle.len <= haystack.len) : (i += 1)
if (std.ascii.eqlIgnoreCase(haystack[i .. i + needle.len], needle)) return true;
return false;
}
/// Keyword search over deferred tools (the load tool's `query` arm): score
/// each deferred tool by how many query tokens appear, case-insensitively, in
/// its qualified name or description; return the top 8, best first. A token
/// that matches nothing simply does not score — there is no fuzzier fallback,
/// because the no-match path returns the full deferred listing anyway.
fn matchQuery(arena: Allocator, all: []const mcp.Tool, query: []const u8) ![]usize {
const top_k = 8;
var best: [top_k]struct { score: usize, idx: usize } = undefined;
var n_best: usize = 0;
for (all, 0..) |t, i| {
if (!isDeferred(all, t)) continue;
var score: usize = 0;
var tok = std.mem.tokenizeAny(u8, query, " \t,;:/_-");
while (tok.next()) |w| {
if (w.len < 2) continue;
if (containsIgnoreCase(t.qualified_name, w) or containsIgnoreCase(t.description, w)) score += 1;
}
if (score == 0) continue;
if (n_best < top_k) {
best[n_best] = .{ .score = score, .idx = i };
n_best += 1;
} else {
// Replace the weakest entry when this one beats it.
var weakest: usize = 0;
for (best[0..n_best], 0..) |b, k| if (b.score < best[weakest].score) {
weakest = k;
};
if (score <= best[weakest].score) continue;
best[weakest] = .{ .score = score, .idx = i };
}
}
const out = try arena.alloc(usize, n_best);
// Selection-sort descending so the strongest match loads first.
for (out, 0..) |*slot, k| {
var top: usize = 0;
for (best[0..n_best], 0..) |b, j| if (b.score > best[top].score) {
top = j;
};
slot.* = best[top].idx;
best[top].score = 0;
_ = k;
}
return out;
}
/// The load tool's live catalog description: the static base plus, while
/// anything is deferred, a compact source listing (server: short tool names).
/// Deferred tools ship NO per-tool catalog entries of their own — this
/// listing is how the model learns what exists (codex's tool_search source
/// listing), and `query` covers discovery beyond it (#476).
pub fn descWithListing(arena: Allocator, all: []const mcp.Tool) ![]const u8 {
// Folded NATIVES ride this listing too (#476, the schema.zig zero-stub
// rule): their names live here, once, instead of a static enumeration
// every session re-pays after the tools load. Same stable-catalog rule
// as the MCP half — stable mode lists by policy, never by load state.
const native_fold = @import("native_fold.zig");
var natives: std.ArrayList([]const u8) = .empty;
if (native_fold.anyFolded() and !@import("no_local_tools.zig").lean) {
for (native_fold.folded) |name| {
if (!native_fold.isFolded(name)) continue;
if (std.mem.eql(u8, name, "rlm")) continue; // tail-only; listing rewrites the head
if (!g_stable_catalog and native_fold.isLoaded(name)) continue;
if (tool_surface.hideBuiltin(name)) continue;
try natives.append(arena, name);
}
}
if (!anyDeferred(all) and natives.items.len == 0) return tool_desc;
// Stable-catalog mode lists by POLICY, not load state: a listing that
// shrinks as tools load would change the prefix this mode exists to fix.
const deferredRule: *const fn ([]const mcp.Tool, mcp.Tool) bool = if (g_stable_catalog) &policyDeferred else &isDeferred;
var servers: std.ArrayList([]const u8) = .empty;
for (all) |t| {
if (omitMcp(t.qualified_name)) continue;
if (!deferredRule(all, t)) continue;
const sv = t.serverName();
const seen = for (servers.items) |s| {
if (std.mem.eql(u8, s, sv)) break true;
} else false;
if (!seen) try servers.append(arena, sv);
}
var aw: Io.Writer.Allocating = .init(arena);
try aw.writer.writeAll(tool_desc);
if (natives.items.len > 0) {
try aw.writer.writeAll(" Folded native:");
for (natives.items, 0..) |name, i| try aw.writer.print("{s}{s}", .{ if (i == 0) " " else ", ", name });
try aw.writer.writeAll(";");
}
if (servers.items.len > 0) try aw.writer.writeAll(" Deferred now:");
for (servers.items) |sv| {
try aw.writer.print(" {s} (", .{sv});
var first = true;
for (all) |t| {
if (omitMcp(t.qualified_name)) continue;
if (!deferredRule(all, t)) continue;
if (!std.mem.eql(u8, t.serverName(), sv)) continue;
if (!first) try aw.writer.writeAll(", ");
try aw.writer.writeAll(shortName(t.qualified_name));
first = false;
}
try aw.writer.writeAll(");");
}
return @import("context_limits.zig").applyAlloc(arena, aw.writer.buffered(), @import("context_limits.zig").mcp_schema_bytes);
}
/// What is deferred right now, names + short descriptions. Doubles as the
/// unknown-name error, which must say what DOES exist.
fn listing(arena: Allocator, all: []const mcp.Tool, unknown: []const []const u8) ![]const u8 {
var aw: Io.Writer.Allocating = .init(arena);
for (unknown) |name| try aw.writer.print("no deferred MCP tool or server named '{s}'. ", .{name});
var n: usize = 0;
for (all) |t| if (isDeferred(all, t)) {
n += 1;
};
if (n == 0) {
try aw.writer.writeAll("No MCP tool schemas are deferred: every connected tool is already callable with its full schema in your tool list.");
return aw.writer.buffered();
}
try aw.writer.print("{d} MCP tool(s) are deferred — pass their names to {s} to load and enable them:\n", .{ n, tool_name });
for (all) |t| if (isDeferred(all, t)) {
try aw.writer.print(" {s}: {s}\n", .{ t.qualified_name, shortDesc(t.description) });
};
return aw.writer.buffered();
}
/// The `load_tool_schemas` meta-tool arm (agent_tools.handleMeta). Meta, not
/// external, for two reasons: it mutates the agent's OWN tool catalog, and
/// running inline on the orchestrator thread is what makes the session state
/// above single-writer.
pub fn handleLoad(agent: anytype, input: Value) ExecResult {
if (agent.sub) return .{ .text = "load_tool_schemas is root-only; a subagent has no MCP registry of its own", .is_error = true };
const reg = agent.registry orelse return .{ .text = "no MCP servers are connected, so there are no schemas to load", .is_error = true };
if (@import("mcp_call.zig").unavailableLoad(reg, agent.arena, input)) |text| return .{ .text = text, .is_error = true }; // #1523
const catalog = reg.snapshotTools(agent.arena) catch return .{ .text = "load_tool_schemas failed to render the requested schemas", .is_error = true };
const r = loadInto(agent.arena, catalog, input) catch
return .{ .text = "load_tool_schemas failed to render the requested schemas", .is_error = true };
// Re-render the catalog so the provider sees the real schema too, not just
// the copy in this tool result.
if (r.loaded > 0) {
agent.invalidateRootTools();
agent.ensureRootTools(agent.provider.kind) catch {};
}
return .{ .text = r.text, .is_error = r.is_error };
}
// --- size accounting -------------------------------------------------------
/// Body in util.zig (600-line cap); re-exported so serverCost and the tests
/// keep naming this module.
pub const jsonBytes = util.jsonBytes;
// Tests live in mcp_schema_gate_tests.zig (both files answer to the 600-line
// ceiling); the catalog-level half is in tool_schema_tests.zig, next to
// renderRootTools.