Claude API Tools

Claude API Tools 是 Anthropic 在 Claude Messages API 中把模型连接到外部能力的一组工具机制。开发者可以提供自定义工具 schema，让 Claude 返回结构化 tool_use 请求；也可以启用 Anthropic 提供的 server tools，由 Anthropic 基础设施直接执行搜索、抓取、代码运行等能力。

这个词条是本库的综述视角，用来归纳 Claude Platform Docs 里的工具层。它和 Function Calling（函数调用）讨论的是同一类模型能力，但使用 Anthropic 的 API 术语：模型输出 tool_use block，应用或平台执行工具，再把 tool_result 放回下一轮消息。

两类执行位置

Claude 工具最重要的边界不是“工具叫什么”，而是工具在哪里执行：

类型	执行者	API 形态	工程含义
Client tools	开发者应用	Claude 返回 `stop_reason: "tool_use"` 和一个或多个 `tool_use` block	应用必须解析参数、执行函数、回传 `tool_result`
Server tools	Anthropic 平台	Anthropic 执行工具并把结果放入响应	应用不需要写 handler，但要理解费用、引用、失败和安全边界

开发者自定义工具属于 client tools：你写 input_schema、工具说明和执行代码。Claude 只生成结构化调用意图；数据库查询、付款、文件写入或内部 API 调用仍由你的 Harness Engineering（驾驭工程）执行。

Anthropic 的 server tools 包括 Web search、Web fetch、Code execution、Advisor 和 Tool search 等。它们降低了接线成本，但不是“无成本工具”：除普通输入/输出 token 外，部分 server tools 还会按使用量计费。

Anthropic-schema client tools

Claude 还提供一类介于自定义函数和 server tools 之间的工具：Anthropic-schema client tools。Anthropic 发布并训练模型理解这些工具 schema，但执行仍发生在开发者应用里。

典型例子包括：

Memory tool：跨会话读写开发者控制的文件
Bash tool：在持久 shell session 中运行命令
Text editor tool：查看和修改文本文件
Computer use tool：通过截图、鼠标和键盘操作桌面环境

这类工具说明了一个常被忽视的分层：schema 由平台标准化，不等于执行由平台托管。只要工具结果需要应用回填，权限、沙箱、审计和错误处理仍然属于应用 harness。

工具调用循环

Claude client tools 的基本循环如下：

sequenceDiagram
    participant U as User
    participant A as App / Harness
    participant C as Claude
    participant T as Client Tool
    U->>A: 用户请求
    A->>C: messages + tools(input_schema)
    C-->>A: stop_reason=tool_use + tool_use blocks
    A->>T: 执行工具
    T-->>A: 工具结果
    A->>C: tool_result
    C-->>A: 最终回答或继续 tool_use
    A-->>U: 回复 / 动作结果

这个循环和 Agent Loop（智能体循环）是同一结构的 API 表达：模型负责选择动作，应用负责执行动作，并把观察结果重新放进上下文。

当同一轮里出现多个工具调用时，应用不能假设“最多一个”。多个只读查询可以并行执行；有顺序依赖或写入副作用的调用应由 harness 串行化，并接入 Agent Guardrails（Agent 护栏）。

Claude Agent SDK位于更高抽象层：它不是只返回 tool_use block 让应用自己实现工具循环，而是复用 Claude Code 的内置工具执行、权限、Hook、session、MCP 和 subagent 机制，在应用进程中直接运行 Agent Loop。需要完全自定义工具协议时，用 Messages API 更底层；需要 Claude Code 风格的文件系统和命令执行 Agent 时，Agent SDK 更省 harness 代码。

触发控制

默认 tool_choice 是 {"type": "auto"}：Claude 会根据用户请求和工具描述判断是否调用工具。工具触发边界可以通过三层方式控制：

工具描述：说明什么时候该用、什么时候不该用
系统提示：例如要求先用工具调查，再回答
tool_choice 参数：在 API 层要求或限制工具调用

