- 上下文效率: 工具定义可能会消耗上下文窗口的大部分(50个工具可能使用10-20K个令牌),留下较少的空间用于实际工作。
- 工具选择准确性: 一次加载超过30-50个工具时,工具选择准确性会下降。
工具搜索的工作原理
工具搜索默认处于启用状态,配置工具搜索中列出的情况除外。 当工具搜索处于活动状态时,工具定义会从上下文窗口中隐藏。代理会收到可用工具的摘要,并在任务需要尚未加载的功能时搜索相关工具。最多五个最相关的工具被默认加载到上下文中,在后续轮次中保持可用,直到SDK压缩代理发现它们的消息。在该压缩之后,代理在下次需要这些工具时会再次搜索它们。 工具搜索在Claude每次搜索工具时增加一个额外的往返,但对于大型工具集,这被每个轮次中较小的上下文所抵消。对于少于约10个工具且其定义能够舒适地放入上下文窗口的情况,预先加载所有工具通常更快。 有关底层API机制的详细信息,请参阅API中的工具搜索。Microsoft Foundry上的工具搜索不受支持,部署在Azure上的部署会在服务器端拒绝它:SDK检测到拒绝并为该部署改为预先加载工具定义。
ENABLE_TOOL_SEARCH无法覆盖此行为,因为拒绝来自部署本身。配置工具搜索
工具搜索默认启用。对于SDK的不支持模型列表中的模型,SDK会改为预先加载工具定义,任何ENABLE_TOOL_SEARCH值都无法覆盖此行为。在Google Cloud的Agent Platform上,SDK根据模型代数决定:
- Claude Opus 4.5、Sonnet 4.5、Haiku 4.5及更高版本:工具搜索默认启用。
- 早期Agent Platform模型:SDK预先加载工具定义,因为它们的服务堆栈拒绝所需的beta标头。
ENABLE_TOOL_SEARCH无法覆盖此行为。
ENABLE_TOOL_SEARCH。
当ANTHROPIC_BASE_URL指向非第一方主机时,SDK也会禁用工具搜索,因为大多数代理不转发tool_reference块。您可以使用ENABLE_TOOL_SEARCH环境变量覆盖该默认值:
设置
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS会保持工具搜索关闭。您无法通过自己设置ENABLE_TOOL_SEARCH来覆盖它。在Claude Code v2.1.227或更高版本上,您的组织可以通过托管设置在设置了此变量的情况下保持工具搜索启用。在获得HIPAA配置的会话中,工具搜索处于关闭状态,ENABLE_TOOL_SEARCH和托管设置都无法将其重新启用。禁用预发布功能涵盖了覆盖应用的位置以及变量删除的内容。
工具搜索适用于所有已注册的工具,无论它们来自远程MCP 服务器还是自定义SDK MCP 服务器。当您使用auto时,SDK会计算工具搜索可以延迟的每个定义,针对一个组合阈值:来自任何服务器的未标记为alwaysLoad的每个MCP工具,加上按需加载的内置工具。SDK会预先加载核心内置工具(如Bash、Read和Edit),不会将其计入阈值。您的某个插件中的mod也可以延迟某个工具或预先加载它,这会改变该计数。
在query()上的env选项中设置值。在TypeScript中,env替换子进程环境,因此展开...process.env以保持继承的变量。在Python中,env合并到继承的环境之上。此示例连接到公开许多工具的远程MCP 服务器,使用通配符预先批准所有工具,并使用auto:5,以便当工具搜索可以延迟的定义达到上下文窗口的5%时激活工具搜索:
https://tools.example.com/mcp替换为您自己的MCP 服务器的URL。成功时,结果文本会打印到控制台。
因为这是一个单次query()调用,SDK在产生错误结果后会抛出异常,所以该示例将循环包装在try块中。要查看运行失败的原因,请检查循环内结果消息的subtype,例如error_during_execution。有关结果消息的更多信息,请参阅处理结果。
优化工具发现
搜索机制将查询与工具名称和描述进行匹配。像search_slack_messages这样的名称比query_slack更广泛地出现在各种请求中。具有特定关键字的描述(“按关键字、频道或日期范围搜索Slack消息”)比通用描述(“查询Slack”)匹配更多查询。
您还可以添加一个系统提示部分,列出可用的工具类别。这为代理提供了关于可以搜索什么类型工具的上下文。通过 TypeScript 中的 systemPrompt 选项或 Python 中的 system_prompt 传递文本,使用带有 append 的 claude_code 预设,这会将您的文本添加到预设的提示中,而不是替换它:
限制
- 最大工具数: 您的目录中最多10,000个工具
- 搜索结果: 默认每次搜索返回最多五个最相关的工具
- 模型支持: Opus 4、Sonnet 4、Haiku 4.5及更新的模型;在Google Cloud的Agent Platform上为Opus 4.5、Sonnet 4.5、Haiku 4.5及更新的模型。在更早的模型上,SDK会预先加载工具定义,如配置工具搜索中所述。
相关文档
- API中的工具搜索:工具搜索的完整API文档,包括自定义实现
- 连接MCP服务器:通过MCP服务器连接到外部工具
- 自定义工具:使用SDK MCP服务器构建您自己的工具
- TypeScript SDK参考:完整API参考
- Python SDK参考:完整API参考