Claude 高级工具使用能力发布

AI Agent 的未来

AI Agent 的未来将是模型能够无缝协作使用数百个甚至数千个工具的世界。IDE 助手可以集成 git 操作、文件操作、包管理器、测试框架和部署管道。操作协调员可以同时连接 Slack、GitHub、Google Drive、Jira、公司数据库以及数十个 MCP 服务器。

要构建高效的 Agent，它们需要能够使用无限的工具库，而不是预先将每个定义都塞入上下文。我们的博客文章讨论了在 MCP 中使用代码执行，其中工具结果和定义在 Agent 读取请求之前有时会消耗 50,000+ 个 token。Agent 应该按需发现和加载工具，仅保留与当前任务相关的内容。

Agent 还需要能够从代码中调用工具。使用自然语言工具调用时，每次调用都需要完整的推理过程，中间结果会在上下文中堆积，无论它们是否有用。代码是编排逻辑的自然选择，比如循环、条件语句和数据转换。Agent 需要灵活性，根据任务选择代码执行或推理。

Agent 还需要从示例而不仅仅是 schema 定义中学习正确的工具使用方法。JSON schema 定义了什么是结构上有效的，但无法表达使用模式：何时包含可选参数、哪些组合有意义，或 API 期望什么样的约定。

今天，我们发布了三个使这一切成为可能的功能：

Tool Search Tool，允许 Claude 使用搜索工具访问数千个工具，而不消耗其上下文窗口

Programmatic Tool Calling，允许 Claude 在代码执行环境中调用工具，减少对模型上下文窗口的影响

Tool Use Examples，为演示如何有效使用给定工具提供了通用标准

在内部测试中，我们发现这些功能帮助我们构建了使用传统工具使用模式不可能实现的东西。例如，Claude for Excel 使用 Programmatic Tool Calling 读取和修改包含数千行的电子表格，而不会使模型的上下文窗口过载。

基于我们的经验，我们相信这些功能为你使用 Claude 构建的内容开启了新的可能性。

Tool Search Tool 的必要性

MCP 工具定义提供了重要的上下文，但随着更多服务器连接，这些 token 可能会累加。考虑一个五服务器的设置：

• GitHub：35 个工具（约 26K token）
• Slack：11 个工具（约 21K token）
• Sentry：5 个工具（约 3K token）
• Grafana：5 个工具（约 3K token）
• Splunk：2 个工具（约 2K token）

这是 58 个工具，在对话甚至开始之前就消耗了约 55K token。再加上 Jira（单独使用约 17K token）这样的服务器，你很快就会接近 100K+ token 的开销。在 Anthropic，我们看到工具定义在优化前消耗了 134K token。

但 token 成本并不是唯一的问题。最常见的故障是错误的工具选择和不正确的参数，特别是当工具有相似的名字时，比如 notification-send-user 对比 notification-send-channel。

Tool Search Tool 不是预先加载所有工具定义，而是按需发现工具。Claude 只会看到它实际需要用于当前任务的工具。

传统方法的对比

传统方法：

• 所有工具定义预先加载（~72K token，用于 50+ MCP 工具）
• 对话历史和系统提示与剩余空间竞争
• 总上下文消耗：在任何工作开始前约 77K token

使用 Tool Search Tool：

• 仅预先加载 Tool Search Tool（~500 token）
• 工具按需发现（3-5 个相关工具，~3K token）
• 总上下文消耗：~8.7K token，保留了 95% 的上下文窗口

这代表了 85% 的 token 使用减少，同时保持对完整工具库的访问。内部测试表明，在处理大型工具库时，MCP 评估的准确性有显著提升。Opus 4 从 49% 提升到 74%，Opus 4.5 从 79.5% 提升到 88.1%（启用 Tool Search Tool）。

Tool Search Tool 如何工作

Tool Search Tool 让 Claude 动态发现工具，而不是预先加载所有定义。你向 API 提供所有工具定义，但用 defer_loading: true 标记工具使其可按需发现。延迟加载的工具最初不会加载到 Claude 的上下文中。Claude 只会看到 Tool Search Tool 本身，加上任何 defer_loading: false 的工具（你最关键的、频繁使用的工具）。

