高级工具调用：让智能体按需发现、程序化编排并正确使用工具

精读对象：Introducing advanced tool use on the Claude Developer Platform
作者：Bin Wu 等
发布机构：Anthropic
发布日期：2025 年 11 月 24 日
报告日期：2026 年 9 月 18 日
文章类型：产品能力说明与智能体工具架构指南
适合读者：智能体开发者、MCP 平台维护者、AI 基础设施工程师、技术负责人

1.核心结论

这篇文章讨论的表面问题是“如何让 Claude 使用更多工具”，实际问题是：当工具数量、返回数据和参数复杂度同时增长时，传统的自然语言工具调用会把上下文窗口变成系统瓶颈。

Anthropic 提出的三项能力分别处理三个不同位置的冗余：

能力	处理的瓶颈	核心机制
Tool Search Tool	所有工具定义预先进入上下文	只在需要时搜索并加载相关工具定义
Programmatic Tool Calling	每次工具调用都经过模型，且中间结果全部进入上下文	让模型编写代码，由代码调用、过滤和聚合工具结果
Tool Use Examples	JSON Schema 只能表达结构，不能充分表达使用惯例	在工具定义中加入经过 Schema 校验的输入示例

三者可以统一理解为一种上下文分层策略：

工具目录留在上下文之外，按需检索
中间数据留在执行环境中，先计算再摘要
使用惯例以少量示例进入工具定义
模型上下文只保留当前决策真正需要的信息

文章最值得保留的原则不是某个 Claude API 字段，而是：**把确定性、重复性、数据密集型的工作交给检索和代码，把语义判断与计划保留给模型。**这能够减少模型调用和上下文占用，也使循环、条件、并发与错误处理从隐式自然语言推理变成可检查的程序逻辑。

但文章中的效果数据主要来自 Anthropic 内部评测。它没有披露完整样本、方差、置信区间、失败样本分布和成本口径，因此可以证明这些机制在特定测试中有效，不能证明相同提升会出现在所有工具库或业务任务中。

2.传统工具调用为什么难以扩展

2.1 工具定义会在任务开始前占用上下文

传统方式通常把每个工具的名称、描述和输入 Schema 都放进模型上下文。工具较少时，这种做法直接且透明；连接多个 MCP 服务器后，定义本身可能在用户提出问题前就占用数万 Token。

原文给出的五服务器示例包含 58 个工具，定义约占 55K Token；再加入 Jira 等服务器后可能接近 100K。Anthropic 还称见过优化前的工具定义占用 134K Token。

这个问题不只是成本。工具越多、名称越相似，模型越容易选错工具或混淆参数。例如，面向单个用户发送通知与面向频道发送通知，可能只有工具名中的一个词不同。

2.2 中间结果会挤占真正需要的证据

顺序工具调用通常遵循下面的循环：

模型决定调用工具
→ 工具返回完整结果
→ 结果进入模型上下文
→ 模型解析结果并决定下一次调用

如果任务涉及大型日志、数千行费用记录或多张数据表，大量中间数据会进入上下文。即使最终只需要一个聚合值，模型仍要读取原始记录。多轮调用还会重复触发模型推理，增加延迟和成本。

2.3 Schema 合法不等于业务调用正确

JSON Schema 能限制字段类型、必填项和枚举值，却不一定能说明：

• 日期应使用哪种格式；
• 业务 ID 遵循什么规则；
• 哪些可选字段应同时出现；
• 不同优先级对应什么 SLA；
• 什么时候应调用两个相似工具中的哪一个。

一个调用可以通过 Schema 校验，却仍违反 API 的隐含约定。文章因此把“结构合法性”和“使用正确性”分开处理。

3.Tool Search Tool：按需加载工具定义

3.1 工作机制

开发者仍把完整工具定义随请求发送给 API，但用 defer_loading: true 标记不需要立即进入模型上下文的工具。模型起初只看到 Tool Search Tool 和少量常用工具；当任务需要额外能力时，再搜索工具目录，返回匹配工具的引用，并把对应完整定义展开到当前对话中。

这里容易产生一个误解：**延迟加载减少的是模型上下文，不是客户端发送给 API 的工具目录。**当前官方文档明确说明，所有工具定义仍须包含在请求的 tools 数组中，API 需要它们执行搜索和展开引用。

