- Authors
- Name
- Youngju Kim
- @fjvbn20031
工具加多了，成功率反而掉了
假设给智能体多接了五个工具，任务成功率反而下降。这是构造的例子，但拓宽过工具表面的团队都会觉得方向眼熟。原因有两层：工具的 schema 每一轮都在吃上下文预算；相似的工具越多，选择就越晃。让模型能做更多事，和让它把眼前这个任务做得更好，是两码事。
所以工具表面这个说法很有用：设计对象不是一个个工具，而是模型面对的整个接口。Anthropic 的智能体构建指南把它叫作智能体-计算机接口，并建议像打磨人类 UI 一样打磨它。他们自己在 SWE-bench 工作中花在优化工具上的时间比整体提示词还多——这段回顾说明了这条建议的分量。
工具数量的诅咒：全部暴露还是精选
第一个要定的是数量。把手头的工具全部暴露，准备起来省事，但光是 schema 就把预算吃掉一块，相似工具之间的误选也会增加。相反，只挑本任务用得上的工具来暴露的精选（curation），才应该是大多数工作的默认值。有余力的话还有一个选项：为这个任务专门造一个工具，叠在精选之上。专用工具有构建和维护成本，但能把好几次调用压成一次。
Anthropic 的工具编写指南推荐的整合（consolidation）就在这条延长线上。与其把列出用户、列出日程、创建日程各做成一个工具，不如做一个在内部处理完这些步骤的"安排日程"工具。工具数量降下来，schema 成本、误选、调用往返一起降。
名字和描述就是接口
模型看不到你的代码，只看得到名字和描述。所以一行描述就能改变行为。同一份指南推荐按服务和资源给名字加前缀的命名空间做法。像 asana_search 和 jira_search 这样让前缀说明归属，即使有好几个相似的搜索工具，模型也不容易搞混。
# 坏例子 —— 这是干什么的、什么时候用，全靠模型猜
- name: proc2
description: '进程工具'
# 好例子 —— 什么时候用它、什么时候用别的，都写在描述里
- name: code_search_symbol
description: '在仓库中查找符号的定义位置。全文搜索请用 code_grep。'
好描述的标准，就是你会递给新同事的入职文档：这个工具做什么、什么时候用、什么时候不要用、返回长什么样。描述写得越好，提示词里那些解释工具用法的段落就越少。
参数设计：用结构堵住错误
参数要朝着减少模型出错点的方向设计。Anthropic 的智能体指南把这比作制造业的防错法（poka-yoke）：不是纠正错误，而是造出一个没法犯错的结构。比如同时接受相对路径和绝对路径的参数，工作目录一变就成了错误源头；收窄到只接受绝对路径，这一类错误就从结构上消失了。标识符也是一样。工具编写指南的观察是：让模型使用人类可读的名字，而不是不知所云的 UUID，准确率会上升。
失败要怎么交回去
工具会失败。设计对象不是失败本身，而是失败回到模型手里的格式。把异常字符串和堆栈原样丢回去，模型往往不知道原因，重复同一个调用。把失败原因和当前可尝试的替代方案结构化返回，下一次调用就会不一样。
{
"error": "file_not_found",
"path": "src/pay/handler.py",
"hint": "这个仓库的源码根目录是 services/。",
"try_next": ["list_dir services/pay", "code_search_symbol handler"]
}
这个格式与第 4 篇要讲的重试策略直接纠缠。没有原因返回的重试，是对同一次失败的重复购买；有替代方案返回的重试，才是探索。先修好失败返回格式，再定重试上限，顺序应当如此。
响应也是表面：token 效率
工具返回的响应会原封不动地从上下文预算里扣走。所以工具编写指南把分页、范围选择、过滤、带合理默认值的截断放在工具这一侧的责任清单上。把 4000 行文件整个返回的读取工具，不如默认 200 行、接受范围参数的读取工具。截断了就要在响应里说明截断这件事，并附上如何更精确检索的提示——做到这一步才算设计完成。
工具也是被评估的对象
工具表面不是造完就结束的东西，而是要靠评估来打磨的对象。同一份指南推荐的循环很朴素：先做原型，用贴近现实的任务跑评估，读智能体留下的记录找它在哪里迷路，改工具，再量一次。改一行工具描述也是框架变更，所以它是第 7 篇要讲的框架指纹必须抓住的变更。而判定哪个表面更好的，归根结底是评估者——它的可靠性是第 5 篇的主题。
亲手练习
在框架工程 RPG 里，你可以把四种工具表面换着插进任何场景：最小 3 个、按任务精选 8 个、精选加专用工具、全部暴露 21 个。把"全部暴露被 schema 成本压垮"和"最小配置被绕路成本拖垮"两种场景都经历一遍，精选是默认值的理由就会留在手感里。
参考资料
- Writing effective tools for agents — Anthropic, 2025-09-11 —— 命名空间、工具整合、有意义的标识符、token 高效的响应、评估循环都在这篇文章里。
- Building effective agents — Anthropic, 2024-12-19 —— 智能体-计算机接口的视角、防错参数设计、SWE-bench 工作中在工具上花的时间比提示词多的回顾都在这篇文章里。
- 开头的成功率故事与正文中的 schema、失败返回示例是为说明而构造的。