Skip to main content

Tool Search Tool：让大规模工具库“按需加载”当你的系统里有上百甚至上千个工具时，把所有工具定义一次性塞进上下文，会带来两个典型问题：既浪费上下文窗口（50 个工具就可能吃掉 1–2 万 token），也会让模型在 30–50 个工具以上更容易选错工具

  1. 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
    Tool search tool
    Claude API Documentation
1px