Context Fills Up With Tool Definitions First
Wire a single agent to five MCP servers — GitHub, Slack, Sentry, Grafana, Splunk — and tool definitions alone burn roughly 55,000 tokens before any work starts, per Anthropic's own documentation. The cost isn't just tokens: selection accuracy degrades too. Once the available tool count crosses 30-50, Claude's ability to pick the right tool starts to slip, and aggregating multiple MCP servers into a single catalog of 200+ tools clears that threshold without much effort.
The fix isn't deleting definitions — it's loading them only when needed. Every request still carries the full tool list, but the point at which a tool actually enters the model's context gets pushed back until after a search returns a match. That deferral verifiably cuts context consumption by over 85%, narrowing what actually lands in context to 3-5 tools per search.
Two Search Paths: Regex and Natural Language
Search-based calling ships as two variants: tool_search_tool_regex_20251119 and tool_search_tool_bm25_20251119. The regex variant has Claude write re.search() patterns to match tool names, descriptions, and argument names (up to 200 characters); the BM25 variant searches the same fields with natural-language queries (up to 500 characters). Both return up to 5 tool_reference blocks per search, which the API auto-expands into full tool definitions before handing them to Claude.
Mark individual tools with defer_loading: true to flag them for on-demand loading. Every request must still carry every tool's full definition — the server needs it to run the search and expand references — and at least one tool, typically the search tool itself, can't be deferred. Deferred tools are excluded from the system-prompt prefix, so prompt-cache hit rates stay untouched.
From Design to Operations: A Tool Search Checklist
Three signals decide whether to adopt it: more than 10 available tools, tool definitions exceeding 10,000 tokens, or observably falling selection accuracy as the toolset grows. Set target numbers up front — context reduction above 85%, 3-5 tools loaded per search, a per-request cap of 10,000 deferrable tools — and keep your 3-5 most-used tools non-deferred so Claude can call them without searching first.
Failures start at the request stage. Leaving zero non-deferred tools trips a 400 error (All tools cannot be deferred), and omitting a definition that a tool_reference points to trips a separate 400 (Tool reference not found). Both are mistakes static validation catches before the request ever goes out.
At execution time, the search itself can fail, and the error codes split four ways: invalid_tool_input for bad patterns or length overruns, unavailable for service timeouts, too_many_requests for rate limits, execution_time_exceeded for search timeouts. Branch recovery by code — retry invalid_tool_input immediately after fixing the pattern, retry unavailable and execution_time_exceeded with exponential backoff, and throttle request rate itself on too_many_requests. Truncate queries client-side before they exceed the 200-character regex or 500-character BM25 cap to head off 400s entirely.
When tools come through an MCP connector, set defer_loading once on the mcp_toolset entry's default_config rather than per tool, or split it per tool via configs within that server. A single server can add dozens of tools at once, so server-level configuration catches what per-tool settings miss. Namespace tool names consistently — github_, slack_ — so one search query matches an entire group, and write descriptions using the phrasing real users actually type.
cache_control can't be set on a deferred tool — doing so trips a 400 — so keep your cache breakpoint on a non-deferred tool instead. Before shipping, test the case where search finds nothing and tool_references comes back empty. Weekly, pull logs of which queries surfaced which tools and refine descriptions from that; a group whose failure rate isn't dropping usually means the namespace or description keywords are out of sync with real queries. If built-in search hits its ceiling, move to embedding-based custom search — return results in the same tool_reference format so the API's expansion logic keeps working unchanged.
Takeaways at a Glance
Keep your 3-5 most-used tools non-deferred and defer the rest, and context consumption drops more than 85% while per-search accuracy holds at 3-5 relevant tools. Design retry and backoff branches around the two request-stage 400s and four execution-stage error codes ahead of time, and the same process keeps running unchanged the next time you add an MCP server.