官方提供两种搜索方式：

• Regex：模型生成 Python 正则表达式，在工具名、描述、参数名和参数描述中匹配；
• BM25：模型用自然语言查询进行关键词相关性检索。

也可以实现自定义搜索，例如使用向量嵌入，再返回标准工具引用。

3.2 为什么可以保留提示缓存

延迟工具不会进入初始系统提示前缀；只有被搜索到的定义才追加到对话中。因此，核心系统提示和常用工具仍可维持稳定前缀，避免因为大型工具目录变化而破坏提示缓存。

3.3 适用条件

原文建议在以下情况采用工具搜索：

• 工具数量达到 10 个以上；
• 工具定义超过 10K Token；
• 多个 MCP 服务器聚合在一起；
• 已经观察到工具选择准确率下降。

工具少于 10 个、定义紧凑，或每次任务都会使用全部工具时，增加搜索步骤可能只会带来额外延迟。

3.4 主要风险

工具搜索把“从所有工具中选择”改成“先检索，再从候选集中选择”。它降低了第二步的难度，却增加了第一步的召回风险：需要的工具如果没有被搜到，模型根本看不到它。

常见失败包括：

• 工具名称和描述没有使用用户会说的词；
• Regex 过窄或语法错误；
• BM25 无法处理同义词或概念级匹配；
• 默认候选数量太少，正确工具被截断；
• 恶意或夸张的描述抢占检索结果；
• 工具分类发生变化，但系统提示中的类别说明没有更新。

因此，工具搜索需要单独测量召回率，而不能只看最终调用正确率。

4.Programmatic Tool Calling：让代码承担编排与数据处理

4.1 工作机制

程序化工具调用让 Claude 生成一段 Python 编排代码。这段代码在隔离的代码执行环境中运行，可以循环、并发调用获准工具，处理工具返回的数据，最终只把筛选或聚合后的结果交回模型。

原文以差旅预算检查为例：先取得团队成员和职级，再并发查询预算与每个人的费用，最后在代码中求和、比较，只把超支人员列表返回给模型。数千条原始费用记录不必进入模型上下文。

这使职责发生了变化：

• 模型负责理解任务并生成编排程序；
• 代码负责循环、条件、并发、计算和过滤；
• 外部系统负责执行真实工具调用；
• 模型只读取最终结果并完成语义解释。

4.2 适用条件

这种模式适合：

• 对大型数据集做聚合或筛选；
• 包含三个以上相关工具调用的多步任务；
• 中间结果不应全部影响模型判断；
• 需要对大量对象并发执行相同操作；
• 控制流可以清楚表达为循环、条件和数据转换。

如果只需一次简单查询，或模型必须仔细阅读每条中间证据，代码执行的额外层次未必有价值。

4.3 可靠性收益来自“显式控制流”

自然语言工具编排把循环和状态隐含在模型连续决策中；程序化调用则把它们写成代码。代码更容易检查是否漏项、是否并发、如何聚合，也可以加入异常处理和边界检查。

不过，“写成代码”并不自动等于正确。模型仍可能生成错误循环、使用错误字段、忽略分页、重复执行有副作用的操作，或把部分失败当成整体成功。生产环境必须记录生成代码、每次工具调用及其结果，并验证最终输出的完整性。

4.4 allowed_callers 不是安全边界

当前文档允许用 allowed_callers 指示工具应被直接调用，还是从代码执行环境调用。但官方明确说明，这个字段主要影响模型引导与 tool_choice 校验，并不会在 API 层绝对阻止直接调用。

因此，客户端仍需自行执行授权：

• 验证调用者、用户和会话权限；
• 限制代码可调用的工具集合；
• 对写入、删除、付款、发送消息等动作设置批准门槛；
• 对批量操作设置数量和金额上限；
• 使用幂等键，避免重试造成重复副作用；
• 保留审计日志和补偿或回滚路径。

4.5 数据保留与执行环境

当前官方文档说明，程序化工具调用建立在代码执行基础设施上，容器数据及执行产物最多保留 30 天，且该功能不符合零数据保留条件。处理敏感数据时，必须把数据保留、区域、平台和组织合规要求纳入设计，而不能只关注 Token 节省。

