tool-search-tool changedagents-and-tools/tool-use/tool-search-tool
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+25added
Lines−25removed
From line
9
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits18to this page, all time
The whole hunk
from line 9, old and new numbered
/
from line 9
99Loading every tool definition up front causes two problems as a tool library grows:
1010
1111* **Context bloat:** A typical multiserver setup (GitHub, Slack, Sentry, Grafana, and Splunk) can consume \~55k tokens in definitions before Claude does any work. Tool search typically reduces this by over 85 percent, loading only the 3–5 tools Claude needs for a given request.
12* **Tool selection accuracy:** Claude's ability to pick the right tool degrades once you exceed 30–50 available tools. Because tool search loads only a focused set of relevant tools on demand, selection accuracy stays high even across thousands of tools.
12* **Tool selection accuracy:** Claude’s ability to pick the right tool degrades once you exceed 30–50 available tools. Because tool search loads only a focused set of relevant tools on demand, selection accuracy stays high even across thousands of tools.
1313
1414For the models that support tool search, see [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#model-compatibility).
1515
1616<Tip>
17 For background on the scaling challenges that tool search solves, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Tool search's on-demand loading is also an instance of the broader just-in-time retrieval principle described in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
17 For background on the scaling challenges that tool search solves, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Tool search’s on-demand loading is also an instance of the broader just-in-time retrieval principle described in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
1818</Tip>
1919
2020Tool search runs as a server-side tool, but you can also implement your own client-side tool search. See [Custom tool search implementation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation) for details.
from line 58
5858| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
5959| Claude Haiku 4.5 (claude-haiku-4-5-20251001) | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
6060
61Claude Opus 4.1 and earlier models don't support the tool search tool.
61Claude Opus 4.1 and earlier models don’t support the tool search tool.
6262
6363## How tool search works
6464
from line 70
7070When you enable the tool search tool:
7171
72721. You include a tool search tool (for example, `tool_search_tool_regex_20251119` or `tool_search_tool_bm25_20251119`) in your `tools` list.
732. 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.
743. Initially, Claude's context contains only the tool search tool and any non-deferred tools.
732. 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.
743. Initially, Claude’s context contains only the tool search tool and any non-deferred tools.
75754. When Claude needs additional tools, it searches using a tool search tool.
76765. The API runs the search and returns the matching tools as `tool_reference` blocks (up to 5 by default, although Claude can set a `limit` in its search input).
77776. The API automatically expands these references into full tool definitions.
from line 553
553553
554554 With `tool_search_tool_regex_20251119`, Claude writes Python `re.search()` patterns, not natural language queries. Matching is case-insensitive. Common patterns include the following:
555555
556 * `"weather"`: matches tool names and descriptions containing "weather"
556 * `"weather"`: matches tool names and descriptions containing “weather”
557557 * `"get_.*_data"`: matches tools such as `get_user_data` and `get_weather_data`
558558 * `"database.*query|query.*database"`: matches either word order
559559
from line 588
588588
589589`defer_loading` controls what enters the context window, not what you send in the request:
590590
591* You still send every tool's full definition in the `tools` array on every request, including the deferred ones. The API needs them server-side to run the search and expand `tool_reference` blocks.
591* You still send every tool’s full definition in the `tools` array on every request, including the deferred ones. The API needs them server-side to run the search and expand `tool_reference` blocks.
592592* Tools without `defer_loading` load into context immediately.
593593* Tools with `defer_loading: true` load only when Claude discovers them through search.
594594* Never set `defer_loading: true` on the tool search tool itself.
595595* Keep your 3–5 most frequently used tools non-deferred so Claude can call them without searching first.
596596
597The computer use and browser use toolsets (`computer_toolset_20260801` and `browser_toolset_20260801`) take `defer_loading` for each member tool inside the entry's `configs` object, not on the entry itself; a request that sets it at the entry level is rejected. Because a toolset defers and expands as a unit, `defer_loading` must resolve to the same value on every enabled member, and when Claude discovers the toolset through search, every enabled member loads at once. See [Client toolsets](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference#client-toolsets) for the `configs` format.
597The computer use and browser use toolsets (`computer_toolset_20260801` and `browser_toolset_20260801`) take `defer_loading` for each member tool inside the entry’s `configs` object, not on the entry itself; a request that sets it at the entry level is rejected. Because a toolset defers and expands as a unit, `defer_loading` must resolve to the same value on every enabled member, and when Claude discovers the toolset through search, every enabled member loads at once. See [Client toolsets](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference#client-toolsets) for the `configs` format.
598598
599599Both tool search variants (`regex` and `bm25`) search tool names, descriptions, argument names, and argument descriptions.
600600
from line 646
646646
647647### Understanding the response
648648
649* **`server_tool_use`:** Claude's call to the tool search tool. The search runs on Anthropic's servers. Never return a `tool_result` for its `srvtoolu_...` ID. The `input` holds the search (`pattern` for the regex variant, `query` for BM25) and might include an optional `limit`, an integer from 1 to 10,000 that caps how many matching tools the search returns (default: 5).
649* **`server_tool_use`:** Claude’s call to the tool search tool. The search runs on Anthropic’s servers. Never return a `tool_result` for its `srvtoolu_...` ID. The `input` holds the search (`pattern` for the regex variant, `query` for BM25) and might include an optional `limit`, an integer from 1 to 10,000 that caps how many matching tools the search returns (default: 5).
650650* **`tool_search_tool_result`:** the search results, in a nested `tool_search_tool_search_result` object. Keep it in the message history as is.
651651* **`tool_references`:** an array of `tool_reference` objects pointing to discovered tools. The API expands these for Claude. You never expand them yourself.
652* **`tool_use`:** Claude's call to a discovered tool. Run it and return a `tool_result` exactly as in standard tool use.
652* **`tool_use`:** Claude’s call to a discovered tool. Run it and return a `tool_result` exactly as in standard tool use.
653653
654The API automatically expands `tool_reference` blocks into full tool definitions before showing them to Claude. You don't need to handle this expansion yourself, as long as you provide all matching tool definitions in the `tools` parameter.
654The API automatically expands `tool_reference` blocks into full tool definitions before showing them to Claude. You don’t need to handle this expansion yourself, as long as you provide all matching tool definitions in the `tools` parameter.
655655
656656### Continuing the conversation
657657
658On the next request, pass the assistant's content back unchanged, including the `server_tool_use` and `tool_search_tool_result` blocks. Add your `tool_result` for the discovered tool in a user message, and send the same `tools` array: the search tool plus every deferred definition. Don't return a `tool_result` for the `srvtoolu_...` ID: the API rejects the request. The API expands `tool_reference` blocks throughout the conversation history, so Claude can reuse discovered tools in later turns without re-searching. A search that matches nothing returns a `tool_search_tool_search_result` with an empty `tool_references` array, not an error.
658On the next request, pass the assistant’s content back unchanged, including the `server_tool_use` and `tool_search_tool_result` blocks. Add your `tool_result` for the discovered tool in a user message, and send the same `tools` array: the search tool plus every deferred definition. Don’t return a `tool_result` for the `srvtoolu_...` ID: the API rejects the request. The API expands `tool_reference` blocks throughout the conversation history, so Claude can reuse discovered tools in later turns without re-searching. A search that matches nothing returns a `tool_search_tool_search_result` with an empty `tool_references` array, not an error.
659659
660660## MCP integration
661661
662If your tools come from MCP servers through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), you don't set `defer_loading` on individual tool definitions. Instead, set it once on the `mcp_toolset` entry's `default_config` for the whole server, or per tool in its `configs`. See [MCP toolset configuration](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#mcp-toolset-configuration).
662If your tools come from MCP servers through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), you don’t set `defer_loading` on individual tool definitions. Instead, set it once on the `mcp_toolset` entry’s `default_config` for the whole server, or per tool in its `configs`. See [MCP toolset configuration](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#mcp-toolset-configuration).
663663
664664## Custom tool search implementation
665665
from line 673
673673}
674674```
675675
676Every tool referenced must have a corresponding tool definition in the top-level `tools` parameter, normally with `defer_loading: true`. This lets you use search methods the built-in variants don't provide, such as embedding-based retrieval, and the API expands the returned `tool_reference` blocks the same way.
676Every tool referenced must have a corresponding tool definition in the top-level `tools` parameter, normally with `defer_loading: true`. This lets you use search methods the built-in variants don’t provide, such as embedding-based retrieval, and the API expands the returned `tool_reference` blocks the same way.
677677
678678<Note>
679 The `tool_search_tool_result` format shown in the [Response format](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#response-format) section is the server-side format used internally by Anthropic's built-in tool search. For custom client-side implementations, always use the standard `tool_result` format with `tool_reference` content blocks as shown in the preceding example.
679 The `tool_search_tool_result` format shown in the [Response format](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#response-format) section is the server-side format used internally by Anthropic’s built-in tool search. For custom client-side implementations, always use the standard `tool_result` format with `tool_reference` content blocks as shown in the preceding example.
680680</Note>
681681
682682For a complete example using embeddings, see the [tool search with embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings) recipe.
from line 734
734734The `error_code` field has four possible values:
735735
736736* `invalid_tool_input`: the search input was invalid, for example a malformed regex pattern or a pattern over the 200-character limit
737* `unavailable`: the search couldn't run, for example because it timed out or the service was unavailable
737* `unavailable`: the search couldn’t run, for example because it timed out or the service was unavailable
738738* `too_many_requests`: rate limit exceeded for tool search operations
739739* `execution_time_exceeded`: the search exceeded its execution time limit
740740
from line 770
770770 ```
771771</Accordion>
772772
773<Accordion title="Claude doesn't find expected tools">
774 **Cause:** The regex pattern doesn't match the tool's name, description, argument names, or argument descriptions.
773<Accordion title="Claude doesn’t find expected tools">
774 **Cause:** The regex pattern doesn’t match the tool’s name, description, argument names, or argument descriptions.
775775
776776 **Debugging steps:**
777777
778778 1. Check tool name, description, argument names, and argument descriptions. Claude searches all of these fields.
779779 2. Test your pattern: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
780 3. Matching is case-insensitive, so casing differences aren't the problem.
780 3. Matching is case-insensitive, so casing differences aren’t the problem.
781781 4. Claude uses broad patterns such as `".*weather.*"`, not exact matches.
782782
783783 **Tip:** Add common keywords to tool descriptions to improve discoverability.
from line 787
787787
788788To learn how `defer_loading` preserves prompt caching, see [Tool use with prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching).
789789
790A tool with `defer_loading: true` can't also carry `cache_control`: the API returns a 400. Put the cache breakpoint on a non-deferred tool.
790A tool with `defer_loading: true` can’t also carry `cache_control`: the API returns a 400. Put the cache breakpoint on a non-deferred tool.
791791
792792## Streaming
793793
794With streaming enabled, you'll receive tool search events as part of the stream:
794With streaming enabled, you’ll receive tool search events as part of the stream:
795795
796796```sse
797797event: content_block_start
from line 841
841841* Write clear, descriptive tool names and descriptions.
842842* Use consistent namespacing in tool names: prefix by service or resource (for example, `github_`, `slack_`) so one search matches the whole group.
843843* Use keywords in descriptions that match how users describe tasks.
844* Add a system prompt section describing available tool categories: "You can search for tools to interact with Slack, GitHub, and Jira."
844* Add a system prompt section describing available tool categories: “You can search for tools to interact with Slack, GitHub, and Jira.”
845845* Monitor which tools Claude discovers to refine your descriptions.
846846
847847## Usage
848848
849Tool search isn't metered as a separate server tool. The response's `usage.server_tool_use` object has no tool search field, and the tool definitions that search loads into context count as input tokens like any other tool definition.
849Tool search isn’t metered as a separate server tool. The response’s `usage.server_tool_use` object has no tool search field, and the tool definitions that search loads into context count as input tokens like any other tool definition.
850850
851851## Next steps
852852
853853<CardGroup cols={2}>
854854 <Card title="Memory tool" icon="brain" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool">
855 Let Claude store and retrieve information across conversations by implementing the memory tool's file operations in your application.
855 Let Claude store and retrieve information across conversations by implementing the memory tool’s file operations in your application.
856856 </Card>
857857
858858 <Card title="Tool reference" icon="book" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference">
No line in this hunk matches that.