当 Claude 需要特定功能时，它会搜索相关工具。Tool Search Tool 返回匹配工具的引用，这些引用会在 Claude 的上下文中展开为完整定义。

例如，如果 Claude 需要与 GitHub 交互，它会搜索 "github"，只有 github.createPullRequest 和 github.listIssues 会被加载，而不是来自 Slack、Jira 和 Google Drive 的其他 50+ 工具。

这样，Claude 可以访问完整的工具库，同时只支付它实际需要的工具的 token 成本。

Prompt 缓存说明

Tool Search Tool 不会破坏 prompt 缓存，因为延迟加载的工具最初被排除在 prompt 之外。它们只在 Claude 搜索后才被添加到上下文中，所以你的系统提示和核心工具定义保持可缓存。

{
  "tools": [
    // 包含一个工具搜索工具（regex、BM25 或自定义）
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},

    // 标记工具以进行按需发现
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {...},
      "defer_loading": true
    }
    // ... 数百个更多延迟加载的工具，defer_loading: true
  ]
}

对于 MCP 服务器，你可以延迟加载整个服务器的同时保持特定的高使用工具加载：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": {"defer_loading": true}, # 延迟加载整个服务器
  "configs": {
    "search_files": {
"defer_loading": false
    }  // 保持最常用工具的加载
  }
}

Claude Developer Platform 提供了基于 regex 和 BM25 的搜索工具开箱即用，但你也可以使用嵌入或其他策略实现自定义搜索工具。

何时使用 Tool Search Tool

像任何架构决策一样，启用 Tool Search Tool 涉及权衡。该功能在工具调用之前增加了搜索步骤，因此当上下文节省和准确性提升超过额外延迟时，它的投资回报率最高。

最有益当：

• 工具定义消耗 >10K token
• 遇到工具选择准确性问题
• 使用多个服务器构建 MCP 驱动的系统

不太有益当：

• 小型工具库（<10 个工具）
• 在每个会话中频繁使用所有工具
• 工具定义紧凑

Programmatic Tool Calling

传统工具调用在工作流变得更复杂时产生两个基本问题：

中间结果造成的上下文污染： 当 Claude 分析 10MB 日志文件以查找错误模式时，整个文件进入其上下文窗口，即使 Claude 只需要错误频率的摘要。在跨多个表获取客户数据时，每条记录都会累积在上下文中，无论是否相关。这些中间结果消耗大量 token 预算，并可能将重要信息完全推出上下文窗口。

推理开销和手动合成： 每次工具调用都需要完整的模型推理过程。收到结果后，Claude 必须"浏览"数据以提取相关信息，推理各部分如何组合，并决定下一步做什么，所有这一切都通过自然语言处理完成。五个工具工作流意味着五次推理过程，加上 Claude 解析每个结果、比较数值和合成结论。这既慢又容易出错。

Programmatic Tool Calling 允许 Claude 通过代码而不是通过单个 API 往返来编排工具。Claude 不是一次一个地请求工具，每个结果都返回到其上下文中，而是编写代码来调用多个工具、处理其输出，并控制哪些信息实际进入其上下文窗口。

Claude 擅长编写代码，通过让它用 Python 而不是通过自然语言工具调用来表达编排逻辑，你获得更可靠、精确的控制流。循环、条件语句、数据转换和错误处理都在代码中是显式的，而不是在 Claude 推理中隐式的。

考虑一个常见的商业任务："哪些团队成员超过了他们的 Q3 差旅预算？"

你有三个可用的工具：

• get_team_members(department) - 返回带有 ID 和级别的团队成员列表
• get_expenses(user_id, quarter) - 为用户返回特定季度的费用行项目
• get_budget_by_level(level) - 返回员工级别的预算限额

传统方法：

• 获取团队成员 → 20 人
• 对每个人获取其 Q3 费用 → 20 次工具调用，每次返回 50-100 个行项目（航班、酒店、餐饮、收据）
• 按员工级别获取预算限额
• 所有这些进入 Claude 的上下文：2,000+ 费用行项目（50 KB+）
• Claude 手动求和每个人的费用，查找其预算，比较费用与预算限额
• 更多往返模型、大量上下文消耗