5.Tool Use Examples：补足 Schema 无法表达的惯例

5.1 工作机制

开发者在工具定义中加入 input_examples，为模型展示经过 Schema 校验的合法输入。示例可以表达日期、ID、标签风格、嵌套对象和可选字段的组合规律。

它与自然语言描述和 Schema 的分工如下：

信息类型	最合适的载体
工具用途、边界、返回内容	描述文本
字段类型、必填项、枚举与结构约束	JSON Schema
格式惯例、字段组合与典型调用模式	输入示例

示例不是 Schema 的替代品。当前文档要求每个示例都必须通过输入 Schema 校验，否则请求会返回错误。

5.2 适用条件

输入示例适合复杂嵌套对象、格式敏感参数、具有领域约定的 API，以及多个工具边界相近的情况。简单单参数工具、标准 URL 或邮箱格式，以及能够直接由 Schema 限制的问题，通常不需要额外示例。

当前文档估算，简单示例会增加约 20–50 个提示 Token，复杂嵌套示例约增加 100–200 个。因此应优先为真正存在歧义的工具提供少量覆盖性示例，而不是把 API 文档复制成大规模示例集。

5.3 示例可能引入新的偏差

示例会告诉模型“常见调用长什么样”，也可能让模型过度模仿：

• 示例只覆盖高优先级工单，模型可能过度填写升级字段；
• 示例使用某个地区或日期格式，模型可能错误推广到其他地区；
• 业务规则已经变化，但示例仍保持旧组合；
• 示例包含真实个人信息、内部 ID 或秘密；
• 示例数量过多，反而增加上下文和选择偏差。

示例应使用虚构但真实感足够的数据，并与 Schema、服务端校验和业务规则同时维护。

6.三项能力如何组合

文章建议从主要瓶颈出发，而不是一次启用全部功能：

工具定义挤占上下文
→ Tool Search Tool

中间数据和多轮调用挤占上下文
→ Programmatic Tool Calling

参数结构合法但使用方式经常错误
→ Tool Use Examples

三者组合时，流程可以是：模型先搜索到相关工具及其示例，再生成编排代码，由代码批量调用工具、处理结果，最后只把高信号结果交回模型。

这种组合提高了扩展能力，也增加了调试层次。失败可能来自搜索未召回、示例误导、生成代码错误、工具执行失败、聚合逻辑错误或最终解释错误。可观察性必须覆盖整条链，而不能只记录最终回复。

7.原文数字复核

7.1 Tool Search Tool

原文示例称，传统方式在开始工作前消耗约 77K Token，工具搜索方式消耗约 8.7K，并称 Token 使用减少 85%。如果把这两个数字视为同一口径，计算结果是：

(77,000 - 8,700) / 77,000 ≈ 88.7%

因此，85% 与该组示例数字不能精确对应。当前官方文档使用“通常减少 85% 以上”的表述，说明 85% 更可能是跨测试的概括值，而 77K 与 8.7K 是特定示例。阅读时不应把两组口径混为一个精确复算结果。

原文报告的工具选择评测为：

模型	传统方式	启用工具搜索	绝对提升	相对提升
Opus 4	49%	74%	25 个百分点	约 51.0%
Opus 4.5	79.5%	88.1%	8.6 个百分点	约 10.8%

文章将其描述为准确率改善，但没有提供评测样本数、重复次数、置信区间、工具库构成或搜索失败类型，因此无法判断结果在其他工具目录上的稳定性。

7.2 Programmatic Tool Calling

原文称复杂研究任务的平均 Token 使用量从 43,588 降至 27,297。复算为：

(43,588 - 27,297) / 43,588 ≈ 37.4%

与文章报告的 37% 基本一致。

两组准确率数据应区分百分点和相对增长：

评测	原值	新值	绝对提升	相对提升
内部知识检索	25.6%	28.5%	2.9 个百分点	约 11.3%
GAIA	46.5%	51.2%	4.7 个百分点	约 10.1%

原文正文写作 “GIA benchmarks”，但链接指向论文《GAIA: a benchmark for General AI Assistants》。GAIA 包含 466 个需要推理、工具使用和多模态能力的问题。这里应把 GIA 视为名称笔误。

