与 agents 一起为 agents 写工具

导读

这篇文章讨论如何为 agents 写工具，也讨论如何让 Claude Code 参与工具优化。它把工具重新定义为 deterministic software 与 non-deterministic agent 之间的契约。

说明：本文按 Agent Learning 的中文阅读页格式，对原文结构与关键技术细节做逐节中文转述与解读；为避免整篇镜像转载，正文保留原文章节脉络、关键数字和术语，但不做逐字复刻。

核心观点

• agent 使用工具不是普通函数调用，而是在不确定任务状态下选择、填参、解释结果和继续行动。
• 高质量工具需要从 prototype 开始，用 agent eval 衡量真实表现。
• Claude Code 可以帮助生成 eval、分析 transcript、优化 tool descriptions 和返回格式。
• 工具命名与 namespace 要帮助模型理解功能边界，避免混用或重复调用。
• tool result 要返回 meaningful context，而不是无筛选地倾倒后端字段。
• token efficiency 是工具设计的一部分，长返回会降低后续推理质量。

正文

What is a tool?

文章先区分传统软件函数与 agent tool。传统函数面对确定性调用者，输入相同通常输出相同；agent tool 面对的是会推理、会误解、会在多种策略之间选择的模型。

当用户问“今天要不要带伞”时，agent 可能调用天气工具，也可能追问位置，甚至可能试图凭常识回答。因此，工具不是被动 API，而是 agent 的行动 affordance。

这意味着工具要按 agent 的认知方式设计：模型是否能理解何时调用、如何填参、如何解释返回、失败后如何恢复。

How to write tools

文章建议从原型和 eval 开始。不要假设工具 schema 写完就算完成；应该让 agent 在真实或代表性任务中使用它，观察 transcript 中的失败模式。

Claude Code 可以参与这个循环：它能读工具实现、生成测试任务、运行 eval、比较成功率，并提出 tool description、参数命名、返回结构上的修改。

关键是把工具优化变成可测过程。工具是否更好，不应只靠开发者感觉，而应看 agent 是否更少误调用、更少填错参数、更能从错误中恢复。

Principles for writing effective tools

第一个原则是选择正确工具边界。太底层会让 agent 做太多编排，太高层会牺牲灵活性。理想工具应贴近用户任务语义，同时保留必要控制。

第二个原则是 namespace。工具集合越大，越需要通过命名和分组向模型说明边界。否则 agent 会在功能重叠工具之间摇摆，或者把一个工具用于错误任务。

第三个原则是返回 meaningful context。模型需要知道状态、关键证据、下一步选项和错误原因；它不需要后端对象的所有字段。返回越高信号，后续推理越稳。

Looking ahead

文章的长期判断是：随着 MCP 和 agent 工具生态扩大，工具设计会成为新的产品接口设计。过去我们为人类写 UI、为程序写 API；现在还要为 agent 写 ACI。

这个接口既要服务模型，也要让人类可审计。好的工具返回、权限、日志和 eval 会让 agent 行为更可解释，而不是只提高自动化能力。

因此工具工程不是附属任务，而是 agent 产品的核心竞争力。

深度解读

这篇文章最有启发的地方，是它把 tool design 从后端工程问题转成认知接口问题。模型不会像确定性程序一样调用 API，它会根据上下文猜测、试探、修正。工具越符合模型理解任务的方式，agent 越能可靠行动。反过来，糟糕工具会让强模型变成一个不断猜参数、误读结果、重复调用的脆弱系统。未来团队可能需要像做 UX research 一样做 tool research：看 transcript，找误解点，改命名、改返回、改权限，再用 eval 验证。

落地启示

• 把工具当作 agent-facing interface 设计，而不是直接暴露内部 API。
• 建立工具 eval，比较修改前后的成功率、误调用率和 token 成本。
• 让返回值优先服务下一步决策：状态、证据、错误类型、可选动作。
• 用 namespace 和清晰 description 降低工具选择歧义。
• 让 Claude Code 参与 transcript 分析和工具迭代，但用 eval 验证结果。