Claude Tool Search 深度拆解：延迟加载、工具引用和与 Codex 对比

Claude Tool Search 解决的不是一个小开关问题，而是 Agent 工具规模化后的上下文管理问题。

导语

Agent 接的工具越多，能力看起来越强。但过了某个点，工具本身会变成噪音。

一个 coding agent 同时接 GitHub、Slack、Jira、Sentry、Grafana、PagerDuty，再加几个内部 MCP server，很容易暴露上百个工具。传统做法是启动会话时把所有工具 schema 全塞进上下文。

这当然直接，但代价也很硬：

• 工具描述吃掉大量 token。
• 工具越多，模型越容易选错。
• 每一轮对话都背着一堆没用到的 schema 走。

Tool Search 要解决的就是这个问题。它不是让 Agent 变聪明的魔法，而是把工具组织方式从“全量塞进上下文”改成“先建索引，再按需加载”。

图：工具上下文从全量堆叠变成可检索目录

Upfront Loading 的问题：工具列表会挤占思考空间

没有 Tool Search 时，工具调用的机制很朴素：请求里带上所有工具定义，模型在上下文里直接看到它们。

工具少时没问题。十几个工具以内，模型通常还能稳定选择。到了几十个甚至上百个工具，schema 本身就会变成负担。

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        }
      }
    },
    {
      "name": "search_github_issues",
      "description": "Search GitHub issues by keyword and repository",
      "input_schema": { "...": "..." }
    }
  ]
}

这类 upfront loading 有两个隐藏成本。

第一是 token 成本。工具定义越详细，消耗越明显。

第二是选择成本。模型在一堆相似工具之间做决策，错误率会上升。很多 MCP server 的工具名还很接近，例如 list、get、search、create、update 一组一组出现，语义差异全靠 description 解释。

所以问题不是“模型不知道怎么调用工具”，而是它一开始看到的工具太多。

API 层机制：defer_loading 只是入口

Tool Search 的第一步，是给工具加 defer_loading: true。

{
  "name": "search_github_issues",
  "description": "Search GitHub issues by keyword and repository",
  "input_schema": { "...": "..." },
  "defer_loading": true
}

这个字段经常被误解。它不是说客户端不用发送完整工具定义。相反，请求里的 tools 数组仍然要包含完整定义，因为 API 后面需要用它展开引用。

defer_loading 控制的是另一件事：这个工具的完整 schema 是否进入模型初始可见的工具上下文。

也就是说：

状态	客户端请求里有没有完整定义	模型初始上下文里有没有完整 schema
普通工具	有	有
defer 工具	有	没有
搜索命中后	有	被展开注入

这个设计保留了协议完整性，也避免模型一开始被大量工具淹没。

搜索链路：从 server_tool_use 到 tool_reference

当 Claude 判断当前任务需要某个延迟加载的工具时，它不会直接发普通 tool_use。它会先发起一次服务端工具搜索，也就是 server_tool_use。

{
  "type": "server_tool_use",
  "id": "srvtoolu_01ABC123",
  "name": "tool_search_tool_regex",
  "input": {
    "pattern": "weather"
  }
}

这不是客户端自己的 MCP tool，也不应该由客户端返回普通 tool_result。它是 Anthropic API 侧的 server-side tool。

搜索完成后，响应里会出现 tool_search_tool_result，里面放的是 tool_reference：

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [
      { "type": "tool_reference", "tool_name": "get_weather" }
    ]
  }
}

注意，这里返回的不是完整 schema，而是指针。

API 会拿这个指针去请求里的 tools 数组里找同名定义，然后自动展开。展开之后，Claude 才能发正式的普通 tool_use。

完整流程可以概括为：

图：Tool Search 先返回工具引用，再展开完整 schema 发起正式调用

这套链路的关键，是工具 schema 仍然存在，但不再默认占据模型注意力。

图：延迟加载的关键不是丢掉 schema，而是把 schema 放到需要时再展开

Claude Code 层：ENABLE_TOOL_SEARCH 控制策略

API 层提供机制，Claude Code 决定什么时候用。

实际使用中，最常见的控制入口是 ENABLE_TOOL_SEARCH：

值	行为
未设置	官方 endpoint 上默认启用；代理或部分平台可能回退为 upfront
true	强制启用 Tool Search
false	禁用，所有工具 upfront 加载
auto	工具定义超过上下文窗口一定比例时启用
auto:N	自定义阈值，例如 auto:5

工具少时，禁用 Tool Search 可能更快，因为少了一轮搜索。工具多时，延迟加载更有价值。

还有一个容易被忽略的配置是 alwaysLoad。它允许某个 MCP server 的工具始终 upfront 加载：

