Anthropic 的 Agent 工具设计理念

Anthropic 发布过一篇很有分量的文章《Writing effective tools for agents》，讲的核心问题是：为什么给 AI Agent 用的工具不能照搬传统 API 设计？

这个问题在实际使用 Claude Code 的过程中感触特别深。同样一个任务，工具设计好的时候 AI 一步到位，设计差的时候它反复调用五六次还出错。根本原因不是 AI 不聪明，而是工具没有按照 AI 的工作方式来设计。

核心矛盾：确定性 API vs 非确定性 AI

传统软件开发追求确定性——同样的输入必须产生同样的输出，接口定义严格，错误处理穷举。这套思维在机器对机器的场景里很有效。

但 AI Agent 不是机器。它的特点是：

用确定性的工具设计思维服务非确定性的 AI，这是大多数 Agent 产品难用的根源。

Anthropic 在文章中给出了一个观察：工具数量超过 10 个之后，Agent 的选择准确率和执行效率会明显下降。

这和我在 Claude Code 中的体验一致。当 MCP server 挂载了太多工具时，Claude 经常在不该用的工具上犹豫，或者在几个功能重叠的工具之间来回切换。

反面例子：分别提供 get_user、get_user_profile、get_user_settings 三个工具。AI 每次都要先搞清楚该调哪个，经常调错。

正面例子：提供一个 get_user_info 工具，通过参数控制返回的详细程度。AI 只需要做一次调用决策。

在配置 MCP server 的时候，如果你发现同一个领域有超过 5 个工具，先考虑能不能合并。

传统 API 返回的是机器友好的数据：

{
  "usr_id": "usr_1a2b3c",
  "evt_sts": 1,
  "loc_cd": "rm_501_bld_a",
  "ts_utc": 1703808000
}

AI 拿到这个数据后还要做一轮「翻译」才能理解含义，然后再翻译成自然语言回复用户。每多一层翻译就多一层出错的可能。

更好的做法是直接返回有语义的数据：

{
  "participant": "张三 (产品经理)",
  "meeting_status": "已确认",
  "location": "A栋501会议室",
  "time": "今天下午2点"
}

Claude Code 的内置工具就遵循这个原则。比如 git status 的结果不是原始 porcelain 格式，而是经过处理的、AI 容易理解的结构化信息。这是它执行效率高的原因之一。

给 AI 的信息太少它做不了判断，太多它抓不住重点。Anthropic 推荐的做法是分层信息架构——默认返回关键摘要，按需展开详细信息。

在 Claude Code 中，这个原则体现在子代理系统的设计上。Explore 代理做快速搜索时只返回文件路径和匹配行；只有明确需要深入分析时才展开完整内容。这样 AI 的注意力始终集中在最相关的信息上。

实际操作建议：如果你在自定义 MCP server 的工具，给返回值加一个 detail_level 参数（summary / detailed / full），让 AI 自己选择需要多少信息。

把 Anthropic 的设计理念对照国内主流 AI Agent 产品，几个问题特别突出：

工具数量堆砌：很多产品宣传「支持 100+ 工具」，实际上工具之间功能高度重叠，AI 的选择困难症比用户还严重。Claude Code 目前核心工具也就十来个（Read、Write、Edit、Bash、Glob、Grep、Agent 等），但每个工具边界清晰、功能不重叠。

返回数据机器化：工具返回原始 JSON 或机器格式数据，AI 需要额外步骤解析。对话轮数一多，错误就累积。

缺少失败引导：传统 API 返回错误码，AI 不知道下一步该做什么。好的工具设计应该在失败时返回「为什么失败」和「建议的下一步操作」，帮助 AI 自我修正。

即使你不开发 Agent 产品，这些设计原则对日常使用 Claude Code 也有直接帮助：

MCP server 配置：不要贪多。挂载 3-5 个高质量的 MCP server 比挂载 20 个效果好。每个 server 的工具数量控制在合理范围内
CLAUDE.md 编写：这本质上也是一种「工具设计」——你在设计 AI 的工作规则。写清晰的规则比写长的规则更重要
Prompt 设计：给 AI 的指令也是一种接口。说清楚要什么（目的性导向）、给够上下文（认知友好）、控制输出范围（信息分层）
自定义工具：如果你在做 MCP 自定义开发，把这三个原则当作设计检查清单