Tool Search Tool：让大规模工具库“按需加载”

当你的系统里有上百甚至上千个工具时，把所有工具定义一次性塞进上下文，会带来两个典型问题：既浪费上下文窗口（50 个工具就可能吃掉 1–2 万 token），也会让模型在 30–50 个工具以上更容易选错工具。Tool Search Tool 的思路是：先只暴露“搜索工具的工具”，其余工具标记为延迟加载；模型需要时先搜索，再把最相关的少量工具定义加载进来使用。

核心机制（7 步）

• 请求里先放入工具搜索工具（Regex 或 BM25 版本）+ 少量常用非延迟工具
• 其余工具定义加上 defer_loading: true（不立即进上下文）
• 模型需要更多工具时，先调用 tool search
• 服务端返回 3–5 个最相关的 tool_reference
• 这些引用会被自动展开成完整工具定义
• 模型再从“已发现”的工具里选择并调用
• 这样既省上下文，又保持工具选择准确率

两种搜索方式怎么选

• Regex 版（tool_search_tool_regex_20251119）：查询是 Python 正则，不是自然语言；适合你希望可控匹配（如 get_.*_data、(?i)slack）。限制：模式最长 200 字符。
• BM25 版（tool_search_tool_bm25_20251119）：查询用自然语言；更适合“我想做什么”式的描述。

两种方式都会搜索：工具名、描述、参数名、参数描述。

延迟加载的最佳实践

• 工具搜索工具本身不要设置 defer_loading: true
• 保留 3–5 个最常用工具为非延迟（提升命中与体验）
• 工具命名与描述尽量贴近用户常用说法（提升可检索性）
• 适合场景：工具 >10 个、工具定义 >10K token、工具选择准确率下降、MCP 多服务器（200+ 工具）等
• 不太适合：工具 <10 个且几乎每次都要用、工具定义非常短

响应与错误处理要点

• 响应里会出现 server_tool_use（触发工具搜索）与 tool_search_tool_result（返回引用列表）
• 常见 400 错误：
• 全部工具都 deferred：至少要有 1 个非延迟工具
• 引用的工具缺少定义：tool_reference 指向的工具必须在顶层 tools 里有对应定义（并通常设为 deferred）
• 工具搜索执行期错误（仍返回 200）：如 invalid_pattern、pattern_too_long、too_many_requests、unavailable

与 MCP、缓存、流式的配合

• 可与 MCP toolset 结合：用 default_config.defer_loading 控制 MCP 工具默认延迟加载，并可对特定工具覆盖
• 支持 prompt caching：已发现的工具可在后续轮次复用，不必每次重新搜索
• 流式返回会把搜索调用与结果作为事件发出，便于前端展示“正在搜索/已找到工具”

原文链接：https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

#工具调用 #Agent开发 #上下文优化 #MCP #API设计

Claude API Docs

Tool search tool

Claude API Documentation