使用 Programmatic Tool Calling：

Claude 不是让每个工具结果返回给 Claude，而是编写 Python 脚本来编排整个工作流。脚本在 Code Execution 工具（沙盒环境）中运行，在需要工具结果时暂停。当你通过 API 返回工具结果时，它们由脚本处理而不是被模型消耗。脚本继续执行，Claude 只看到最终输出。

这是 Claude 对预算合规任务的编排代码：

team = await get_team_members("engineering")

# 为每个唯一级别获取预算
levels = list(set(m["level"] for m in team))
budget_results = await asyncio.gather(*[
    get_budget_by_level(level) for level in levels
])

# 创建查找字典：{"junior": budget1, "senior": budget2, ...}
budgets = {level: budget for level, budget in zip(levels, budget_results)}

# 并行获取所有费用
expenses = await asyncio.gather(*[
    get_expenses(m["id"], "Q3") for m in team
])

# 找出超过差旅预算的员工
exceeded = []
for member, exp in zip(team, expenses):
    budget = budgets[member["level"]]
    total = sum(e["amount"] for e in exp)
    if total > budget["travel_limit"]:
        exceeded.append({
            "name": member["name"],
            "spent": total,
            "limit": budget["travel_limit"]
        })

print(json.dumps(exceeded))

Claude 的上下文只接收最终结果：超过预算的两到三个人。2,000+ 行项目、中间求和和预算查找不影响 Claude 的上下文，将消耗从 200KB 的原始费用数据减少到 1KB 的结果。

效率收益巨大：

Token 节省： 通过将中间结果保持在 Claude 的上下文之外，PTC 大幅减少 token 消耗。复杂研究任务的平均使用量从 43,588 下降到 27,297 token，减少了 37%。

延迟降低： 每次 API 往返都需要模型推理（几百毫秒到秒）。当 Claude 在单个代码块中编排 20+ 工具调用时，你消除了 19+ 次推理过程。API 处理工具执行时无需每次都返回到模型。

准确性提升： 通过编写显式编排逻辑，Claude 的错误比在自然语言中处理多个工具结果时更少。内部知识检索从 25.6% 提升到 28.5%；GIA 基准从 46.5% 提升到 51.2%。

生产工作流涉及杂乱的数据、条件逻辑和需要扩展的操作。Programmatic Tool Calling 让 Claude 通过编程处理这种复杂性，同时将其专注力保持在可操作的结果上，而不是原始数据处理。

Programmatic Tool Calling 如何工作

添加 code_execution 到工具，并设置 allowed_callers 以选择程序化执行的工具：

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "get_team_members",
      "description": "Get all members of a department...",
      "input_schema": {...},
      "allowed_callers": ["code_execution_20250825"] # 选择进行程序化工具调用
    },
    {
      "name": "get_expenses",
 	...
    },
    {
      "name": "get_budget_by_level",
	...
    }
  ]
}

API 将这些工具定义转换为 Claude 可以调用的 Python 函数。

Claude 不是一次一个地请求工具，而是生成 Python 代码：

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc",
  "name": "code_execution",
  "input": {
    "code": "team = get_team_members('engineering')\n..." # 上面的代码示例
  }
}

当代码调用 get_expenses() 时，你收到带有 caller 字段的工具请求：

{
  "type": "tool_use",
  "id": "toolu_xyz",
  "name": "get_expenses",
  "input": {"user_id": "emp_123", "quarter": "Q3"},
  "caller": {
    "type": "code_execution_20250825",
    "tool_id": "srvtoolu_abc"
  }
}

你提供结果，这在 Code Execution 环境中处理而不是在 Claude 的上下文中。这种请求-响应循环对代码中的每个工具调用重复。

当代码执行完毕时，只有代码的结果返回给 Claude：

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc",
  "content": {
    "stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]"
  }
}

