把工具说明书写给一个不看的人
约 3 分钟0 阅读
我给 Agent 配工具的时候，犯过一个特别开发者式的错。
我给每个工具写了详尽的描述——背景、用途、参数解释、注意事项、示例，像个正经的 API 文档，洋洋洒洒几百字。我以为写得越详细，Agent 越会用。结果调用错误率高得离谱，它该用 A 工具的时候老去用 B，参数也常填错。
我一度以为是模型理解力不行。直到我对比了几个调用日志，发现一个细节：它根本没在「读」我写的描述，它在「扫」。
Agent 不读文档，它扫文档
这是我想了很久才接受的事实。模型在决定调用哪个工具时，它对每个工具描述的注意力是有限的——它会快速扫一遍所有工具的关键信息，抓住最显眼的几个词做决策。那些详尽的解释、周到的背景介绍，对它来说不是帮助，是噪音。
我的工具描述里有句话：「此工具用于查询库存，注意仅在有效期内可用，建议先用 X 确认状态。」模型要的是「查库存」三个字。但我把「查库存」埋在了一堆「注意」「建议」里，模型扫过去，抓到的是「确认状态」，于是它先去调了 X 工具，然后乱了套。
它不是没看见我写的，是我写的关键信息被淹没了。
砍成 API 注释
我把所有工具描述重写了一遍，原则就一条：像写 API 注释，不像写文档。
- 第一句：这个工具干什么。短句，主谓宾。
- 第二句：什么时候该用它，什么时候别用。
- 然后：参数说明，每个一行，类型和含义。
没了。背景、注意事项、示例，全删。一个工具描述从几百字砍到三五句。
效果立竿见影——调用错误率断崖式下降。模型扫一眼就抓到「查库存」「返回库存数量」「参数：商品 ID」，该用就用，参数填对，干净利落。
三个让 Agent「看得见」的写法
重写过程中我总结了几个原则：
- 把用途放第一句。Agent 扫描述时，第一句话权重最高。别铺垫，直接说这个工具干啥。
- 用对比说边界。「这个工具查库存；要改库存用 X」比单说「这个工具查库存」更有效——给了它区分的锚点。
- 参数名要自解释。别叫
id，叫productId。Agent 靠参数名猜填什么，名字清楚它能猜对。
一个反直觉的发现
这次改造给我最大的触动是：给 Agent 写工具描述，目标不是「讲清楚」，是「让它一眼选对」。
这俩不一样。讲清楚是人读文档的标准——读完了理解了就行；一眼选对是 Agent 的标准——它不会读完，它只会扫。你得把决策需要的信息，塞进它扫的那几眼能抓到的位置。
所以我后来给工具写描述，心里想的是一个根本不会认真读的用户——他会跳着看、抓关键词、然后做决定。写给这样的读者，描述自然就短、准、可扫。
收尾
那批 Agent 稳定下来后，我把「工具描述精简法」写进了项目规范。新人来配工具，第一版描述总爱写长，我让他们砍——砍到只剩用途、边界、参数三件事。
他们一开始不情愿，觉得砍掉了重要信息。但上线一对比错误率就服了。Agent 跟人不一样，它不需要被说服，它需要被引导。短而准的描述，就是最好的引导。