为智能体编写高效工具——借助智能体

发布于 2025 年 9 月 11 日

概述

智能体的能力取决于我们提供的工具。本文分享了编写高质量工具和评估的技术，以及如何使用 Claude 来优化工具以提升智能体性能。

模型上下文协议（MCP）可以为 LLM 智能体提供数百个工具来解决真实世界任务。但我们如何让这些工具发挥最大效用？

涵盖的关键技术

本文描述了如何：

• 构建和测试工具原型
• 创建并运行智能体工具的综合评估
• 与 Claude Code 等智能体协作自动提升工具性能
• 识别编写高质量工具的关键原则

什么是工具？

工具代表一种新型软件，反映了确定性系统与非确定性智能体之间的契约。与总是产生相同输出的传统函数调用不同，即使输入相同，智能体也可能生成不同的响应。

当用户问"我今天应该带伞吗？"时，智能体可能会调用天气工具、根据常识回答，或提出澄清问题。智能体偶尔会产生幻觉或误解工具用法。

这需要从根本上重新思考软件设计——不是像为开发者编写传统 API 那样编写工具，而是专门为智能体设计。目标是扩大智能体能够使用多种策略有效解决问题的范围。

如何编写工具

构建原型

首先快速创建工具原型。如果使用 Claude Code 编写工具，请提供软件库、API 或 SDK 的文档。LLM 友好的文档通常存在于官方网站的 llms.txt 文件中。

将工具封装在本地 MCP 服务器或桌面扩展中，以便在 Claude Code 或 Claude 桌面应用中连接和测试。

连接到 Claude Code： 运行 claude mcp add <name> <command> [args...]

连接到 Claude 桌面版： 导航到 Settings > Developer 或 Settings > Extensions

工具也可以直接传递给 Anthropic API 调用进行程序化测试。

自己测试工具以发现粗糙之处，并收集关于预期用例的用户反馈。

运行评估

通过运行评估来衡量 Claude 使用工具的效果。首先生成大量基于真实世界用途的评估任务，然后与智能体协作分析结果并确定改进措施。工具评估手册提供了端到端指导。

生成评估任务

Claude Code 可以快速探索工具并创建数十个提示-响应对。提示应受真实世界用途启发，并基于真实的数据源和服务。避免使用过于简单的"沙盒"环境，它们无法用足够的复杂性对工具进行压力测试。

强任务的例子：

• 安排下周与 Jane 开会讨论我们最新的 Acme Corp 项目。附上我们上次项目规划会议的笔记并预订会议室。
• 客户 ID 9182 报告他们在单次购买尝试中被扣款三次。找出所有相关日志条目并确定是否有其他客户受到相同问题影响。
• 客户 Sarah Chen 刚刚提交了取消请求。准备一个留存方案。确定：（1）他们为什么离开，（2）什么留存方案最具吸引力，（3）在提供方案前我们应该注意的任何风险因素。

弱任务的例子：

• 安排下周与 jane@acme.corp 开会。
• 在支付日志中搜索 purchase_complete 和 customer_id=9182。
• 按客户 ID 45892 查找取消请求。

每个评估提示都应配对一个可验证的响应或结果。验证器可以从精确字符串比较到基于 Claude 的判断。避免使用过于严格的验证器，因为格式或标点符号差异而拒绝正确响应。

可以选择指定你期望智能体调用的工具，但避免过度指定策略，因为可能存在多个有效的解决路径。

运行评估

使用直接的 LLM API 调用以程序化方式运行评估，使用简单的智能体循环（交替进行 LLM API 和工具调用的 while 循环）。每个智能体应该接收单个任务提示和工具访问权限。

在系统提示中，指示智能体在工具调用之前输出推理和反馈块，这会触发思维链行为并提高有效性。

如果使用 Claude 运行评估，请启用交错思考以获得类似功能。这有助于识别智能体为什么调用或不调用某些工具，并揭示工具描述和规范中需要改进的地方。

收集超出顶层准确率的指标：总运行时间、工具调用次数、令牌消耗和工具错误。跟踪工具调用可以揭示常见工作流程和整合机会。

分析结果

智能体是识别工具描述、实现和模式问题的有益伙伴。但是，请注意省略的反馈可能比包含的反馈更重要。

观察智能体在哪里困惑。通读推理和反馈（或思维链）以识别粗糙之处。审查包括工具调用和响应的原始转录，以捕获智能体推理中未明确描述的行为。

分析工具调用指标。冗余调用建议调整分页或令牌限制；无效参数错误建议需要更清晰的描述或示例。在推出 Claude 的网络搜索工具时，团队发现 Claude 不必要地在搜索查询中附加"2025"，使结果产生偏差。改进工具描述解决了这个问题。

与智能体协作

让智能体分析结果并自动改进工具。连接评估转录并将它们粘贴到 Claude Code 中。Claude 擅长分析转录并同时重构多个工具，同时保持自我一致性。

本文中的大多数建议来自使用 Claude Code 反复优化内部工具实现。评估是在反映真实工作流程复杂性的内部工作区上创建的。

团队依赖保留的测试集来防止对训练评估的过拟合。这些揭示了超出专家实现的额外性能改进，无论是手动编写还是 Claude 生成的。

编写高效工具的原则

为智能体选择正确的工具

更多工具并不总是改善结果。一个常见错误是包装现有软件功能或 API 端点，而不考虑它们是否适合智能体。

智能体与传统软件有不同的"可供性"——感知潜在行动的不同方式。LLM 智能体有有限的上下文（处理能力约束），而计算机内存便宜且充足。

考虑搜索地址簿。传统软件高效地逐个处理联系人。但是，如果智能体接收所有联系人并逐个令牌读取，它会将有限的上下文空间浪费在不相关的信息上。更好的方法是首先跳到相关条目，按字母顺序。

