Claude Developer Platform 的高级工具调用能力

官方原文: https://www.anthropic.com/engineering/advanced-tool-use

发布日期： 2025 年 11 月 24 日

作者： Bin Wu 撰写；Adam Jones、Artur Renault、Henry Tay、Jake Noble、Noah Picard、Sam Jiang 和 Claude Developer Platform 团队共同参与。

概览

Claude Developer Platform 新增三项 Beta 能力，让 Claude 可以动态地发现、理解并执行工具。它们解决的是 Agent 开发中的一个核心问题：当系统可能接入数千个工具时，怎样既保持完整的工具能力，又不耗尽 Context Window。

设想中的 Agent 可以在大型工具库中自然工作。例如 IDE 助手同时接入 Git、文件操作、包管理、测试与部署；又如运营协调 Agent 同时连接 Slack、GitHub、Google Drive、Jira、数据库和 MCP server。

三项能力

1. Tool Search Tool

问题： 如果一开始就把所有工具定义都放进上下文，会消耗大量 Token。一个由 GitHub、Slack、Sentry、Grafana 和 Splunk 构成的五 server 配置，包含 58 个工具，在对话开始前就约占 55K tokens。Anthropic 也曾遇到过工具定义优化前占用 134K tokens 的情况。成本之外，名称相近的工具还容易导致选错工具，或传入错误参数。

方案： Tool Search Tool 支持按需发现，而不是预先加载所有工具。将工具设为 defer_loading: true 后，初始上下文只包含 Tool Search Tool 本身，约 500 tokens。Claude 需要某项能力时先搜索，只有匹配的工具定义才会被加入上下文。

文章报告，在保留完整工具库访问能力的前提下，Token 使用量可降低 85%。内部 MCP 评测中，Opus 4 的准确率从 49% 提升至 74%，Opus 4.5 则从 79.5% 提升至 88.1%。

使用时，在 tools 数组中加入一个工具搜索工具，可采用 regex、BM25 或自定义实现；再为可发现的工具设置 defer_loading: true。对于 MCP server，还可以延迟加载整个 server，同时让高频工具始终保留在初始上下文中。

由于延迟加载的工具完全不进入初始 prompt，prompt caching 不会受影响。

适用场景： 工具定义超过 10K tokens、工具选择准确率不足、使用多个 MCP server，或可用工具数量达到 10 个以上。若工具少于 10 个、几乎每个工具都高频使用，或定义本身很紧凑，则收益有限。

2. Programmatic Tool Calling

问题： 传统工具调用会把中间结果不断塞入 Context，并产生额外推理往返。每调用一次工具，都需要一次完整模型推理；不管中间结果是否相关，都会持续累积在上下文中。

方案： Programmatic Tool Calling 让 Claude 通过代码来编排工具，而不是逐个发起 API 往返。Claude 会编写 Python，调用多个工具、处理它们的返回值，并自行决定哪些结果应进入 Context Window。循环、条件判断、数据转换与错误处理都明确存在于代码中。

示例：差旅预算合规检查

文中用 get_team_members、get_expenses 和 get_budget_by_level 三个工具，检查哪些成员超出了第三季度差旅预算。

传统方式下，读取 20 个人的数据可能产生数千条费用明细，约 50 KB 以上，全部进入 Claude 的 Context。采用 Programmatic Tool Calling 后，Claude 编写 Python 脚本并以 asyncio.gather 并行执行；最终只有超预算的 2 至 3 人会进入上下文，数据量从约 200 KB 的原始数据缩减到约 1 KB 的结果。

报告的改进包括：

在复杂研究任务中节省 37% tokens，平均从约 43,588 降至约 27,297。
对包含 20 个工具的工作流，减少 19 次以上的推理往返，从而降低延迟。
准确率提升：知识检索从 25.6% 升至 28.5%，GIA benchmark 从 46.5% 升至 51.2%。

工作方式分为四步：

在 tools 中加入 code_execution，并用 allowed_callers 明确允许哪些工具从代码中被调用。
Claude 用 Python 编写编排逻辑。
工具在 Code Execution 环境中运行，中间结果不进入 Claude 的 Context；工具请求会携带 caller 字段，关联到对应的代码执行 Session。
只有最终输出，即 stdout，会返回到 Claude 的 Context。

适用场景： 大数据集中只需汇总结果、包含三个以上相互依赖调用的多步骤流程、需先过滤/排序/转换再交给 Claude 的结果，以及可并行操作。对于单工具调用、必须让 Claude 逐一推理所有中间结果的任务，或返回很小的快速查询，收益较小。

3. Tool Use Examples

问题： JSON Schema 能定义输入结构，却无法充分表达正确的使用习惯。以支持工单 API create_ticket 为例，日期格式、ID 规则、嵌套对象的写法，以及参数之间的关联都可能存在歧义，Schema 本身难以说明白。

方案： Tool Use Examples 允许在工具定义的 input_examples 字段中直接提供真实的调用示例。文章为 create_ticket 给出三个例子：

附带完整联系人信息和升级处理的严重 Bug。
有报告人、但没有联系人或升级信息的功能请求。
只有标题的内部任务。

这些示例让 Claude 学到 YYYY-MM-DD 日期、USR-XXXXX ID、kebab-case 标签等格式约定，也能理解嵌套结构与可选参数之间的关系。内部测试显示，复杂参数处理的准确率从 72% 提升到 90%。

适用场景： 复杂嵌套结构、可选参数很多的工具、带领域惯例的 API，或需要在相似工具间消歧的情况。对于单参数工具、Claude 已了解的标准格式，或更应由 JSON Schema 负责的校验问题，帮助不大。

最佳实践

应根据当前最主要的瓶颈组合使用这些能力：

工具定义让 Context 过度膨胀：使用 Tool Search Tool。
大量中间结果污染 Context：使用 Programmatic Tool Calling。
参数错误或调用格式不正确：使用 Tool Use Examples。

Tool Search Tool： 工具名称和说明要清楚；在 system prompt 中说明有哪些工具类别；保留 3 至 5 个最常用工具常驻，其余按需加载。

Programmatic Tool Calling： 清晰说明每个工具的返回格式，因为 Claude 需要编写解析代码。优先接入适合并行运行的工具和幂等操作。

Tool Use Examples： 使用贴近生产的真实数据，展示最简、部分填写、完整填写等不同模式；每个工具保留 1 至 5 个示例，重点覆盖 Schema 无法显式说明的歧义。

开始使用

这些能力以 Beta 形式提供，需要使用 header advanced-tool-use-2025-11-20。下面的 Python SDK 示例展示了启用方式：

python

client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {"type": "code_execution_20250825", "name": "code_execution"},
        # 在你的工具上配置 defer_loading、allowed_callers 和 input_examples
    ]
)

致谢

基础研究由 Chris Gorgolewski、Daniel Jiang、Jeremy Fox 和 Mike Lambert 贡献。本项工作借鉴了 Joel Pobar 的 LLMVM、Cloudflare 的 Code Mode，以及 Anthropic 自身的 Code Execution as MCP。特别感谢 Andy Schumeister、Hamish Kerr、Keir Bradwell、Matt Bleifer 和 Molly Vorwerck。

Claude Developer Platform 的高级工具调用能力 ​

概览 ​

三项能力 ​

1. Tool Search Tool ​

2. Programmatic Tool Calling ​

3. Tool Use Examples ​

最佳实践 ​

开始使用 ​

致谢 ​