工具参考

本页面是 Anthropic 提供的工具以及您可以在任何工具定义上设置的可选属性的参考。有关工具使用的概念性介绍，请参阅 Claude 的工具使用。有关在应用程序中实现工具使用的指导，请参阅定义工具。

Anthropic 提供的工具

Anthropic 提供两种工具：在 Anthropic 基础设施上执行的 "server tools"（服务器工具），以及由 Anthropic 定义 schema 但由您的应用程序负责执行的 "client tools"（客户端工具）。这两种工具都与任何用户定义的工具一起出现在请求的 tools 数组中。

有关模型兼容性，请参阅各工具的页面。支持的模型因工具和工具版本而异。要在代码中检查某个模型是否接受 Web 搜索或代码执行，请参阅使用 Models API。

工具版本控制

大多数 Anthropic 提供的工具在 type 字符串中带有 _YYYYMMDD 后缀。当工具的行为、schema 或模型支持发生变化时，会发布新版本。旧版本仍然可用，以便现有集成继续正常工作。

当一个工具有多个活跃版本时，它们之间的关系各不相同：

• 按功能区分： web_search_20260209 和 web_fetch_20260209 相比其前代版本增加了动态内容过滤；web_fetch_20260309 增加了绕过缓存的选项；web_search_20260318 和 web_fetch_20260318 增加了响应包含控制。code_execution_20260120 增加了从沙箱内部进行程序化工具调用的功能；code_execution_20260521 在工具描述中披露了每个单元的时间限制。在每种情况下，新版本和旧版本都是当前版本；使用哪一个取决于您是否需要新功能。
• 按模型区分： text_editor_20250728 适用于 Claude 4 及更高版本的模型，text_editor_20250124 适用于更早的模型。您使用的版本取决于您的目标模型。
• 变体，而非版本： tool_search_tool_regex_20251119 和 tool_search_tool_bm25_20251119 是同时发布的两种搜索算法。两者互不取代。
• 旧版： code_execution_20250522 仅支持 Python。code_execution_20250825 增加了 Bash 和文件操作。
• 后继版本： computer_toolset_20260801 是 beta 版 computer_20251124 和 computer_20250124 的稳定后继版本，后两者在较早的工具版本中为其列出的模型上仍然可用。browser_toolset_20260801 是浏览器使用工具的第一个版本。两者都是客户端工具集。

mcp_toolset 类型不按日期进行版本控制；其版本信息改由 anthropic-beta 头承载。

客户端工具集

计算机使用工具和浏览器使用工具是 Anthropic 定义的 "client toolsets"（客户端工具集）：tools 中的一个条目声明一组固定的成员工具，其名称、描述和输入 schema 由 Anthropic 定义，而每次调用都由您的应用程序执行。该条目不接受 name，因为带日期的 type 已固定了成员名称。configs、cache_control 和 allowed_callers（仅接受 ["direct"]）是可选的。

客户端工具集是 Messages API 工具。它们目前不能作为 Claude Managed Agents 中的智能体工具使用，后者提供自己的内置智能体工具集、MCP 工具集和自定义工具。

{
  "type": "browser_toolset_20260801",
  "configs": {
    "javascript_exec": { "enabled": true }
  },
  "cache_control": { "type": "ephemeral" }
}

configs 用于调整单个成员：

• 键是成员名称，每个值仅接受 enabled 和 defer_loading。
• 您省略的成员保持其默认值。缺失的值、{} 和重述的默认值是等效的。
• 未知的成员名称或成员值中的任何其他字段都会被拒绝，禁用所有成员的 configs 也会被拒绝（请改为省略该条目）。
• 被禁用的成员会从 Claude 可见的工具中移除。如果 Claude 仍然调用它，请返回一个错误 tool_result。

请按成员设置 defer_loading，切勿在条目上设置，并为每个启用的成员赋予相同的值：在工具搜索下，工具集作为一个定义整体加载和展开。当每个启用的成员都延迟加载时，只有本身未延迟加载的工具搜索工具才能呈现该工具集，因此请在同一请求中声明一个。不要在成员延迟加载的工具集条目上放置 cache_control；请改为在非延迟加载的工具上设置断点，因为延迟加载的定义不属于缓存前缀的一部分。

cache_control 只能放在条目上；要了解断点落在何处（包括批量操作内部的标记），请参阅工具使用与提示缓存。

处理成员工具调用。 Claude 通过一个 tool_use 块调用成员，其 name 为成员名称，toolset_name 为 computer 或 browser；input 包含该成员的参数，且没有 action 字段。请根据 toolset_name 和 name 这一对进行分派，因为自定义工具可能与某个成员同名，而且两个工具集共享诸如 screenshot 之类的名称。只有成员结果会回显 toolset_name。一个轮次中的多个成员调用构成一个批量操作，您需要按顺序运行（计算机使用、浏览器使用）。新成员只会随新的带日期 type 一起出现。

工具集条目不支持的内容。 API 会以 invalid_request_error 拒绝以下每一项：

• strict: true 或 input_examples。
• 条目上的 defer_loading，或 defer_loading 值不同的已启用成员（请在 configs 中按成员设置，且全部设为相同的值）。
• allowed_callers 中的代码执行调用方（不支持程序化工具调用）。
• 旧版 fine-grained-tool-streaming-2025-05-14 beta 头。当您进行流式传输时，每个成员的 input 以一个完整的 input_json_delta 到达。
• 指定工具集或某个成员的 tool 类型 tool_choice（请使用 auto、any 或 none）。
• 同一工具集的两个条目，或带有该工具集名称的其他工具：与 computer_toolset_20260801 并存的名为 computer 的工具，或与 browser_toolset_20260801 并存的名为 browser 的工具。这两个工具集可以一起声明。

工具定义属性

tools 数组中的每个工具（包括用户定义的工具）都接受可选属性，用于控制工具的加载方式、谁可以调用它以及如何验证其输入。这些属性可以组合使用：您可以在同一个工具上同时设置 defer_loading、cache_control 和 strict。

allowed_callers 值

allowed_callers 是一个数组，接受以下值的任意组合：

"code_execution_20260120" 和 "code_execution_20260521" 在 allowed_callers 中均被接受且可互换：使用任一代码执行工具版本的请求都能满足列出任一调用方的工具。无论请求声明的是哪个版本，响应块始终将调用方标记为 code_execution_20260120。

从数组中省略 "direct"（例如 "allowed_callers": ["code_execution_20260120"]）会引导 Claude 仅从代码执行内部调用该工具。响应的 tool_use 块包含一个 caller 字段，用于标识是哪个调用方调用了该工具。有关完整说明（包括 caller 响应结构和错误行为），请参阅程序化工具调用。

defer_loading 与提示缓存

设置了 defer_loading: true 的工具会在计算缓存键之前从渲染的工具部分中剥离。它们完全不会出现在系统提示前缀中。当工具搜索发现一个延迟加载的工具并为其返回 tool_reference 时，该工具的完整定义会在对话正文的该位置内联展开，而不是在前缀中。

这意味着 defer_loading: true 会保留您的提示缓存。您可以向请求中添加延迟加载的工具而不会使现有缓存条目失效，并且缓存在发现该工具的轮次和调用该工具的轮次之间保持有效。

要了解如何将 defer_loading 与 cache_control 断点结合使用，请参阅工具搜索工具提示缓存指南。