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 上默认启用代理或部分平台可能回退为 upfronttrue强制启用 Tool Searchfalse禁用所有工具 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. }写工具描述时可以抓住五点工具名带领域和动作例如github_create_issue。description 说明触发场景而不只是动作。input_schema 的字段也写清楚含义。一个工具只做一件事避免万能工具。高频工具少量alwaysLoad长尾工具交给搜索。未来工具描述会越来越像搜索文档。写得越具体Agent 越容易在正确任务里找到它。Codex 也在走同一条路Tool Search 不是 Claude 独有方向。OpenAI Codex CLI 和 OpenAI Agents SDK 也在解决同一个问题工具 schema 太多不能全部塞进上下文。差别在实现层级。维度Claude Tool SearchOpenAI Codex / Agents SDK延迟加载字段defer_loading: truedefer_loading: true搜索能力tool_search_tool_regex/tool_search_tool_bm25tool_search/ToolSearchTool()实现位置Messages API 协议层Responses API / SDK / CLI 层特殊结构server_tool_use、tool_reference、tool_search_tool_result主要沿 function calling 体系组织方式MCP server alwaysLoadtool_namespaceClaude 把能力下沉到 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 架构拆解别再把向量库当唯一记忆系统