这和 Agent-Computer Interface（智能体计算机接口）一致：工具名称、description、schema 和触发说明，就是模型看到的工具界面。描述含糊时，模型不是“懒得用工具”，而是没有足够明确的接口信号。

Strict tool use

Claude 支持在自定义工具定义中设置 strict: true，要求工具调用严格匹配 schema。它解决的是结构合规问题：字段、类型、枚举和值形状更稳定。

但 strict schema 不等于业务安全。模型生成的 tool_use 参数即使完全符合 schema，应用仍要做权限检查、业务校验、风险分级和人工审批。这一点和 Structured Outputs（结构化输出）及 Function Calling（函数调用）的边界相同：schema 正确只说明“形状对”，不说明“该执行”。

MCP 与工具生态

Claude 工具层可以和 Model Context Protocol（模型上下文协议）组合使用。MCP connector 让 Messages API 连接远程 MCP 服务器；更底层地看，MCP 负责外部服务如何发现和暴露工具，Claude API tools 负责把这些能力放进当前模型请求，让 Claude 决定是否调用。

当工具数量很大时，Anthropic 的 Tool search tool 提供按需发现和加载工具的模式。它和 Context Engineering（上下文工程）中的 Select 策略一致：不要把全部低频工具一次性塞进上下文，而是让模型先找到当前任务需要的能力。

Anthropic 的 MCP 代码执行式用法是同一问题的另一种工程解法：把 MCP server 暴露为代码 API，让 Agent 在代码执行环境里按需读取工具文件、调用 MCP 工具、处理中间数据，再把摘要或少量样本返回模型。它不改变 Claude tool_use / tool_result 的底层语义，但改变了 harness 给模型呈现工具的方式：模型看到的是可探索的代码接口，而不是一次性展开的巨大工具列表。

成本含义

Claude 工具调用的成本来自三部分：

tools 参数中的工具名、说明和 schema 会进入输入 token
tool_use 和 tool_result blocks 会进入后续请求/响应
部分 server tools 有额外的按量费用

此外，只要请求中提供工具，Claude API 会加入启用工具能力所需的系统提示 token。工程上这意味着：工具不是免费的按钮。工具越多、schema 越大、循环越长，成本和上下文压力越高，也越需要 Prompt Caching（提示缓存）、工具裁剪和 trace 评估。

工具可用性设计

Anthropic 的工具工程建议可以看作 Claude API Tools 的上层方法论：工具要按 Agent 的使用方式设计，而不是机械映射底层 API。一个工具是否“好用”，要通过真实任务 eval 和 raw trace 判断。

实践上有几条高频规则：

优先提供贴近工作流的少量高层工具，而不是把每个内部 API 端点都暴露给模型
用服务名、资源名或动作名做清晰命名空间，减少相似工具之间的混淆
工具响应默认返回高信号、任务相关字段；需要技术 ID 时再提供详细格式
对长结果提供分页、过滤、范围选择或可解释截断，避免工具结果吞掉上下文窗口
错误响应要给出可行动的修正建议，让模型知道下一次应该怎么改参数

这些规则同样适用于 client tools、MCP connector 暴露的工具，以及 Claude Agent SDK里接入的外部工具。

与 OpenAI API Tools 的对照

OpenAI API Tools（OpenAI API 工具）和 Claude API Tools 都在解决“模型如何调用外部能力”，但术语和执行边界不同：

维度	Claude API Tools	OpenAI API Tools
自定义调用输出	`tool_use` block	`function_call` / tool call item
工具结果回填	`tool_result`	`function_call_output` / tool output
执行位置分类	client tools / server tools / Anthropic-schema client tools	function tools / hosted tools / remote MCP / custom tools
大工具集策略	Tool search server tool	`tool_search` 延迟加载

两者的共同点更重要：模型只负责提出动作意图；真正可靠的系统要靠工具接口设计、harness 执行、权限治理、错误处理和评估闭环。