🏠 总目录 📚 资料库工具与 MCP

用 Agent 为 Agent 写有效的工具

⏱ 14 分钟 | ⭐ ACI:像设计 API 一样设计给模型的接口

🎯 一句话

工具是确定性接口与非确定性决策之间的契约。用途、边界、参数、返回值与错误提示要一起设计,再用代表性任务检查模型是否选对、用对并能修复错误。

本页先解决:工具的用途、参数、返回值与错误提示怎样一起验证?

Claude 博客资料库 · 工具与MCP

工具的用途、参数、返回值与错误提示怎样一起验证?

工具不仅供程序调用,也要让 Agent 能正确理解用途与限制。

读完可以:把工具用途、参数、响应和错误提示一起放入可迭代评估。

📄 来自 Claude 官方博客
原文标题
Writing Effective Tools for Agents—with Agents(用 Agent 为 Agent 写有效的工具)
原文链接
https://www.anthropic.com/engineering/writing-tools-for-agents
作者
Ken Aizawa 等(Anthropic)
发布日期
2025-09-11
⚠️ 本页是原文的中文结构化整理笔记(保留架构、数据、案例、结论),并非逐字翻译。版本、参数与案例数字属于原文所示条件,不是本资料库的实测结果;产品状态与接口以实施时官方文档为准。
📑 本页目录

为 Agent 写高质量工具需要重新思考软件开发实践:工具不是简单的函数封装,而是确定性系统与非确定性 Agent 之间的新契约。「Agent 的能力上限由我们给它的工具决定」。文章给出一套评估驱动的工具改进方法论,包括让 Agent 参与优化自己的工具。

工具不仅供程序调用,也要让 Agent 能正确理解用途与限制。

理解 Agent 工具的特殊性

先用原型暴露实际误用,再通过评估改变工具接口,而不只修改提示词。

工作流:原型 → 评估 → 迭代

1. 快速原型

2. 综合评估

生成评估任务: 基于真实工作流的几十个「提示-验证」对,避免过度简化的沙箱。强任务需要多次(甚至数十次)工具调用,例如:

运行评估: 用 API 直接跑简单 Agent 循环;让 Agent 在工具调用前输出推理和反馈块;跟踪准确率之外的指标——运行时间、调用次数、token 消耗、错误率。

分析结果: 读 Agent 的推理找困惑点;读原始转录抓 Agent 不会明说的隐式行为。例子:Anthropic 发现 Claude 会在搜索词后多余地拼接 "2025",根源是工具描述有误导。

3. 让 Claude 改进工具

把评估转录喂给 Claude Code,让它分析模式并系统性重构工具。内部实测:Claude 优化后的 Slack/Asana MCP server 性能超过专家手写版本。

用途、命名、参数、响应和错误提示一起影响可用性,逐项看五条原则。

五条工具设计原则

1. 选对工具(而非更多工具)

2. 命名空间

3. 返回有意义的上下文

4. 为 token 效率优化

5. 提示词工程化的工具描述

结论

「为 Agent 构建有效工具,需要把软件开发实践从可预测的确定性模式转向非确定性模式。」有效工具的共性:定义清晰无歧义、审慎使用 Agent 上下文、可灵活组合进多种工作流、让 Agent 能直觉地解决真实任务。与其铺开全面的工具集,不如深耕少数高影响工作流的工具,用评估驱动持续进化。


✅ 检查点

  1. 给模型的工具和给人的 API,设计取向有什么不同?
  2. 工具命名和参数设计上有哪些实用原则?
  3. 怎么评估一个工具设计得好不好?
👀 答案
  1. ⭐ 模型常依赖当前可见的描述、Schema 和示例来选择工具,也可能通过工具继续查文档;不要假设它已掌握隐藏约定。所以工具描述要自包含:说清用途、边界、参数含义、典型场景、以及什么时候不该用。另外人能容忍复杂签名,模型会被过多可选参数干扰。
  2. ①命名要表达意图而不是实现(`search_orders` 而不是 `query_db`);②参数尽量少、语义明确,能有默认值就给默认值;③避免需要模型自己拼接的格式(如复杂的查询字符串);④枚举优于自由文本——能列举的就别让它自由发挥;⑤把容易搞错的约束写进参数描述,而不是指望它记住。
  3. ⭐ 看模型在真实任务里的使用情况:①调用成功率(参数错误率高说明描述不清)②选择正确率(该用时用了吗、不该用时忍住了吗)③重试次数(高说明错误信息没帮上忙)。⚠️ 不要只看「工具本身能不能跑通」——那是最低标准。

本节回顾

先记住这几件事

  • 工具说明要包含用途、边界、参数和何时不该使用。
  • 让容易误用的条件进入参数约束,不全靠模型猜测。
  • 在真实任务中检查选用是否正确、调用是否成功、错误能否修复。