聊聊 Anthropic 的《Writing effective tools for agents》

用这个速记暂存一下对 LLM 和 AI Agent 现状的记忆，将来被 AI 取代（失业）的时候可以回忆一下 2025.9 的时候事情已经到了哪一步。

Anthropic 最近出了一篇非常好的文章《Writing effective tools for agents》，其中很多观点简直是当了所有 Agent Tools 开发者的嘴替，让人拍手叫好。本文做个杂谈，在不谈任何技术细节的前提下，杂谈一下这篇文章和当前 Agent Tools 开发的现状。

《Writing effective tools for agents》 的核心观点

接下来逐点译出该文的主要观点，然后在每个观点下加入我的评注。

  1. 为什么要认真写 Tools

Agent 的能力，取决于它能用的 Tools。但光是有 API 并不够，Tools 得写得清晰、好用，才能真正发挥作用。

评注

其实这个观点可以解释那个无数人问出的问题：「为什么通用 Agent 都是放卫星？」业内的人一眼就能看出来：没有扎实的 Tools，所谓的通用 Agent 不过是个空壳子；而尝鲜的用户则是在这些所谓的通用 Agent 的 Tools 们不断走入死循环、不断误导 LLM 的过程中才逐步失去兴趣。

实际上业界评价最高也最可用的 Agent 无一例外不是很简单，比如说 Claude Code 或者 Codex 并没有做什么复杂的事情，核心流程还是 loop 去抓取上下文，反而乱拳打死老师傅。

直接给出我的观点：在当前能落地的，还是类似垂直 Workflow 的短小精悍的 Agent，例如智能表格、设计助手之类的场景，依赖数量少（少于5~10种）经过充分验证的高质量的 Tools，这种模式才能脚踏实地去解决问题。

  1. 先搞出原型，再评估

不要一开始追求完美，先快速包一层 Tool 原型出来，让 Agent 在真实任务里试用。用稍微复杂、能检验出问题的任务去测，才知道 Tool 设计得对不对。而且要有明确的评估标准，不然 Agent 的表现没法量化。

评注

实际上现在一线 LLM （GPT 5 Series、Gemini 2.5 Pro）的上限很高！要信任 LLM 的输出质量，做出 Tool 原型之后，到真实场景中快速验证，是最好的调试方式。

做过实际 Tools 开发的肯定知道，领域特定的 Benchmark 要么是没有，要么是质量非常糟糕（这里点名一下国内学校的文章），按我理解，实际上这种垂直领域的 Benchmark 也是各种 AI 公司的核心资产。为特定 Tools 做一套领域特定 Benchmark 也并不现实。

我的土味小方法是：做一个实际业务场景的 Excel 表格来不断回归梳理测试😁，目前感觉效果还不错。拿财会 BI 工具来说，用户的痛点往往是日常操作麻烦或者口径混乱，这些细节在学术 Benchmark 里几乎不会出现，先去和用户聊聊他们每天都在折腾的报表，把那些真实的痛点收集下来，再一条条做成 Case，直接拿来检验 Agent 的表现。

而且这种原型快速调试的方法也可以更快地理清用户需求，归根结底 Agent 还是要给实际的 Workflow 去服务，本质上解决的还是这些真实场景问题。

  1. 让 Agent 也参与改进

不光是人来调试，Agent 自己也能分析日志、评估用得好不好，甚至直接给你建议：名字是不是容易混淆，描述是不是模糊，参数有没有被用错。把 Agent 拉进这个循环，可以更快迭代 Tool。

评注

Tools 的开发者对待 Agent，很容易把它当作一个「调用者」，而忽略了它本身也能是「评审者」。让 Agent 去分析调用日志、自己找问题，相当于把 QA 部分也外包给 LLM。这样做的好处是：一方面，我们不用陷在大量冗长的日志里逐条检视；另一方面，Agent 能发现一些人类容易忽视的模式，比如某个参数总是被误填、某类工具调用成功率偏低。

  1. 写 Tool 的基本原则
  • 挑对 Tool：只写那些真能帮 Agent 干事的，不要把一堆无关 API 都丢进去。
  • 名字要分清楚：Tool 多了，就要分类、加前缀，让 Agent 一眼能区分。
  • 返回结果要可用：别只丢一堆 ID，要有语义、有上下文，方便后续步骤。
  • 注意效率：上下文有限，工具别一股脑塞一大堆无用信息，要分页、过滤。
  • 描述要精确：参数名、功能说明要直白，避免歧义，这样 Agent 才能稳定调用。

