[regnull]

Why

A week of runs measured: each engineer call sent ~67k prompt tokens on average, starting at ~52k before any work. About 45k of that is tool definitions, and Linear's 76 MCP tools alone are ~30k. Every bot carries them on every call, yet Linear was called 19 times out of ~3,200 tool calls. The filesystem MCP tools were never called.

Separately, since #299 the derived thresholds for glm-5.3-flash (1.05M window) are summary 200k / clear ~133k, so calls passed 170k tokens before anything was trimmed.

What

• Lazy MCP tools (runtime/tool_loading.py)
  • MCP tools (registry source mcp:*) stay bound to the agent, but DeferredToolsMiddleware leaves them out of each model request until the bot loads them.
  • New load_tools tool: exact names (the server prefix can be dropped when unique) or a keyword query; at most 15 per call.
  • The system prompt gets a "Tools to load on demand" section listing names by server, with no schemas.
  • The loaded set lives in agent state (a union reducer), so it survives summarization and clearing; each run starts empty because the checkpoint is per run.
  • Loaded tools are appended after the always-on tools, so a load doesn't break the cached prefix of earlier definitions.
  • A call to an unloaded tool is refused and the tool is loaded, so the retry sees the real schema instead of guessed arguments.
  • Skipped for CLI-agent bots. defer_mcp_tools (default true) turns it off; it's in Settings → Context and the README.
• MAX_DERIVED_SUMMARY_TRIGGER 200k → 100k: 1M-window models now summarize at 100k and clear at ~67k, still above the ~47k that caused re-reading before Cap the output reserve and derived summary trigger in context thresholds #299.

Expected effect: per-call tool definitions go from ~45k tokens to ~4k plus a ~1k name list, until a run loads something.

Tests

• tests/test_tool_loading.py: search and name resolution, the prompt section, tools hidden until loaded and kept after, load by query, refuse-and-load, unknown names, the off switch.
• The fake model now records the tools offered on each call.
• Two threshold tests updated for the 100k cap.
• Backend: 798 passed; ruff clean.

Not yet run against a real model; worth watching the first run that touches Linear.

🤖 Generated with Claude Code