MCP 一接，工具数量很容易冲到三位数。但堆接口不等于变强——原文那句 Agents are only as effective as the tools we give them 说得刻薄也实在：工具是确定性系统和会走神、会创新的模型之间的契约，不是又一个 REST 封装。[1]
Anthropic 自己承认：文里不少段落，就是团队用 Claude Code 迭代内部工具时从 transcript 里抠出来的。产线可以压成一句：先粗糙可跑 → 上评测 → 对着 transcript 改 → 再抽象成原则。[1]
文首提示
- 主线：Agent 工具「新契约」→ 原型—评测—迭代 → Slack/Asana 内测叙事 → 五大原则 是什么 → 落地 意味着什么。
- 深度：文内
### 深度解析与 材料勘读；文末 结论与讨论 与 延伸阅读。
一、工具不是「又一个 REST API」
传统软件里，getWeather("NYC") 是确定性契约。Agent 里用户问「要不要带伞」，模型可能调天气、靠常识、先追问城市——甚至用错工具。[1]
所以你要为「像人类白领一样会误触按钮的同事」设计接口，而不是只为编译器写函数。[1]
人话：别一比一照搬内部微服务；先问「人类拿到这个按钮会怎么用」。[1]
二、推荐产线：原型 → 评测 → 与 Agent 协作改进
2.1 搭原型
先立可跑的粗糙版，本地接 MCP 或在 Desktop extension（DXT） 里试。[1]
用 Claude Code 写工具时，把依赖库/API 文档喂全；官方文档常见 llms.txt 扁平摘要，利于模型读。[1]
本地接到 Claude Code：claude mcp add <name> <command> ...；也可把工具直接塞进 API 做程序化试跑。[1]
中文场景：先做 search_customer_notes 能返回「片段+时间+作者」，别先做 export_full_database。
2.2 跑评测（Eval）
任务要「像真工单」：原文给了强任务与弱任务对照——强任务往往要多跳、多工具、带附件与跨系统协调；弱任务则偏「一句话指令」或「单条 SQL 式」检索。[1]
每条任务应配可验证结果：从简单字符串比对，到用 Claude 当裁判（原文提醒 verifier 别过严，避免格式标点误杀正确回答）。[1]
可选：标注「期望调用的工具」以衡量是否 grasp 工具意图——但避免过拟合唯一策略，因正确路径常不止一条。[1]
运行方式：建议程序化 agent loop（while 交替 LLM 与 tool）；评测用 system prompt 让模型输出推理/反馈块（可在 tool 前输出以触发类 CoT）；用 Claude 时可开 interleaved thinking 便于分析「为啥没调某工具」。[1]
指标（原文列举） ：单任务/单工具耗时、工具调用次数、token、工具错误等——用于发现可合并的工作流、该分页的参数等。[1]
内测叙事（文中图表） ：内部 Slack、Asana MCP：人类手写 vs Claude 优化 在 hold-out 测试集上的表现对比。[1]
2.3 把 transcript 丢回给 Agent 改工具
把评测 transcript 拼进 Claude Code，可一次性重构多工具，保持描述与实现自洽。[1]
Anthropic 强调用 held-out 测试集防过拟合；并发现有时 Claude 生成的实现还能在测试集上超过「专家手写」——以原文表述为准。[1]
三、五大原则（原文精华压缩）
3.1 选对工具，别堆一百个半吊子
反例：通讯录若 list_contacts 返回全体联系人，Agent 只能像「翻电话本逐页读」一样烧上下文。[1]
正例：优先 search_contacts、message_contact 等跳转到相关页的能力。[1]
工具可合并多步：如 schedule_event 代替「查空闲+建日程」三连；search_logs 代替整段 read_logs；get_customer_context 聚合客户侧信息。[1]
要点：每个工具目的单一清晰；重叠少；让人类工程师在任一情境下能唯一选对工具，Agent 才有一致机会。[1]
3.2 命名空间（Namespacing）
多 MCP、数百工具时，用 asana_search / jira_search 、再细到 asana_projects_search 等前缀分层，减少「撞名与模糊边界」。[1]
前缀/后缀策略对不同模型影响非平凡，应靠自家评测选方案。[1]
3.3 返回「有意义」的上下文
优先 name、可读 URL、file_type，少甩 raw UUID、256px 图链 等低信号字段——必要时再暴露技术 ID 供下一步调用。[1]
把难读的 ID 解析成语义化或简单编号，常能减幻觉、提检索精度。[1]
可用 response_format（如 concise / detailed）让 Agent 控制 verbosity：detailed 里带 thread_ts 等继续操作所需 ID；concise 只给正文省 token。[1]
3.4 Token 效率：质与量都要
分页、范围、过滤、合理默认截断；原文称 Claude Code 对工具响应默认约 25,000 tokens 上限一类实践（以当前产品文档为准）。[1]
截断时要提示下一步：鼓励多次小搜索，而非一次巨查询；错误信息要可行动，别只抛 opaque code。[1]
3.5 把描述与 schema 当 prompt 工程
像给新同事写说明：术语、查询格式、资源关系写清楚；参数名 user_id 优于 user 。[1]
小改描述也可能带来巨大评测提升（文中有 SWE-bench 相关叙述）。[1]
更多规范见 Developer Guide、MCP tool annotations（开放世界/破坏性操作披露）等——以官网为准。[1]
深度解析：评测里「Claude 超过手写」的可迁移条件
事实：原文称 held-out 集上有时 Claude 重构的工具可超过专家实现。[1]
原文观点：transcript 驱动迭代、防过拟合。[1]
本文解读：该结论依赖 任务分布与 verifier 设计——若 verifier 过松或过严，排序会变；迁移到你的域时，保留 人类可读 transcript 与 双盲 spot check 比迷信单次分数重要。
四、中文速记表（帮助落地会议）
| 原则 | 一句话 |
|---|---|
| 少而准 | 高影响工作流优先，能合并就合并 [1] |
| 分得清 | 前缀 + 资源粒度，避免撞车 [1] |
| 回得对 | 高信号字段 + 可选详细度 [1] |
| 省 token | 分页截断 + 友好错误 [1] |
| 写得像给人看 | 描述=另一次 prompt 工程 [1] |
五、思辨延伸（非 Anthropic 结论）
金融合规：工具返回中的客户标识、金额字段需脱敏分级与权限模型，与「高信号」原则并行设计。
组织治理：工具清单应版本化、可审计；谁有权加「破坏性工具」要走评审。
与系列其它篇：第 3 篇讲平台级 Tool Search / PTC，本篇讲单个工具与工具集如何写得值得被搜、值得被代码编排。[1]
材料勘读：发布稿里没写清的事：内测图表与可公开复现性
事实：Slack/Asana 叙事与图表来自 Anthropic 内测。[1]
原文观点：评测驱动、工具描述即 prompt。[1]
本文解读（推断） ：对外分享时不应复述未公开的精确百分比为新标准——应强调 方法论（强任务、held-out、transcript 迭代）。
结论与讨论
技术坐标
本文把工具设计从 「给编译器用的 API」 转到 「给非确定性 Agent 用的契约」，并把 评测—transcript—迭代 写进标准产线——与后续平台级「工具搜索/代码编排」形成上下层关系。
批判性问题
- Verifier 是否过拟合格式而误杀正确行为？
- 工具合并后是否模糊了 审计粒度（谁在何时调了什么）？
- 命名空间策略是否已在多模型上交叉验证？
独立判断（事实 / 原文观点 / 本文解读）
| 类型 | 内容 |
|---|---|
| 事实 | 原文 URL；五大原则与 MCP 相关引用。[1] |
| 原文观点 | Agents are only as effective as the tools；原型—评测闭环。[1] |
| 本文解读 | 最值得买的是 「强任务 + held-out」 文化；原则列表离开评测易沦为口号。 |
能力、默认 token 上限与 CLI 子命令以 Claude / Anthropic 最新文档为准。
参考文献与延伸阅读
- [1] Writing effective tools for AI agents — with agents — 原文
- Advanced tool use（平台层）
- Model Context Protocol
- 若先读系列前几篇建立 Agent 模式观，再读本篇，更容易理解「为何工具要当产品做」。