这是 Claude 看到的一切，而不是沿途处理的 2000+ 费用行项目。

何时使用 Programmatic Tool Calling

Programmatic Tool Calling 向工作流添加了代码执行步骤。这个额外的开销在 token 节省、延迟改进和准确性收益可观时才值得。

最有益当：

• 处理大型数据集，仅需要聚合或摘要
• 运行三个或更多依赖工具调用的多步工作流
• 过滤、排序或转换工具结果，然后 Claude 看到它们
• 处理中间数据不应影响 Claude 推理的任务
• 跨许多项运行并行操作（例如检查 50 个端点）

不太有益当：

• 进行简单的单工具调用
• 处理 Claude 应该看到和推理所有中间结果的任务
• 运行具有小响应的快速查找

Tool Use Examples

JSON Schema 擅长定义结构——类型、必需字段、允许的枚举——但无法表达使用模式：何时包含可选参数、哪些组合有意义，或 API 期望什么样的约定。

考虑一个支持票据 API：

{
  "name": "create_ticket",
  "input_schema": {
    "properties": {
      "title": {"type": "string"},
      "priority": {"enum": ["low", "medium", "high", "critical"]},
      "labels": {"type": "array", "items": {"type": "string"}},
      "reporter": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "contact": {
            "type": "object",
            "properties": {
              "email": {"type": "string"},
              "phone": {"type": "string"}
            }
          }
        }
      },
      "due_date": {"type": "string"},
      "escalation": {
        "type": "object",
        "properties": {
          "level": {"type": "integer"},
          "notify_manager": {"type": "boolean"},
          "sla_hours": {"type": "integer"}
        }
      }
    },
    "required": ["title"]
  }
}

schema 定义了什么是有效的，但留下了关键问题未回答：

• 格式歧义： due_date 应该使用 "2024-11-06"、"Nov 6, 2024" 还是 "2024-11-06T00:00:00Z"？
• ID 约定： reporter.id 是 UUID、"USR-12345" 还是仅仅 "12345"？
• 嵌套结构使用： Claude 何时应该填充 reporter.contact？
• 参数关联： escalation.level 和 escalation.sla_hours 如何与 priority 相关联？

这些歧义可能导致工具调用格式错误和参数使用不一致。

Tool Use Examples 让你直接在工具定义中提供示例工具调用。与仅依赖 schema 不同，你向 Claude 展示具体的使用模式：

{
    "name": "create_ticket",
    "input_schema": { /* 与上面相同的 schema */ },
    "input_examples": [
      {
        "title": "Login page returns 500 error",
        "priority": "critical",
        "labels": ["bug", "authentication", "production"],
        "reporter": {
          "id": "USR-12345",
          "name": "Jane Smith",
          "contact": {
            "email": "jane@acme.com",
            "phone": "+1-555-0123"
          }
        },
        "due_date": "2024-11-06",
        "escalation": {
          "level": 2,
          "notify_manager": true,
          "sla_hours": 4
        }
      },
      {
        "title": "Add dark mode support",
        "labels": ["feature-request", "ui"],
        "reporter": {
          "id": "USR-67890",
          "name": "Alex Chen"
        }
      },
      {
        "title": "Update API documentation"
      }
    ]
  }

从这三个示例，Claude 学会了：

• 格式约定： 日期使用 YYYY-MM-DD，用户 ID 遵循 USR-XXXXX，标签使用 kebab-case
• 嵌套结构模式： 如何构造带其嵌套 contact 对象的 reporter 对象
• 可选参数关联： 关键 bug 有完整的联系信息 + 带紧密 SLA 的升级；功能请求有 reporter 但无 contact/escalation；内部任务仅有 title

在我们自己的内部测试中，Tool Use Examples 在复杂参数处理上将准确性从 72% 提升到 90%。

何时使用 Tool Use Examples

Tool Use Examples 向工具定义添加了 token，因此它们在准确性提升超过额外成本时最有价值。

最有益当：

• 复杂嵌套结构，有效的 JSON 并不意味着正确的使用
• 具有许多可选参数且包含模式很重要的工具
• 具有 schema 中不被捕获的特定领域约定的 API
• 相似工具，其中示例明确说明使用哪个（例如 create_ticket 对比 create_incident）