{
  "mcpServers": {
    "essential-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@org/essential-mcp"],
      "alwaysLoad": true
    }
  }
}

这个配置适合少量高频工具。用多了，就会把 Tool Search 的收益抵消掉。

代理兼容性：协议化能力的代价

Claude 的方案很协议化。server_tool_use、tool_reference、tool_search_tool_result 都是特殊 block。

好处是行为清晰，API 可以统一展开引用。

坏处也明显：中间代理必须认识这些 block。

如果 ANTHROPIC_BASE_URL 指向 one-api、LiteLLM 或公司内部网关，而代理只支持 text、tool_use、tool_result 这些常见类型，就可能出现：

• unknown content block type
• 代理把未知 block 丢掉
• 转 OpenAI 格式时无法表达
• 下一轮上下文断裂

这也是很多配置工具提供“启用 Tool Search”开关的原因。它本质上是在“更省上下文”和“更兼容代理”之间做选择。

工具描述怎么写，决定能不能被搜到

Tool Search 让工具变成索引，但索引质量取决于工具名和描述。

模糊描述很危险：

{
  "name": "mcp__github__tool1",
  "description": "Does GitHub stuff"
}

这类工具很难在 issue、PR、workflow、release 等具体任务里被正确召回。

更好的描述要包含领域、动作、触发场景和关键参数：

{
  "name": "mcp__github__create_issue",
  "description": "Create a new issue in a GitHub repository. Use this when the user wants to report a bug, request a feature, or track a task. Requires owner, repo, title, and optional body, labels, assignees."
}

写工具描述时，可以抓住五点：

1. 工具名带领域和动作，例如 github_create_issue。
2. description 说明触发场景，而不只是动作。
3. input_schema 的字段也写清楚含义。
4. 一个工具只做一件事，避免万能工具。
5. 高频工具少量 alwaysLoad，长尾工具交给搜索。

未来工具描述会越来越像搜索文档。写得越具体，Agent 越容易在正确任务里找到它。

Codex 也在走同一条路

Tool Search 不是 Claude 独有方向。

OpenAI Codex CLI 和 OpenAI Agents SDK 也在解决同一个问题：工具 schema 太多，不能全部塞进上下文。

差别在实现层级。

维度	Claude Tool Search	OpenAI Codex / Agents SDK
延迟加载字段	defer_loading: true	defer_loading: true
搜索能力	tool_search_tool_regex
/tool_search_tool_bm25	tool_search
/ToolSearchTool()
实现位置	Messages API 协议层	Responses API / SDK / CLI 层
特殊结构	server_tool_use
、tool_reference、tool_search_tool_result	主要沿 function calling 体系
组织方式	MCP server +alwaysLoad	tool_namespace

Claude 把能力下沉到 API block。只要客户端和代理支持这些 block，不同客户端可以获得较一致的行为。

OpenAI 更像框架层能力。它对现有 function calling 基础设施侵入更小，但一致性更多依赖 SDK 和运行时实现。

所以正确结论不是“Claude 有，OpenAI 没有”，而是：当工具数量超过上下文舒适承载范围时，延迟加载加运行时搜索正在成为共识。

更大的趋势：能力不该全塞进上下文

Tool Search 只是工具层的一个实现。往上看，skills、agents、memory 也会遇到同样的问题。

当一个 Agent 拥有几十个 skills，每个 skill 都有 system prompt、examples、专属工具和约束时，全部 upfront 加载同样会把上下文挤满。

更合理的架构是：

用户需求 -> 意图识别 / 搜索 -> 加载相关能力 -> 执行任务

工具层叫 Tool Search，技能层可能叫 progressive skill loading，记忆层可能叫 memory retrieval。本质都是同一句话：

能力规模超过上下文容量后，能力必须被组织成索引，而不是全部放进模型短期记忆里。

结语

Tool Search 的核心价值，不是省几个 token，也不是多一个环境变量。

它把 Agent 的工具上下文从仓库模式改成索引模式。仓库模式要求模型一开始看见所有工具；索引模式允许模型先理解任务，再按需找到工具。

MCP 生态越膨胀，这个差异越关键。未来写工具的人，不只是写函数接口，也是在写可被 Agent 搜到、选对、调用稳的能力说明。

这会成为 Agent 工程里很基础的一门手艺。

推荐阅读

Agent 评测别把「调优 Loop」 跑成「刷题 Loop」

代码不是 AI 编程的最终资产，AI Coding 真正该存的是 Checkpoint

长程 Agent 的三类硬约束

企业 Agent 为什么难落地：组织、数据和流程才是真卡点

Agent Memory 架构拆解：别再把向量库当唯一记忆系统