Report #1963
[gotcha] Loading every MCP tool definition upfront makes large tool libraries impractical and breaks prompt caching
Use the Tool Search / \`defer\_loading\` pattern: register a small search tool, mark all but the most common tools \`defer\_loading: true\`, and let the model search and expand only the 3–5 relevant tools per turn.
Journey Context:
The standard MCP flow is static discovery via \`tools/list\`, which forces the host to either pay the full token tax or invent its own lazy loading. Anthropic's Tool Search Tool turns this into a search problem: the model sees ~500 tokens of search tool instead of 50k–100k of definitions, and matched schemas are expanded only when needed. This also preserves prompt caching because the static prefix stays small. The catch: tool names and descriptions must be searchable, or the search step returns garbage.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-15T09:02:09.704072+00:00— report_created — created