不太有益当：

• 简单的单参数工具，使用显而易见
• 标准格式，如 Claude 已经理解的 URL 或电子邮件
• 最好通过 JSON Schema 约束处理的验证问题

组合这些功能

让 Agent 采取真实世界的行动意味着同时处理规模、复杂性和精确性。这三个功能一起解决工具使用工作流中的不同瓶颈。以下是如何有效地组合它们。

战略性地分层功能

并不是每个 Agent 对于给定任务都需要使用所有三个功能。从你最大的瓶颈开始：

• 工具定义的上下文膨胀 → Tool Search Tool
• 大的中间结果污染上下文 → Programmatic Tool Calling
• 参数错误和格式错误的调用 → Tool Use Examples

这种专注的方法让你解决限制 Agent 性能的特定约束，而不是预先增加复杂性。

然后根据需要分层添加额外功能。它们是互补的：Tool Search Tool 确保找到正确的工具，Programmatic Tool Calling 确保高效执行，Tool Use Examples 确保正确调用。

设置 Tool Search Tool 以获得更好的发现

工具搜索与名称和描述匹配，因此清晰、描述性的定义改进发现准确性。

// 好的做法
{
    "name": "search_customer_orders",
    "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

// 不好的做法
{
    "name": "query_db_orders",
    "description": "Execute order query"
}

添加系统提示指导，以便 Claude 知道什么是可用的：

You have access to tools for Slack messaging, Google Drive file management, 
Jira ticket tracking, and GitHub repository operations. Use the tool search 
to find specific capabilities.

保持三到五个最常用的工具始终加载，其余的延迟加载。这平衡了常见操作的立即访问与所有其他的按需发现。

设置 Programmatic Tool Calling 以确保正确执行

由于 Claude 编写代码来解析工具输出，清晰地记录返回格式。这帮助 Claude 编写正确的解析逻辑：

{
    "name": "get_orders",
    "description": "Retrieve orders for a customer.
Returns:
    List of order objects, each containing:
    - id (str): Order identifier
    - total (float): Order total in USD
    - status (str): One of 'pending', 'shipped', 'delivered'
    - items (list): Array of {sku, quantity, price}
    - created_at (str): ISO 8601 timestamp"
}

见下文了解受益于程序化编排的选择工具：

• 可以并行运行的工具（独立操作）
• 安全重试的操作（幂等）

设置 Tool Use Examples 以提高参数准确性

精心制作示例以明确行为：

• 使用现实数据（真实城市名、看似合理的价格，不是 "string" 或 "value"）
• 展示最小、部分和完整规范模式的多样性
• 保持简洁：每个工具 1-5 个示例
• 专注于歧义（仅在正确使用不明显的地方添加示例）

API 使用

这些功能处于测试阶段。要启用它们，添加 beta 头并包含你需要的工具：

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
    ]
)

如需详细的 API 文档和 SDK 示例，请参阅我们的：

• Tool Search Tool 文档和 cookbook
• Programmatic Tool Calling 文档和 cookbook
• Tool Use Examples 文档

这些功能将工具使用从简单的函数调用转移到智能编排。当 Agent 处理跨越数十个工具和大型数据集的更复杂工作流时，动态发现、高效执行和可靠调用变成了基础。

我们很期待看到你构建的东西。

由 Bin Wu 编写，得到了 Adam Jones、Artur Renault、Henry Tay、Jake Noble、Noah Picard、Sam Jiang 以及 Claude Developer Platform 团队的贡献。这项工作建立在 Chris Gorgolewski、Daniel Jiang、Jeremy Fox 和 Mike Lambert 的基础研究之上。我们也从整个 AI 生态系统中获得了灵感，包括 Joel Pobar 的 LLMVM、Cloudflare 的 Code Mode 和作为 MCP 的 Code Execution。特别感谢 Andy Schumeister、Hamish Kerr、Keir Bradwell、Matt Bleifer 和 Molly Vorwerck 的支持。