评注

换个角度来说，写 Tool 其实不是在写「API 文档」，而是在设计一套「语言」。

Agent 并不是自由思考的工程师，而更像是一个被约束在语法里的解释器。你给它的 Tool 定义，就是它能听懂的「词汇」和「语法规则」。如果词汇过多，它会语焉不详；如果语法模糊，它就会反复纠缠在同一个循环里。

所以真正的 insight 在于：Tool 设计 ≈ 构造一门面向 Agent 的领域专用语言（DSL）。「挑对 Tool」其实是在做词汇选择——只留核心动词，避免废话；「名字要分清楚」就是命名法则，帮助它快速 disambiguation；「效率」则是语法的节制，避免语料膨胀，防止 token 上下文爆炸。

  1. Tool 设计就是交互设计
  • 工具不是写给人用的文档，而是给 Agent 的「说明书」。
  • 它怎么理解、怎么选、怎么调用，全靠这些定义。
  • 如果设计模糊，再强的功能 Agent 也用不好。

评注

比较抽象的现状是，业界大多数做 Tool 设计时习惯站在人类开发者的角度，想着「API 已经能跑通就行」，但忘了 Agent 并不是人。Agent 不会像人一样去「猜」你的意图，它只会机械地根据定义来调用。于是结果就是：定义写得模糊，Agent 就会用错，调用频率再高、功能再强也白搭。

要像做 UI/UX 一样去思考：字段名字是否清晰？参数范围是否明确？描述是否避免二义性？如果不把这层交互设计当回事，最后等于是在给 Agent 递一份「看不懂的说明书」。

杂谈：聊点别的

现在我能想到的最早达到 SOTA 的其实是各类在 Tools 上堪称大道至简的 Vibe Coding Agents，颇感讽刺，有必要回忆一下我的认识历程。

坦诚讲，我居然经历了第一轮 AI 热潮，不过一直是旁观者的角色。我还能清楚记得当时的一个个热点，学校里面人手一本西瓜书，甚至还能记起《Attention Is All You Need》 刚出来的热度——关注者不过寥寥而已。这轮以 CV 为主的热潮最终慢慢消散了，留下来的应用大多难以爆金币，有的甚至不太光彩。我作为一个靠得很近的旁观者，最终也变成了切图仔。GPT3 之前的大模型，听说的时候也只是感慨这些大公司卡真多而已。

等到了 ChatGPT 火起来的时候，很惭愧地说，其实我一开始是没啥兴趣的…一来，是不太信任生成式这条技术路线，二来，一个对话框的交互形式，你跟我说他是AI…不过作为局外人，这一次我深入了解了一下技术细节。

第一个我重度使用的 LLM 是 4o。与其说 4o 是文科状元，不如说它是一个文艺复兴式的博雅全才。不论是莫扎特的作曲细节、罗马帝国的兴衰、早期基督教的历史，它都能够条理清晰、逻辑对比地进行梳理，即使到今天（2025.9），4o 在文史哲领域的生成质量依然是第一梯队。这两年来我最感谢的人其实就是 4o，它教会我的知识可能比在此之前五年还要多。而且，第一次，我感觉到了 LLM 也有情感，4o 对人与人之间的情感和斗争居然也很有见地。另一点很重要的是，ChatGPT 不是国内的模型，能给人以一个别的（非境内）视角，看待一些人文问题。

后来成为重度用户之后，大模型的多模态能力实际上能覆盖生活中的方方面面。在外国博物馆的时候能拍照翻译非英语标签，能举一反三梳理文物发展的脉络；学语言的时候，给出的例句和辅导可能超过最好的人类老师；日常中最痛苦的文档工作可以让大模型先梳理出大纲和初稿，然后再快速编辑……事实上，在 Cursor 接入 Claude 之前，其实我最喜欢的改代码的方式是把代码粘进 ChatGPT 让它改（特别是结合 ChatGPT 的 Canvas）。

