Claude API 进阶 Tool Use：三招降本提准

工具调用最常见的失败不是“模型不会调用 API”，而是工具定义塞满 context、参数填错、以及中间结果反复进出模型。先定位是哪一种，再选择 Tool Search、Programmatic Tool Calling 或 input_examples；三种能力不是互相替代。

---

先看决策表

官方当前把这几种方法放在同一套 Tool Context 管理框架中：Tool Search 减少预加载定义，程序化调用减少 tool_result 往返，Prompt Caching 降低重复前缀成本，Context Editing 清掉已经失去价值的旧结果。

---

1. Tool Search：只加载本轮需要的定义

Tool Search 的适用条件不是“接了 MCP”，而是工具目录已经大到影响 baseline context。工具标记为 defer_loading: true 后，定义不会一开始就进入 prompt；Claude 先搜索，再通过 tool_reference 加载命中的工具。

import os
from anthropic import Anthropic

client = Anthropic()

tools = [
    {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search",
    },
    {
        "name": "get_customer_orders",
        "description": "Return orders for one customer. Use for order history, not account details.",
        "defer_loading": True,
        "input_schema": {
            "type": "object",
            "properties": {"customer_id": {"type": "string"}},
            "required": ["customer_id"],
        },
    },
]

response = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1200,
    tools=tools,
    messages=[{"role": "user", "content": "查客户 C-1042 最近三笔订单"}],
)

Tool Search 验收标准

• 首轮 prompt 中没有被延迟工具的完整 schema。
• 搜索结果能区分名称相近但职责不同的工具。
• 工具描述写清楚 什么时候用、什么时候不用。
• 记录搜索命中率、额外延迟和输入 token，而不是只看回答是否正确。

---

2. Programmatic Tool Calling：把批处理留在沙箱里

程序化工具调用允许 Claude 在 Code Execution 沙箱里写代码，再由代码调用被授权的工具。适合 fan-out、聚合、过滤和条件分支；中间结果不会逐项进入对话历史。

tools = [
    {"type": "code_execution_20260120", "name": "code_execution"},
    {
        "name": "get_service_health",
        "description": "Return health and latency for one service.",
        "allowed_callers": ["code_execution_20260120"],
        "input_schema": {
            "type": "object",
            "properties": {"service": {"type": "string"}},
            "required": ["service"],
        },
    },
]

用户请求“找出 50 个服务里延迟超过 500ms 的项目”时，正确的数据路径是：

Claude 写循环
  → 沙箱并发调用 get_service_health
  → 在沙箱中过滤 latency_ms > 500
  → 只把异常服务返回 context

严格串行、每一步都需要模型重新判断的任务不适合这种模式。那种场景无法减少模型回合，却增加了代码执行和沙箱开销。

---

3. input_examples：修复“选对工具，填错参数”

JSON Schema 能定义类型，却不擅长表达团队惯例。例如日期必须是业务时区、可选字段必须成对出现、或数组内元素需要特定组合。这时才加 input_examples。

{
    "name": "create_incident",
    "description": "Create an incident after an alert has been verified. Do not use for unverified alerts.",
    "input_schema": {
        "type": "object",
        "properties": {
            "service": {"type": "string"},
            "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3"]},
            "started_at": {"type": "string", "description": "ISO 8601 with timezone"},
            "evidence_urls": {"type": "array", "items": {"type": "string"}},
        },
        "required": ["service", "severity", "started_at", "evidence_urls"],
    },
    "input_examples": [
        {
            "service": "checkout-api",
            "severity": "sev2",
            "started_at": "2026-08-25T09:42:00+10:00",
            "evidence_urls": ["https://monitor.example/incidents/abc"],
        }
    ],
}

示例本身也占 token，所以只给误填率高的工具添加。先修 description，再补 example，最后才考虑在 prompt 里堆更多规则。

---

一套可复用的上线流程

1. 从 trace 里统计三类失败：选错工具、参数不合法、结果过大。
2. 为每类失败只引入一种控制变量。
3. 建立 30–100 条真实任务 eval，不用演示用 happy path。
4. 比较成功率、输入 token、工具轮数、P95 延迟和总成本。
5. 达到阈值后灰度发布，并保留普通 Tool Use 回退路径。

完成标准

• 工具选择准确率没有下降。
• Schema 校验失败率低于团队设定阈值。
• 大结果在进入模型前完成过滤。
• 每项节省都有 trace 或账单证据，不写“显著降低”这种空结论。

---

常见错误

---

动手练习

假设你有订单、客户、退款、库存、物流共 35 个工具。选一个“调查延迟订单”的任务：

1. 标出本轮真正需要的 3–5 个工具。
2. 为其余工具配置延迟加载。
3. 用程序化调用并发查询订单与物流状态。
4. 为退款工具补一个包含时区和证据链接的 input example。
5. 用相同 20 条任务比较普通调用与新方案。

自检

• 我能解释三种能力分别减少哪一种失败。
• 我没有把官方示例中的版本字符串当成永久常量。
• 我为成本、延迟、准确率分别留了指标。
• 我能在新方案失败时回退到普通 Tool Use。

相关阅读

• MCP 的 Code Execution 模式
• Tool Design Principles
• Agent Evaluation

参考资料

• https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context
• https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
• https://www.anthropic.com/engineering/advanced-tool-use