预算示例中，原始费用数据从 200KB 降到 1KB，按字节比例约减少 99.5%。但这是用于解释机制的构造示例，不是对生产流量的统计结果。

7.3 Tool Use Examples

原文称复杂参数处理准确率从 72% 提升至 90%，即提高 18 个百分点，相对提升 25%。同样，文章没有公开任务数、参数复杂度、错误判定方法或模型重复测试结果。

7.4 证据强度总结

结论	证据类型	可以确认的范围	不能确认的内容
延迟加载能减少上下文中的工具定义	机制说明、示例与内部测试	对大型工具库有明确的 Token 节省机制	所有工具库都能减少固定比例
程序化调用能减少中间数据和推理轮次	机制说明与内部测试	数据密集型、多调用任务可能受益	每种任务都会更快、更准或更便宜
输入示例能改善复杂参数调用	内部评测	示例可表达 Schema 无法表达的惯例	任何工具加入示例都会提升准确率
三项功能适合组合	架构推论	三者解决不同瓶颈，逻辑上互补	组合后收益可以直接相加

8.当前文档与原文的变化

原文发布时把三项能力放在同一个 beta header 下，并使用 2025 年的代码执行版本。当前官方文档已经把它们分别纳入工具搜索、工具基础设施和工具定义文档，示例使用更新后的日期版本，也不再展示原文的统一 beta header。

这不表示接口永远稳定。工具类型仍使用日期版本，支持模型、云平台差异、调用限制和数据保留规则也可能变化。实现时应以当前文档为准，不应直接复制文章中的版本字符串。

当前文档还补充了原文没有充分强调的限制：

• 工具搜索最多可延迟 10,000 个工具，默认返回最多 5 个候选；
• 延迟加载工具仍需随请求发送完整定义；
• allowed_callers 不构成硬安全边界；
• 某些递归 Schema、MCP Connector 工具以及计算机和浏览器工具不能用于程序化调用；
• 输入示例不适用于服务端工具和部分工具集；
• 程序化调用的容器存在生命周期与数据保留约束。

9.文章没有充分展开的风险

9.1 检索层成为新的单点故障

工具搜索降低了选择空间，也意味着搜索索引、命名和描述决定模型能看到什么。需要建立工具级检索评测，包括标准查询、同义表达、跨语言查询、相似工具和零结果情况。

9.2 程序化调用扩大单次决策的影响范围

传统逐次调用允许系统在每一步重新检查；代码编排可能在一次模型决策后并发调用几十个工具。它减少模型往返，也可能把错误快速放大。

对只读查询，可以采用较大批量；对写入、发送、删除和付款，应限制并发与数量，必要时先生成执行计划，由人或策略引擎批准后再执行。

9.3 中间数据不可见会损失审计信息

把中间数据留在执行环境中可以节省上下文，但不应等同于不记录。模型不需要读取全部记录，审计系统仍应保存来源、过滤条件、失败项、聚合逻辑和数据版本，使最终结论可以复查。

9.4 错误结果可能在代码中被压缩

如果 50 次调用中有 5 次失败，代码可能只聚合 45 个成功结果并给出看似完整的答案。程序化调用必须显式报告成功数、失败数、重试数和遗漏对象，而不是只打印最终列表。

9.5 工具描述和示例也属于不受信任输入

来自第三方 MCP 服务器的描述可能过时、错误或带有诱导性指令。检索到工具不等于工具可信。平台应对工具来源、权限、版本和描述进行治理，避免把动态工具目录当作天然安全的知识库。

10.选择与组合建议

当前问题	首选机制	不应首先采用的情况	核心评测
工具定义超过上下文预算	Tool Search Tool	工具少且每次都要用	Top-k 召回率、最终选对率、搜索延迟
模型经常在相似工具间选错	Tool Search Tool，并改进命名与描述	根因是权限或业务规则不清	混淆矩阵、零结果率、错误工具率
中间结果庞大，只需聚合值	Programmatic Tool Calling	模型必须阅读全部原始证据	Token、模型轮次、聚合正确率
需要对大量对象执行同一只读查询	Programmatic Tool Calling	工具具有高风险副作用且不可幂等	成功率、部分失败率、并发与限流
参数结构复杂且可选字段有关联	Tool Use Examples	Schema 已能完整约束	参数错误率、示例 Token 成本
格式错误可以由 Schema 消除	强化 Schema 或 strict mode	不要只靠示例暗示	校验失败率、服务端拒绝率
三类问题同时存在	分层组合三项能力	尚未建立单项基线	端到端成功率、成本、延迟、可审计性