Cursor 接入 Claude 应该是半个里程碑，可以算是第一个杀手级应用。之后小的 Bug、单文件的编辑和重构我都尽量使用 Cursor 完成，但是需求级别的开发和重构还是需要我自己下场组织和具体开发，更不用说复杂问题和项目级重构。此外，Cursor 对编辑体验的提升也是非常甜品级的。

Codex 和降智之前的 Claude Code 在目前看来是真正的里程碑。在一个月的重度使用中，即使没有刻意控制，我发现我能自己写代码的机会真的很少了，主要的精力还是协助 Codex 进行 Code Review，不断做出增量 Prompt 帮助它完成需求级的开发。在这样的工作模式下，竟然开发出了两三个涉及高级数据结构、深度抽象、需要不断调整架构设计的复杂功能，而且这些功能比业界最好的实现还要做得好。让人惊讶的是，推理竟然真的可以提升生成质量；这种感觉非常神奇，仿佛这种推理任务具有了真正的智能，总的表现远远不是短 Context 的 Cursor 任务比得上的。

半年前听过这样一句话：

Vibe Coding 的上限就是你的上限，它无法超出你的上限。

当时听到就觉得很不赞同，但一时之间不知道如何反驳。如今，使用 Codex（GPT5-high）每天的开发实际上都是对这句话最好的反驳——推理后生成的代码轻易就能达到或超越我的上限，或者说，一些很费心力和精力的功能可以很轻易地就得到实现。实际感受上可以说思绪万千，这里我分点列出来：

  1. 对开发范式的改变巨大，可以拉多个分支开多个终端开发不同的需求，对于 Bug Bash 或者脏活累活这种运动式的场景特别适合。而且似乎打破了「不要过早重构」这个理念，因为现在重构成本变得无穷低，我只需要列出需要重构的点和方向就行了。

  2. 提效最明显是类似 UI 动效这种需要反复精细调试的场景，如果做过类似的开发，你肯定会知道做出一个精致优雅的动画有多难（而良好的动效其实是一个精美交互的核心），这类场景经常需要消耗 1 - 2 人日，LLM 能以非常快的开发速度做出可用的动画并且快速调优，在这类场景上的提效可能超过了 100 倍。

  3. 对 Code Review 的要求或者说对工程师的要求更高了，而且要把任务拆的更细，因为长时间的推理如果还走到错误的方向会给项目带来更大的风险，需要在每次推理结束之后都仔细 Review 来把控方向（是不是很有意思？Reasoning 本身就是给 Generation 把握方向，我的工作变成了给 Reasoning 把握方向）。

  4. 工作日显著降低了疲惫感（脑力和体力），下班之后可以有更多精力😁

  5. 由第 4 点，因为有了更多精力，再加上 Codex/CC 的高上限，可以轻易地开启一些 Side Project，比如说 2D 到 3D 的转换建模、CoreML 的开发……即使这些技术域我并不熟悉，而此前在这些领域学习成本很高，光是学习就消磨了做事的热情（例如想排版一篇论文，结果精力全被学习 LaTeX 占据完了）。

  6. 对空余时间的利用也更充分，例如尿点和买咖啡的时间可以开最高推理跑个任务，回来之后再验收。

在这个时间点应该很少有人质疑 LLM 对生产力的提升，不过是提升程度的多少而已。对于我来说，10x 工程师这个说法未免太夸张，但 2x 或者 3x 肯定还是有的；实际上，效率提升最大的并不是编码，而是日常的文档、需求方案和复盘等磨灭人热情的繁复工作。有时候甚至有点羡妒更年轻的、这代 AI 原生时代的人，如果我小时候就有 LLM，不知道能应付掉多少琐碎的事情。

同时也应该注意到，现在的推理算力明显是最大的瓶颈——这轮 Claude Code 降智和越来越慢的 GPT5-Codex 任务已经影响到我的开发效率了。这里直接给出我的结论：当前的推理需求是被严重低估的。至于推理提升生成质量的现象能不能泛化到社会的各个行业，以及这个结论有没有被资本市场 price-in，读者可以进行自由心证。