Tool Search Tool

Overview (confidence: high)

The tool search tool is a Claude API mechanism that scales tool use to hundreds or thousands of tools by letting the model search its tool catalog and load only the tools it needs on demand. Instead of loading every tool definition into the context window up front, Claude searches the catalog — tool names, descriptions, argument names, and argument descriptions — and loads only the 3–5 tools required for a given request.

It solves two problems that appear as a tool library grows:

• Context bloat: a typical multiserver setup (GitHub, Slack, Sentry, Grafana, Splunk) consumes ~55k tokens in definitions before the model does any work; tool search typically reduces this by over 85 percent.
• Tool selection accuracy: the model’s ability to pick the right tool degrades beyond 30–50 available tools. On-demand loading of a focused set keeps selection accuracy high even across thousands of tools.

Mechanism (confidence: high)

• You include a tool search tool (for example tool_search_tool_regex_20251119 or tool_search_tool_bm25_20251119) in the tools list.
• You provide every tool definition in the tools array and set defer_loading: true on the tools that shouldn’t load up front. At least one tool — normally the tool search tool itself — must stay non-deferred.
• Initially the context contains only the tool search tool and any non-deferred tools. When Claude needs more, it searches, the API runs the search server-side and returns matching tools as tool_reference blocks (up to 5 by default), then automatically expands them into full definitions.
• The API excludes deferred tools from the system-prompt prefix; expansion appends a tool_reference block inline in the conversation. The prefix stays untouched, so prompt caching is preserved. Strict mode composes with defer_loading without grammar recompilation.
• defer_loading controls what enters the context window, not what you send: you still send every tool’s full definition on every request so the API can run the search and expand references.

Variants (confidence: high)

• Regex (tool_search_tool_regex_20251119): Claude writes Python re.search() patterns, not natural language. Case-insensitive; max pattern length 200 characters.
• BM25 (tool_search_tool_bm25_20251119): Claude searches with natural language queries; max query length 500 characters.

Both variants search tool names, descriptions, argument names, and argument descriptions.

MCP Integration (confidence: high)

For MCP toolsets through the MCP connector, set defer_loading once on the mcp_toolset entry’s default_config for the whole server, or per tool in its configs.

A custom client-side tool search is also possible: return standard tool_result blocks containing tool_reference content from your own search tool, with every referenced tool defined in the top-level tools parameter.

Limits and Fit (confidence: high)

• Max 10,000 deferred tools per request; each search returns up to 5 matches by default.
• Use when: 10+ tools, definitions consume >10k tokens, selection accuracy drops as the toolset grows, aggregating multiple MCP servers (200+ tools), or the tool library grows over time.
• Standard tool calling fits better when: fewer than 10 tools, every tool is used in every request, or definitions are small (<100 tokens total).
• Optimization: keep 3–5 most-used tools non-deferred; clear descriptive names/descriptions; namespace tool names by service (github_, slack_); add a system prompt section describing available tool categories.
• Not metered as a separate server tool; the definitions it loads count as input tokens like any other.

Relationship to Other Context Approaches (confidence: medium)

Tool search is one of four complementary context-management approaches documented by Claude Platform, alongside programmatic tool calling, prompt caching, and context editing — each targets a different source of context pressure, and they compose.

Related

tool-context-management two-tier-search-architecture prompt-caching token-usage-reduction claude-code-context-window message-batch-processing graphify-skill

Open Questions

• How tool search behaves for agents that aggregate 200+ tools across multiple MCP servers in practice (selection accuracy ceiling).
• Whether the deferred-loading pattern generalizes to non-Claude agents or remains a Claude API-specific mechanism.

Sources

• raw/external/platform-claude-com-tool-search-tool-081b885d.md
• raw/external/platform-claude-com-manage-tool-context-625d4da8.md