笔记 · Agent ·

工具要按 Agent 的习惯来设计

给 Agent 的工具不是 API 的简单包装。要少而准,返回有意义的信息,再用评测和 Agent 一起改。

读书笔记原文:《Writing effective tools for agents — with agents》↗Ken Aizawa · Anthropic

为什么读

以后如果要写 MCP 或给 Agent 配工具,这篇是很实用的清单。它写于 2025 年 9 月,提到的 MCP、模型版本这些会继续演变,但方法本身不太会过时。

我记下的要点

  1. 工具是一份契约: 普通函数每次调用结果一样,Agent 却可能调工具、直接凭知识回答、或者反问。所以工具要为 Agent 设计,而不只是为开发者。
  2. 别照搬 API: Agent 上下文有限,search_contacts 比 list_contacts 好;把多步操作合并,比如一个 schedule_event 代替查用户、查日程、建日程三个工具。工具太多或互相重叠会让它分心。
  3. 返回有意义的内容: 优先给名字、文件类型这类人能读懂的字段,少给 uuid 之类的底层标识。可以加一个详细 / 简洁的参数,Slack 的例子里简洁版只用了约三分之一的 token。
  4. 省 token、错误要能指路: 分页、过滤、截断都要有合理默认值;报错要具体说明怎么改,不要只丢一个错误码。
  5. 描述当成写给新同事: 把隐含的背景讲清楚,参数名不要有歧义,比如用 user_id 而不是 user。他们发现 Claude 会无故在搜索词里加上「2025」,改了描述就好了。
  6. 用评测驱动,让 Agent 帮忙改: 准备贴近真实的任务和可验证的结果,跑完把记录交给 Claude Code,让它批量重构工具。

我的想法

「把描述当成写给新同事」这条,我作为产品人特别有感觉。写 PRD 时最常见的问题就是默认对方知道背景,原来给模型写工具说明也一样。

这篇和 Vercel 那篇放在一起看挺有意思:这里讲怎么把工具设计好,那边干脆把大部分工具删了。我理解两者不矛盾,核心都是别让 Agent 在一堆相似的选项里犹豫。

我目前还不会自己写工具,评测那部分对我来说门槛偏高,先记下思路。

我打算试试

  • 找一个我常用的 MCP,看看它的工具描述写得清不清楚,按文中的标准挑挑毛病