当代理需要管理数百个工具时，工具搜索（Tool Search）能按需动态加载 3-5 个最相关的工具，避免上下文被全部工具定义撑满。默认开启，可通过 ENABLE_TOOL_SEARCH 环境变量配置模式（true/auto/auto:N/false），auto 模式会在工具定义超过上下文 10% 时自动激活。仅支持 Claude Sonnet 4 及以上和 Opus 4 及以上模型。

Claude Code 工具搜索（Tool Search）配置指南

工具搜索使代理能与成百上千个工具协作，通过按需动态发现和加载工具来实现。不需要一开始就把所有工具定义塞入上下文窗口，代理会搜索工具目录，只加载它需要的工具。

这一方案解决了工具库扩大时的两个难题：

上下文效率： 工具定义会消耗大量上下文窗口（50个工具大约占 10-20K tokens），留给实际工作的空间就少了。
工具选择精度： 同时加载超过 30-50 个工具时，选择工具的准确度会下降。

工具搜索默认开启。本页介绍工作原理、配置方法以及如何优化工具发现。

工作原理

开启工具搜索后，工具定义不会进入上下文窗口。代理会收到可用工具的摘要，当任务需要某个尚未加载的能力时，它会搜索相关工具。3-5 个最相关的工具会被加载到上下文，并在后续轮次中保持可用。如果对话足够长，SDK 会压缩早期消息来释放空间，之前发现的工具可能被移除，代理在需要时会再次搜索。

工具搜索在 Claude 首次发现工具时会多一次往返（搜索步骤），但对于大型工具集，每次轮次的上下文更小，总体还是节省的。工具少于约 10 个时，一次性全部加载通常更快。

关于底层 API 机制，详见 API 中的工具搜索。

工具搜索需要 Claude Sonnet 4 或更高版本，或者 Claude Opus 4 或更高版本。Haiku 模型不支持工具搜索。

配置工具搜索

工具搜索默认开启。在 Vertex AI 上默认关闭，Vertex AI 上支持 Claude Sonnet 4.5 及更高版本、Claude Opus 4.5 及更高版本。当 ANTHROPIC_BASE_URL 指向非第一方主机时也会关闭，因为大多数代理不会转发 tool_reference 块。你可以用 ENABLE_TOOL_SEARCH 环境变量覆盖以上默认行为：

值	行为
(未设置)	工具搜索开启。工具定义被延迟，按需发现。在 Vertex AI 或非第一方 `ANTHROPIC_BASE_URL` 上回退为一次性加载。
`true`	始终开启。SDK 发送 beta 头部，即使在 Vertex AI 和通过代理时也一样。在早于 Sonnet 4.5 或 Opus 4.5 的 Vertex AI 模型上，或在不支持 `tool_reference` 块的代理上，请求会失败。
`auto`	检查所有工具定义的总 token 数占模型上下文窗口的比例。如果超过 10%，工具搜索激活；如果低于 10%，所有工具正常加载到上下文。
`auto:N`	与 `auto` 相同，但使用自定义百分比。`auto:5` 表示当工具定义超过上下文窗口的 5% 时激活。数值越小激活越早。
`false`	关闭工具搜索。所有工具定义在每次轮次都被加载到上下文。

工具搜索应用于所有已注册的工具，包括来自远程 MCP 服务器和自定义 SDK MCP 服务器的工具。使用 auto 时，阈值基于所有工具定义的总大小。

在 query() 的 env 选项中设置该值。下面示例连接到暴露了许多工具的远程 MCP 服务器，使用通配符预批准所有工具，并设置 auto:5 以便在工具定义超过上下文窗口 5% 时激活工具搜索：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when tools exceed 5% of context
        },
    )

    async for message in query(
        prompt="Find and run the appropriate database query",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

将 ENABLE_TOOL_SEARCH 设为 "false" 会关闭工具搜索，所有工具定义在每次轮次都加载到上下文。这会去掉搜索的额外往返，在工具集较小（约少于 10 个）且定义轻松塞入上下文窗口时，可能更快。

优化工具发现

搜索机制会匹配查询与工具名称和描述。名称像 search_slack_messages 比 query_slack 能覆盖更广泛的请求。带有具体关键字的描述（“Search Slack messages by keyword, channel, or date range”）比泛泛的描述（“Query Slack”）能匹配更多查询。

你也可以在系统提示中添加一段列出可用工具类别的内容，这能让代理知道有哪些工具可以搜：

You can search for tools to interact with Slack, GitHub, and Jira.

限制

最大工具数： 目录中最多 10,000 个工具
搜索结果： 每次搜索返回 3-5 个最相关的工具
模型支持： Claude Sonnet 4 及更高版本、Claude Opus 4 及更高版本（不支持 Haiku）

常见问题

工具搜索支持哪些模型？

工具搜索需要 Claude Sonnet 4 或更高版本，或者 Claude Opus 4 或更高版本。Haiku 模型不支持工具搜索。

如何关闭工具搜索？

将 ENABLE_TOOL_SEARCH 环境变量设为 "false" 即可关闭。例如在 query() 的 env 中设置 ENABLE_TOOL_SEARCH: "false"。

`auto:5` 是什么意思？

auto:5 表示当所有工具定义的总 token 数超过模型上下文窗口的 5% 时，工具搜索被激活。数值越小，工具搜索越容易启动；数值越大，越倾向于一次性加载全部工具。

Claude Code 工具搜索（Tool Search）配置指南 #

工作原理 #

配置工具搜索 #

优化工具发现 #

限制 #

相关文档 #

常见问题 #

工具搜索支持哪些模型？ #

如何关闭工具搜索？ #

auto:5 是什么意思？ #