构建一些针对特定高影响力工作流程的精心设计的工具，匹配评估任务，然后扩展。与其实现 list_contacts，不如考虑 search_contacts 或 message_contact 工具。

工具可以整合功能，在底层处理多个离散操作。例子包括：

• 不是单独的 list_users、list_events 和 create_event 工具，而是实现一个 schedule_event 工具来查找可用时间并安排
• 不是 read_logs，而是实现 search_logs 仅返回带有上下文的相关行
• 不是单独的 get_customer_by_id、list_transactions 和 list_notes 工具，而是实现 get_customer_context 编译最近的相关信息

每个工具都应该有清晰、独特的目的。工具应该使智能体能够像拥有相同资源的人类一样细分和解决任务，同时减少中间输出消耗的上下文。

太多或重叠的工具会分散智能体对高效策略的注意力。精心、选择性规划要构建（或避免）的工具会带来显著回报。

为工具命名空间

智能体可能访问数十个 MCP 服务器和数百个工具，包括来自其他开发者的工具。重叠或目的模糊的工具会导致混淆。

命名空间（在公共前缀下对相关工具进行分组）有助于划定边界。例如，按服务（例如 asana_search、jira_search）和按资源（例如 asana_projects_search、asana_users_search）进行命名空间有助于智能体选择适当的工具。

前缀与后缀命名对评估有非平凡影响。影响因 LLM 而异——根据您自己的评估选择命名方案。

通过实现名称反映自然任务细分的工具，您可以减少加载到智能体上下文中的工具和描述，同时将计算从上下文卸载到工具调用本身。这降低了总体错误风险。

从工具返回有意义的上下文

工具实现应该只向智能体返回高信号信息，优先考虑上下文相关性而非灵活性。避免使用像 uuid、256px_image_url、mime_type 这样的低级技术标识符。相反，使用 name、image_url、file_type。

智能体处理自然语言名称、术语和标识符的成功率显著高于晦涩的标识符。将任意字母数字 UUID 解析为语义上有意义的语言（甚至 0 索引 ID）显著提高了 Claude 在检索任务中的精度，通过减少幻觉。

有时智能体需要灵活性来与自然语言和技术标识符交互以进行下游调用（例如 search_user(name='jane') -> send_message(id=12345)）。通过公开 response_format 枚举参数来启用此功能，允许智能体控制工具返回"简洁"还是"详细"响应。

ResponseFormat 枚举示例：

enum ResponseFormat {
   DETAILED = "detailed",
   CONCISE = "concise"
}

详细响应提供包含技术标识符的全面信息（206 个令牌），而简洁响应仅返回基本内容（72 个令牌）。这允许智能体检索 ID 以进行进一步工具调用，同时在仅需要内容时节省令牌。

工具响应结构——XML、JSON 或 Markdown——也会影响评估性能。不存在一刀切的解决方案，因为 LLM 在匹配训练数据的格式上表现更好。根据您自己的评估选择响应结构。

优化工具响应的令牌效率

虽然上下文质量很重要，但上下文数量也很重要。对于消耗大量上下文的响应，实施分页、范围选择、过滤和/或具有合理默认参数的截断。Claude Code 默认将响应限制为 25,000 个令牌。

随着有效的智能体上下文长度增长，上下文高效的工具仍然至关重要。

截断响应时，用有用的指导引导智能体。直接鼓励更令牌高效的策略，比如进行多次有针对性的搜索而不是单次广泛搜索。发生错误时，通过提示工程响应来传达具体、可操作的改进，而不是不透明的错误代码或回溯。

截断响应的例子：

显示带有分页指导的查询响应："返回前 10 个结果。使用 offset 参数获取更多结果。"

无用的错误响应例子：

返回：Error: 400 Bad Request

有用的错误响应例子：

返回：Error: Invalid customer_id format. Expected numeric ID (e.g., customer_id="12345"), received: "jane". Try searching by name first: search_customers(name="jane")

截断和错误响应引导智能体采取更令牌高效的行为或提供正确格式的输入示例。

提示工程您的工具描述

最有效的改进方法之一是提示工程工具描述和规范。这些加载到智能体上下文中，并共同引导智能体采取有效的工具调用行为。

编写描述和规范时，考虑如何向新团队成员描述工具。使隐式上下文显式——专门的查询格式、小众术语定义、资源关系。

通过严格的数据模型清晰描述预期输入和输出来避免歧义。输入参数应明确命名：使用 user_id 而不是 user。

评估提示工程改进的影响。即使对工具描述的小改进也会产生戏剧性的改进。Claude Sonnet 3.5 在精确工具描述改进后在 SWE-bench Verified 上实现了最先进的性能，大幅减少了错误并提高了任务完成率。

其他最佳实践出现在开发者指南中。如果为 Claude 构建工具，请阅读有关工具如何动态加载到 Claude 系统提示中的内容。对于 MCP 服务器，工具注释披露哪些工具需要开放世界访问或进行破坏性更改。

展望未来

构建有效的智能体工具需要将软件开发从可预测、确定性的模式重新导向非确定性模式。

通过描述的迭代、评估驱动过程，成功工具的一致模式浮现出来：它们被有意且清晰地定义，明智地使用智能体上下文，在多样化工作流程中组合在一起，并使智能体能够直观地解决真实世界任务。

随着智能体交互机制的发展——从 MCP 协议更新到底层 LLM 改进——系统性、评估驱动的工具改进方法确保它们与日益强大的智能体共同发展。

致谢

由 Ken Aizawa 撰写，得到了来自研究、MCP、产品工程、营销、设计和应用 AI 团队同事的贡献。