Scale to many tools with tool search changedagent-sdk/tool-search
Nearest release: v2.1.299, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 14 Oct 2026 02:42 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+76added
Lines−80removed
From line
19
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits12to this page, all time
The whole hunk
from line 19, old and new numbered
/
from line 19
1919
2020For details on the underlying API mechanism, see [Tool search in the API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool).
2121
22<Note>
23 Tool search isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), which reject it server-side: the SDK detects the rejection and loads tool definitions upfront for that deployment instead. [`ENABLE_TOOL_SEARCH`](#configure-tool-search) can't override this, since the rejection comes from the deployment itself.
24</Note>
22> [!NOTE]
23>
24> Tool search isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), which reject it server-side: the SDK detects the rejection and loads tool definitions upfront for that deployment instead. [`ENABLE_TOOL_SEARCH`](#configure-tool-search) can't override this, since the rejection comes from the deployment itself.
2525
2626## Configure tool search
2727
from line 48
4848
4949Set the value in the `env` option on `query()`. In TypeScript, `env` replaces the subprocess environment, so spread `...process.env` to keep inherited variables. In Python, `env` is merged on top of the inherited environment. This example connects to a remote MCP server that exposes many tools, pre-approves all of them with a wildcard, and uses `auto:5` so tool search activates when the definitions it can defer reach 5% of the context window:
5050
51<CodeGroup>
52 ```typescript TypeScript theme={null}
53 import { query } from "@anthropic-ai/claude-agent-sdk";
51```typescript TypeScript theme={null}
52import { query } from "@anthropic-ai/claude-agent-sdk";
5453
55 try {
56 for await (const message of query({
57 prompt: "Find and run the appropriate database query",
58 options: {
59 mcpServers: {
60 "enterprise-tools": {
61 // Connect to a remote MCP server
62 type: "http",
63 url: "https://tools.example.com/mcp"
64 }
65 },
66 allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
67 env: {
68 ...process.env, // env replaces the subprocess environment, so keep inherited variables
69 ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
54try {
55 for await (const message of query({
56 prompt: "Find and run the appropriate database query",
57 options: {
58 mcpServers: {
59 "enterprise-tools": {
60 // Connect to a remote MCP server
61 type: "http",
62 url: "https://tools.example.com/mcp"
7063 }
64 },
65 allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
66 env: {
67 ...process.env, // env replaces the subprocess environment, so keep inherited variables
68 ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
7169 }
72 })) {
73 if (message.type === "result" && message.subtype === "success") {
74 console.log(message.result);
75 }
7670 }
77 } catch (error) {
78 // A single-shot query() throws after yielding an error result
79 console.log(`Session ended with an error: ${error}`);
71 })) {
72 if (message.type === "result" && message.subtype === "success") {
73 console.log(message.result);
74 }
8075 }
81 ```
76} catch (error) {
77 // A single-shot query() throws after yielding an error result
78 console.log(`Session ended with an error: ${error}`);
79}
80```
8281
83 ```python Python theme={null}
84 import asyncio
85 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
82```python Python theme={null}
83import asyncio
84from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
8685
8786
88 async def main():
89 options = ClaudeAgentOptions(
90 mcp_servers={
91 "enterprise-tools": {
92 "type": "http",
93 "url": "https://tools.example.com/mcp",
94 }
95 },
96 allowed_tools=[
97 "mcp__enterprise-tools__*"
98 ], # Wildcard pre-approves all tools from this server
99 env={
100 "ENABLE_TOOL_SEARCH": "auto:5" # Activate tool search when deferrable definitions reach 5% of context
101 },
102 )
87async def main():
88 options = ClaudeAgentOptions(
89 mcp_servers={
90 "enterprise-tools": {
91 "type": "http",
92 "url": "https://tools.example.com/mcp",
93 }
94 },
95 allowed_tools=[
96 "mcp__enterprise-tools__*"
97 ], # Wildcard pre-approves all tools from this server
98 env={
99 "ENABLE_TOOL_SEARCH": "auto:5" # Activate tool search when deferrable definitions reach 5% of context
100 },
101 )
103102
104 try:
105 async for message in query(
106 prompt="Find and run the appropriate database query",
107 options=options,
108 ):
109 if isinstance(message, ResultMessage) and message.subtype == "success":
110 print(message.result)
111 except Exception as error:
112 # A single-shot query() raises after yielding an error result
113 print(f"Session ended with an error: {error}")
103 try:
104 async for message in query(
105 prompt="Find and run the appropriate database query",
106 options=options,
107 ):
108 if isinstance(message, ResultMessage) and message.subtype == "success":
109 print(message.result)
110 except Exception as error:
111 # A single-shot query() raises after yielding an error result
112 print(f"Session ended with an error: {error}")
114113
115114
116 asyncio.run(main())
117 ```
118</CodeGroup>
115asyncio.run(main())
116```
119117
120118To run this example, replace `https://tools.example.com/mcp` with the URL of your own MCP server. On success the result text prints to the console.
121119
from line 125
127125
128126You can also add a system prompt section listing available tool categories. This gives the agent context about what kinds of tools are available to search for. Pass the text in the `systemPrompt` option of `query()` in TypeScript, or `system_prompt` in Python. Use the `claude_code` preset with `append`, which adds your text to the preset's prompt instead of replacing it:
129127
130<CodeGroup>
131 ```typescript TypeScript theme={null}
132 options: {
133 systemPrompt: {
134 type: "preset",
135 preset: "claude_code",
136 append: "You can search for tools to interact with Slack, GitHub, and Jira."
137 }
128```typescript TypeScript theme={null}
129options: {
130 systemPrompt: {
131 type: "preset",
132 preset: "claude_code",
133 append: "You can search for tools to interact with Slack, GitHub, and Jira."
138134 }
139 ```
135}
136```
140137
141 ```python Python theme={null}
142 options = ClaudeAgentOptions(
143 system_prompt={
144 "type": "preset",
145 "preset": "claude_code",
146 "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
147 }
148 )
149 ```
150</CodeGroup>
138```python Python theme={null}
139options = ClaudeAgentOptions(
140 system_prompt={
141 "type": "preset",
142 "preset": "claude_code",
143 "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
144 }
145)
146```
151147
152148For the full set of system prompt options, see [Modifying system prompts](/docs/en/agent-sdk/modifying-system-prompts).
153149
No line in this hunk matches that.