feat(mcp): lazy tool schemas — descriptions up front, full schema on demand (#416)

[justrach]

Closes #416. The largest per-turn context win in the current batch, and the one with a measured number rather than an estimate.

The problem

mcp.zig loaded every tool schema from every connected server into the tool list up front. With #345's global always-on config that scales badly: the live evals caught one companion server silently injecting +2,568 input tokens of schemas into every session, on every call.

The measurement

Against the bundled 13-tool Smolify manifest (a real server, 9,528 bytes of description + schema, the same order as the offender above), the served catalog for that one server drops:

10,505 → 3,696 bytes, a 64.8% cut, roughly 1,700 input tokens off every request for the whole session.

Obtained by rendering schema.renderRootTools twice, once with eager = {"*"} (byte-exact pre-change behaviour) and once with the default policy, then diffing lengths. The guarding test asserts a conservative 50% so ordinary schema growth cannot turn it red.

The default: size-based, per server

≤ 4 KiB of description + serialized schema stays eager. 4 KiB is roughly 1,000 tokens; below that the load_tool_schemas round trip re-emits about as much as deferral saved, so the indirection is a wash. The consequence that matters: every small server behaves byte-for-byte as it does today, and only expensive servers change behaviour at all.

Escape hatches: GRAFF_MCP_EAGER=<names> (with * restoring the old catalog wholesale), per-server "eager": true in .mcp.json and the global config, GRAFF_MCP_SCHEMA_BUDGET, and GRAFF_MCP_LAZY_SCHEMAS=0.

Two deliberate deviations from the issue

1. Size-based is the primary mechanism, with pins layered on, rather than a pin list alone. This is what buys zero behaviour change for the common case.
2. load_tool_schemas is a meta tool, not an external one. External tools run on a pool thread, which would make the loaded-schema set a genuine data race against concurrent MCP calls in the same batch. Meta dispatch runs inline on the orchestrator: exactly one writer, and an immediate catalog re-render. This is why the SDKs regenerate — the diff is the single new tool name, no drift noise.

Trust and consent are untouched: trustWorkspace and every consent check are unchanged, since deferral is about context cost, not permissions.

Verification

zig build test → 1057/1057, exit 0 (baseline 1043), also confirmed from a clean cache dir. scripts/eval-tier1.sh green across fmt, 600-line ceiling, reachability, build, invariants and SDK sync. Test reachability proven two ways: an exact +14 count, and a deliberate break that failed as expected.

Covered by test: descriptions-only listing, with an assertion that real property names present in schemas never leak into descriptions; load_tool_schemas returning correct schemas and enabling exactly the named tools; an unloaded call producing an actionable error naming both the tool and the fix; eager pin / * / off-switch / zero-budget bypasses; per-session caching proven with a render counter; dedupe when a tool is named twice; all three provider wire formats emitting valid combinator-free placeholder schemas.

Known gaps

• handleLoad's Agent-facing side (the invalidateRootTools/ensureRootTools re-render and the sub guard) is verified by inspection, not by test — its pure core loadInto is fully covered, but constructing a real Agent in a unit test is not set up here. load_tool_schemas was confirmed live to reach graff --schema.
• The placeholder schema for a deferred tool is assumed acceptable to every provider. It is {"type":"object", …}, the same shape an MCP server with no inputSchema already produces, through the same serde normalization, but it was not exercised against a live provider.

src/schema.zig is at 595/600 and src/agent_tools.zig at 597/600, so the next change to either needs an extraction first.