跳转到主要内容
工具搜索使您的代理能够通过动态发现和按需加载来处理数百或数千个工具。代理不是将所有工具定义预先加载到上下文窗口中,而是搜索您的工具目录并仅加载它需要的工具。 当工具库扩展时,这种方法解决了两个挑战:
  • 上下文效率: 工具定义可能会消耗上下文窗口的大部分(50个工具可能使用10-20K个令牌),留下较少的空间用于实际工作。
  • 工具选择准确性: 一次加载超过30-50个工具时,工具选择准确性会下降。
工具搜索默认启用。

工具搜索的工作原理

当工具搜索处于活动状态时,工具定义会从上下文窗口中隐藏。代理会收到可用工具的摘要,并在任务需要尚未加载的功能时搜索相关工具。最多五个最相关的工具被默认加载到上下文中,在后续轮次中保持可用。如果对话足够长,SDK会压缩早期消息以释放空间,之前发现的工具可能会被移除,代理会根据需要再次搜索。 工具搜索在Claude首次发现工具时增加一个额外的往返(搜索步骤),但对于大型工具集,这被每个轮次中较小的上下文所抵消。对于少于约10个工具的情况,预先加载所有工具通常更快。 有关底层API机制的详细信息,请参阅API中的工具搜索
工具搜索在Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5及更新的模型上受支持;有关当前列表,请参阅API文档中的模型兼容性。在Google Cloud的Agent Platform上,最低支持的模型是Claude Sonnet 4.5和Claude Opus 4.5。
工具搜索默认启用。在Google Cloud的Agent Platform上默认禁用,其中支持Claude Sonnet 4.5及更高版本以及Claude Opus 4.5及更高版本。当ANTHROPIC_BASE_URL指向非第一方主机时也会禁用,因为大多数代理不转发tool_reference块。您可以使用ENABLE_TOOL_SEARCH环境变量覆盖任一默认值: 设置CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS会保持工具搜索关闭,ENABLE_TOOL_SEARCH无法覆盖它。该变量会删除defer_loading工具定义和tool_reference内容块所需的beta标头。 工具搜索适用于所有已注册的工具,无论它们来自远程MCP服务器还是自定义SDK MCP服务器。使用auto时,阈值基于所有服务器上所有工具定义的组合大小。 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。有关结果消息的更多信息,请参阅处理结果 ENABLE_TOOL_SEARCH设置为"false"会禁用工具搜索,并在每个轮次上将所有工具定义加载到上下文中。这消除了搜索往返,当工具集很小(少于约10个工具)且定义在上下文窗口中舒适地适配时,这可能会更快。

优化工具发现

搜索机制将查询与工具名称和描述进行匹配。像search_slack_messages这样的名称比query_slack更广泛地出现在各种请求中。具有特定关键字的描述(“按关键字、频道或日期范围搜索Slack消息”)比通用描述(“查询Slack”)匹配更多查询。 您还可以添加一个系统提示部分,列出可用的工具类别。这为代理提供了关于可以搜索什么类型工具的上下文。通过 TypeScript 中的 systemPrompt 选项或 Python 中的 system_prompt 传递文本,使用带有 appendclaude_code 预设,这会将您的文本添加到预设的提示中,而不是替换它:
有关完整的系统提示选项集,请参阅修改系统提示

限制

  • 最大工具数: 您的目录中最多10,000个工具
  • 搜索结果: 默认每次搜索返回最多五个最相关的工具
  • 模型支持: Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5及更新版本;请参阅API文档中的模型兼容性了解当前列表。在Google Cloud的Agent Platform上,支持Claude Sonnet 4.5及更新版本以及Claude Opus 4.5及更新版本。