Writing Effective Tools for Agents — With Agents
原标题: Writing Effective Tools for Agents — With Agents 中文标题: 为AI智能体编写高效工具——与智能体协同共创 作者: Ken Aizawa | 发布日期: 2025年9月11日 原文链接: https://www.anthropic.com/engineering/writing-tools-for-agents
一句话摘要
本文提出了一套以评估驱动、智能体协同迭代为核心的工具设计方法论，阐释如何基于模型上下文协议（MCP）为AI智能体打造真正高效的工具。
完整核心内容翻译
一、什么是"工具"？
工具代表着一种全新的软件范式——它是确定性系统与非确定性智能体之间的契约。与传统API不同，传统API面向的是行为可预测的程序调用，而智能体工具必须充分考虑智能体行为的不确定性——智能体可能产生幻觉、误解工具用途，或采取出人意料的策略。
核心挑战在于：如何在智能体有限的上下文窗口约束下设计工具，同时赋能多样化的问题解决路径。
二、如何编写工具
构建原型： 首先快速创建工具原型。使用 Claude Code 时，可提供相关文档（包括 MCP SDK 文档）。工具可以封装在本地 MCP 服务器或桌面扩展中进行测试，然后通过 claude mcp add <name> <command> 连接。
运行评估： 生成基于真实工作流的评估任务——而非简化的沙盒场景。优质任务应当是多步骤复合操作（如安排会议并附加文档和预订会议室），而非简单的搜索操作。将提示词与可验证的结果配对，使用简单的智能体循环（LLM调用与工具调用交替进行）以编程方式运行评估。采集的指标不应局限于准确率，还应包括运行时间、Token消耗量、工具调用频次和错误率。
分析结果： 审查智能体在哪些环节遇到困难，检视推理链路和原始工具调用序列，识别模式：冗余调用提示需要调整分页策略；参数错误则表明描述不够清晰。
与智能体协作： Claude Code 可以通过分析评估日志来自动改进工具。文章指出，大部分指导经验来自于反复使用智能体辅助优化内部工具的过程，并利用保留测试集防止过拟合。
三、编写高效工具的原则
选择正确的工具： 工具数量多并不等于效果好。与其包装每一个API端点，不如聚焦于智能体自然使用的"高影响力工作流"。工具应整合功能——例如，实现一个 schedule_event（查找空闲时间并安排日程）比分别提供 list_users、list_events 和 create_event 三个工具要好得多。
关键洞察："智能体拥有与传统软件截然不同的能力特征——它们感知可能行动的方式完全不同。"
命名空间管理： 将相关工具归入统一前缀（如 asana_search、asana_projects_search）。这能降低认知负荷，避免功能重叠的工具之间产生混淆。前缀式与后缀式命名在不同模型上的性能差异是可量化的。
返回有意义的上下文： 避免返回底层技术标识符（如 uuid、mime_type），转而返回语义化字段（如 name、image_url、file_type）。自然语言标识符能显著降低检索任务中的幻觉率。可选方案：暴露一个 response_format 枚举参数，允许智能体按需请求"详细"或"简洁"的响应格式，在灵活性与Token效率之间取得平衡。
优化Token效率： 实现分页、过滤和截断机制，并设置合理的默认值。Claude Code 默认将工具响应限制在 25,000 个 Token 以内。截断时应提供有用的引导，将智能体引向更有针对性的搜索而非宽泛查询。错误响应应当提供"具体且可操作的改进建议"，而非晦涩的错误代码。
精心设计工具描述： 工具描述会被加载到智能体上下文中，对性能有显著影响。应当像向新团队成员解释一样描述工具——将隐含知识显式化。明确预期的输入输出，避免模糊的参数命名（用 user_id 而非 user）。文章强调，Claude Sonnet 在优化工具描述后达到了最先进的 SWE-bench 性能。
四、成果与验证
内部评估对比了人工编写与 Claude 优化的工具：
- Slack MCP 服务器： Claude 优化版本相比人工实现展现出可量化的改进
- Asana MCP 服务器： 智能体辅助优化同样带来了性能增益
- 保留测试集揭示了超越"专家"实现的额外改进空间
五、展望
高效的智能体工具要求软件开发从确定性范式向非确定性范式转变。工具应当"被有意且清晰地定义，审慎使用智能体上下文，能在多样化工作流中灵活组合，并使智能体能够直觉式地解决现实任务。"随着智能体能力的演进和 MCP 协议的迭代，系统化、评估驱动的方法确保工具能够随能力提升而扩展。
技术要点
- 工具是确定性与非确定性之间的契约： 传统API为确定性程序设计，而智能体工具必须容纳幻觉、误解和非预期策略等不确定行为。
- 评估驱动的迭代开发： 用真实工作流生成评估任务，采集准确率、Token消耗、调用频次等多维指标，让智能体自身参与工具优化。
- 整合优于拆分： 将多个细粒度API合并为面向工作流的复合工具（如
schedule_event），减少智能体的决策负担。 - 语义化返回值降低幻觉： 返回自然语言字段而非技术ID，显著减少智能体在后续调用中产生错误引用。
- 工具描述即Prompt工程： 描述文本对模型表现影响巨大，应像向新同事解释一样编写，将隐含知识外化。
深度解读
本文的核心洞察在于将"为智能体设计工具"定义为一种全新的软件工程学科。传统软件接口假设调用者完全理解文档、严格遵循协议，而智能体作为"模糊理解者"，对工具的感知更接近人类对说明书的阅读方式——存在遗漏、误读和创造性发挥。
这一认知转变引出了几个深层启示：
首先，工具设计本质上是一种人机交互设计。工具描述不是给编译器看的类型声明，而是给"有一定理解力但会犯错的思维体"看的操作指南。这解释了为什么Prompt工程技巧（明确、具体、示例化）同样适用于工具描述。
其次，用智能体优化智能体工具形成了一个自我改进循环。Claude Code 分析自身失败案例来改进工具定义，本质上是一种"元学习"——不改变模型权重，而是改变模型与外部世界交互的界面。这比传统的人工试错效率高得多。
第三，"少即是多"的工具设计哲学挑战了工程师的直觉。在确定性编程中，细粒度API提供最大灵活性；但对智能体而言，过多选择反而增加了决策错误的概率。这与心理学中的"选择悖论"异曲同工。
延伸思考
- 随着智能体能力的提升，工具设计的最佳实践会如何演变？当模型推理能力足够强大时，是否可以回归更细粒度的工具，让智能体自行编排？
- MCP协议能否成为"智能体时代的HTTP"——一个统一的工具交互标准？当前的生态碎片化问题如何解决？
- 工具优化的自动化程度有多高的上限？是否可能实现"给定一组API文档，自动生成最优MCP工具"的全流程自动化？
- 在多智能体协作场景中，工具设计需要哪些额外考量？不同智能体对同一工具的理解差异如何处理？
本文为 Anthropic 官方工程博客文章的深度中文解读。