11.落地流程

11.1 建立传统调用基线

记录代表性任务中的工具定义 Token、最终成功率、错选工具率、参数错误率、模型轮次、端到端延迟和总成本。没有基线，就无法判断高级机制是否真正改善系统。

11.2 找出主要瓶颈

不要因为功能可用就全部启用。先确认失败主要来自工具发现、中间数据膨胀，还是参数惯例不清。

11.3 单独引入一种机制

在相同任务集上比较新旧方案，并记录失败类型。Tool Search Tool 应单独评估召回；程序化调用应检查部分失败和聚合正确性；输入示例应检查是否对未见过的参数组合仍有效。

11.4 建立安全与权限层

客户端应对每次真实工具调用执行身份验证、授权和参数校验。不要把模型生成的代码、allowed_callers 或工具搜索结果当作授权依据。

11.5 再做组合评测

单项有效后，再评估组合。组合收益不能直接相加，因为更少的上下文可能改变模型行为，搜索结果会影响生成代码，示例也会增加工具定义 Token。

12.生产检查清单

12.1 工具搜索

• 常用工具是否保持立即加载，其余工具是否合理延迟？
• 工具名、描述和参数是否包含用户常用表达及同义词？
• 是否测试 Top-k 召回、零结果、相似工具和跨语言查询？
• 搜索失败时是否有回退路径？
• 第三方工具描述是否经过可信来源与权限审查？

12.2 程序化调用

• 生成代码和每次工具调用是否进入审计日志？
• 工具返回格式是否明确、稳定并可由代码解析？
• 是否正确处理分页、空值、超时、限流和部分失败？
• 写操作是否幂等，是否限制批量规模和并发？
• allowed_callers 之外是否还有真实授权检查？
• 最终结果是否报告处理总数、成功数和失败数？
• 数据保留与代码执行环境是否符合合规要求？

12.3 输入示例

• 每个示例是否通过 Schema 校验？
• 示例是否只覆盖 Schema 无法表达的关键歧义？
• 是否同时包含最小、部分和完整参数形式？
• 是否使用虚构数据，避免个人信息、凭证和内部标识？
• 业务规则或 API 版本变化时，示例是否同步更新？

12.4 端到端评测

• 是否同时记录成功率、Token、模型轮次、延迟与成本？
• 准确率变化是否区分百分点与相对提升？
• 是否保存评测样本、模型版本、工具目录和参数配置？
• 是否分析搜索、代码、工具、聚合和最终解释各层错误？
• 新机制是否解决了已知瓶颈，而不是只增加复杂度？

13.总体评价

《Introducing advanced tool use》给出的不是三个彼此孤立的 API 功能，而是一套清晰的上下文工程思路：大型工具目录按需检索，大型中间结果在代码环境中处理，复杂调用惯例通过少量示例传递。它把模型从“读取全部定义、观察全部数据、逐次决定每次调用”的负担中解放出来，使模型更集中于语义判断和任务规划。

文章的机制解释具有较强工程价值，内部结果也表明这些功能在特定大型工具库和多步骤任务中可能同时改善 Token 使用与准确率。但数字口径并非全部一致，评测方法披露有限，且原文对检索召回、代码执行权限、部分失败、数据保留和审计的讨论不足。

因此，正确的采用方式不是默认启用全部高级功能，而是先测量传统调用的瓶颈：

工具太多时延迟加载，数据太多时程序化处理，参数惯例不清时提供示例；每增加一层，都必须同时验证效果、成本、安全和可审计性。

14.参考资料

1. Anthropic：Introducing advanced tool use on the Claude Developer Platform
2. Claude Platform Docs：Tool search tool
3. Claude Platform Docs：Programmatic tool calling
4. Claude Platform Docs：Define tools
5. Grégoire Mialon 等：GAIA: a benchmark for General AI Assistants