模型上下文协议（MCP）可以为 LLM 智能体提供可能数百种工具来解决现实世界的任务。但我们如何让这些工具发挥最大效力呢？
在本文中，我们描述了在各种智能体 AI 系统中提高性能的最有效技术¹。
我们首先介绍如何做到以下几点：
- 构建和测试工具原型
- 创建并运行工具与智能体的综合评估
- 与 Claude Code 等智能体协作，自动提高工具性能
最后，我们总结了一路上识别出的高质量工具编写关键原则：
- 选择要实现（和不要实现）的正确工具
- 为工具命名空间以定义功能的清晰边界
- 从工具向智能体返回有意义的上下文
- 优化工具响应的 token 效率
- 为工具描述和规范进行提示工程
构建评估可以让你系统性地衡量工具性能。你可以使用 Claude Code 基于这种评估自动优化工具。
什么是工具？
在计算机科学中，确定性系统在给定相同输入时总是产生相同输出，而非确定性系统（如智能体）即使在相同的起始条件下也可能产生不同的响应。
当我们传统上编写软件时，我们建立的是确定性系统之间的契约。例如，像 getWeather("NYC") 这样的函数调用总是以完全相同的方式获取纽约市的天气，无论何时调用都是如此。
工具是一种新型软件，它反映了确定性系统与非确定性智能体之间的契约。当用户询问「今天我应该带伞吗？」时，智能体可能会调用天气工具，从一般知识中回答，甚至可能首先询问关于位置的澄清问题。有时，智能体可能会产生幻觉，甚至无法理解如何使用工具。
这意味着在为智能体编写软件时需要从根本上重新思考我们的方法：我们需要为智能体设计工具和 MCP 服务器，而不是像为其他开发者或系统编写函数和 API 那样。
我们的目标是增加智能体在解决广泛任务中有效的表面区域，通过使用工具来追求各种成功策略。幸运的是，根据我们的经验，对智能体来说最「人性化」的工具最终对人类来说也出奇地直观易懂。
如何编写工具
在本节中，我们描述了如何与智能体合作编写和改进你提供给它们的工具。首先搭建工具的快速原型并在本地测试。接下来，运行综合评估来衡量后续变化。与智能体一起工作，你可以重复评估和改进工具的过程，直到你的智能体在现实世界任务中实现强大的性能。
构建原型
如果不亲自动手，很难预测智能体会发现哪些工具人性化，哪些不会。首先搭建工具的快速原型。如果你使用 Claude Code 来编写工具（可能一次完成），给 Claude 提供你的工具将依赖的任何软件库、API 或 SDK（包括可能的 MCP SDK）的文档会很有帮助。LLM 友好的文档通常可以在官方文档站点的 llms.txt 平面文件中找到（这是我们 API 的）。
将你的工具包装在本地 MCP 服务器或桌面扩展（DXT）中，将允许你在 Claude Code 或 Claude Desktop 应用中连接和测试你的工具。
要将本地 MCP 服务器连接到 Claude Code，运行 claude mcp add <name> <command> [args...]。
要将本地 MCP 服务器或 DXT 连接到 Claude Desktop 应用，分别导航到 设置 > 开发者 或 设置 > 扩展。
工具也可以直接传递到 Anthropic API 调用中进行程序化测试。
自己测试工具以识别任何粗糙的边缘。收集用户反馈，建立对你期望工具能够支持的用例和提示的直觉。
运行评估
接下来，你需要通过运行评估来衡量 Claude 使用你的工具的效果如何。首先生成大量基于现实世界用途的评估任务。我们建议与智能体协作来帮助分析结果并确定如何改进工具。在我们的工具评估指南中查看这个端到端过程。
我们内部 Slack 工具的保留测试集性能
生成评估任务
利用你的早期原型，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 循环）：每个评估任务一个循环。每个评估智能体应该被给予单个任务提示和你的工具。
在你的评估智能体的系统提示中，我们建议指导智能体不仅输出结构化响应块（用于验证），还输出推理和反馈块。指导智能体在工具调用和响应块之前输出这些内容可能通过触发思维链（CoT）行为来增加 LLM 的有效智能。
如果你使用 Claude 运行评估，你可以启用交错思维来获得类似的「现成」功能。这将帮助你探索智能体为什么调用或不调用某些工具，并突出工具描述和规范中的具体改进领域。
除了顶级准确性，我们建议收集其他指标，如单个工具调用和任务的总运行时间、工具调用总数、总 token 消耗和工具错误。跟踪工具调用可以帮助揭示智能体采用的常见工作流程，并提供一些工具整合的机会。
我们内部 Asana 工具的保留测试集性能
分析结果
智能体是你在发现问题和提供从矛盾工具描述到低效工具实现和令人困惑的工具模式等方面反馈的有用伙伴。但是，请记住，智能体在反馈和响应中遗漏的内容往往比它们包含的内容更重要。LLM 并不总是说出它们的意思。
观察你的智能体在哪里感到困惑或混乱。阅读你的评估智能体的推理和反馈（或 CoT）以识别粗糙的边缘。审查原始记录（包括工具调用和工具响应）以捕获智能体 CoT 中未明确描述的任何行为。读懂言外之意；记住你的评估智能体不一定知道正确答案和策略。
分析你的工具调用指标。大量冗余的工具调用可能表明需要对分页或 token 限制参数进行一些适当调整；大量无效参数的工具错误可能表明工具需要更清晰的描述或更好的例子。当我们推出 Claude 的网络搜索工具时，我们发现 Claude 不必要地在工具的 query 参数后附加 2025，这偏向了搜索结果并降低了性能（我们通过改进工具描述引导 Claude 朝正确方向发展）。
与智能体协作
你甚至可以让智能体为你分析结果并改进工具。只需将评估智能体的记录连接起来并粘贴到 Claude Code 中。Claude 擅长分析记录并一次重构许多工具，例如，确保工具实现和描述在进行新更改时保持自我一致。
事实上，这篇文章中的大部分建议都来自于与 Claude Code 反复优化我们内部工具实现。我们的评估建立在我们内部工作区之上，反映了我们内部工作流程的复杂性，包括真实的项目、文档和消息。
我们依靠保留测试集来确保我们没有过度拟合「训练」评估。这些测试集揭示我们可以提取额外的性能改进，甚至超越我们通过「专家」工具实现所达到的，无论这些工具是由我们的研究人员手动编写还是由 Claude 本身生成。
在下一节中，我们将分享从这个过程中学到的一些东西。
编写有效工具的原则
在本节中，我们将我们的学习提炼为编写有效工具的几个指导原则。
为智能体选择正确的工具
更多工具并不总是导致更好的结果。我们观察到的一个常见错误是工具只是包装现有软件功能或 API 端点，无论工具是否适合智能体。这是因为智能体与传统软件具有不同的「可供性」，也就是说，它们对可以用这些工具采取的潜在行动有不同的感知方式。
LLM 智能体有有限的「上下文」（也就是说，它们一次可以处理的信息量是有限的），而计算机内存便宜且丰富。考虑在通讯录中搜索联系人的任务。传统软件程序可以有效地存储和处理联系人列表，一次一个，在继续之前检查每一个。
但是，如果 LLM 智能体使用一个返回所有联系人的工具，然后必须逐个 token 地阅读每一个，它就是在不相关信息上浪费其有限的上下文空间（想象通过从上到下阅读每一页，即通过暴力搜索，在你的通讯录中搜索联系人）。更好、更自然的方法（对智能体和人类都是如此）是首先跳到相关页面（也许按字母顺序找到它）。
我们建议构建少数几个针对特定高影响工作流程的深思熟虑的工具，这些工具与你的评估任务相匹配，然后从那里扩展。在通讯录案例中，你可能选择实现 search_contacts 或 message_contact 工具，而不是 list_contacts 工具。
工具可以整合功能，在底层处理可能的多个离散操作（或 API 调用）。例如，工具可以用相关元数据丰富工具响应，或者在单个工具调用中处理经常链接的多步任务。
以下是一些例子：
- 与其实现
list_users、list_events和create_event工具，考虑实现一个schedule_event工具，它查找可用性并安排事件。 - 与其实现
read_logs工具，考虑实现一个search_logs工具，它只返回相关日志行和一些周围上下文。 - 与其实现
get_customer_by_id、list_transactions和list_notes工具，实现一个get_customer_context工具，它一次性编译客户的所有最近和相关信息。
确保你构建的每个工具都有明确、不同的目的。工具应该使智能体能够以与人类相同的方式细分和解决任务，在获得相同底层资源的情况下，同时减少否则会被中间输出消耗的上下文。
过多的工具或重叠的工具也可能让智能体从追求高效策略中分心。仔细、选择性地规划你构建（或不构建）的工具确实会有很大回报。
为工具命名空间
你的 AI 智能体可能会获得对数十个 MCP 服务器和数百个不同工具的访问，包括其他开发者的工具。当工具在功能上重叠或目的模糊时，智能体可能会对使用哪些工具感到困惑。
命名空间（在通用前缀下分组相关工具）可以帮助在大量工具之间划定边界；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 枚举参数来启用两者，允许你的智能体控制工具是否返回 "concise" 或 "detailed" 响应（下面的图片）。
你可以添加更多格式以获得更大的灵活性，类似于 GraphQL，你可以选择你想要接收的确切信息片段。以下是控制工具响应详细程度的 ResponseFormat 枚举示例：
enum ResponseFormat {
DETAILED = "detailed",
CONCISE = "concise"
}
以下是详细工具响应的例子（206 个 token）：
以下是简洁工具响应的例子（72 个 token）：
Slack 线程和线程回复由唯一的 thread_ts 标识，这是获取线程回复所必需的。thread_ts 和其他 ID（channel_id、user_id）可以从 "detailed" 工具响应中检索，以启用需要这些的进一步工具调用。"concise" 工具响应只返回线程内容并排除 ID。在这个例子中，我们使用 "concise" 工具响应用了约 1/3 的 token。
甚至你的工具响应结构，例如 XML、JSON 或 Markdown，都可能对评估性能产生影响：没有一种适合所有情况的解决方案。这是因为 LLM 在下一个 token 预测上训练，倾向于用匹配其训练数据的格式表现更好。最佳响应结构会因任务和智能体而广泛变化。我们鼓励你基于自己的评估选择最佳响应结构。
优化工具响应的 token 效率
优化上下文质量很重要。但优化返回给智能体的工具响应中的上下文数量也很重要。
我们建议为任何可能使用大量上下文的工具响应实现分页、范围选择、过滤和/或截断的某种组合，并具有合理的默认参数值。对于 Claude Code，我们默认将工具响应限制为 25,000 个 token。我们预期智能体的有效上下文长度会随时间增长，但上下文高效工具的需求会保持。
如果你选择截断响应，一定要用有用的指令指导智能体。你可以直接鼓励智能体追求更多 token 高效的策略，比如为知识检索任务进行许多小而有针对性的搜索，而不是单个广泛的搜索。同样，如果工具调用引发错误（例如，在输入验证期间），你可以提示工程你的错误响应以清楚地传达具体和可行的改进，而不是不透明的错误代码或回溯。
以下是截断工具响应的例子：
以下是无用错误响应的例子：
以下是有用错误响应的例子：
工具截断和错误响应可以引导智能体朝着更多 token 高效的工具使用行为（使用过滤器或分页）或给出正确格式化工具输入的例子。
为工具描述进行提示工程
我们现在来到改进工具最有效的方法之一：为你的工具描述和规范进行提示工程。因为这些被加载到你的智能体上下文中，它们可以共同引导智能体朝向有效的工具调用行为。
在编写工具描述和规范时，想想你会如何向团队中的新员工描述你的工具。考虑你可能隐含带来的上下文，专门的查询格式、小众术语的定义、底层资源之间的关系，并使其明确。通过清楚地描述（并用严格的数据模型强制执行）预期的输入和输出来避免歧义。特别是，输入参数应该被明确命名：与其使用名为 user 的参数，不如尝试名为 user_id 的参数。
通过你的评估，你可以更有信心地衡量提示工程的影响。即使对工具描述的小调整也能产生戏剧性的改进。在我们对工具描述进行精确调整后，Claude Sonnet 3.5 在 SWE-bench Verified 评估上实现了最先进的性能，大大降低了错误率并改善了任务完成。
你可以在我们的开发者指南中找到工具定义的其他最佳实践。如果你为 Claude 构建工具，我们也建议阅读关于工具如何动态加载到 Claude 的系统提示中。最后，如果你为 MCP 服务器编写工具，工具注释有助于披露哪些工具需要开放世界访问或进行破坏性更改。
展望未来
要为智能体构建有效的工具，我们需要将我们的软件开发实践从可预测、确定性模式重新定向到非确定性模式。
通过我们在这篇文章中描述的迭代、评估驱动过程，我们已经识别出使工具成功的一致模式：有效的工具是有意且清楚定义的，明智地使用智能体上下文，可以在多样化工作流程中组合在一起，并使智能体能够直观地解决现实世界任务。
在未来，我们预期智能体与世界交互的具体机制会演化，从 MCP 协议的更新到底层 LLM 本身的升级。通过系统性、评估驱动的改进智能体工具方法，我们可以确保随着智能体变得更有能力，它们使用的工具将与它们一起演化。
致谢
本文由 Ken Aizawa 编写，研究部门的同事们（Barry Zhang、Zachary Witten、Daniel Jiang、Sami Al-Sheikh、Matt Bell、Maggie Vo），MCP 团队（Theo Chu、John Welsh、David Soria Parra、Adam Jones），产品工程团队（Santiago Seira），市场团队（Molly Vorwerck），设计团队（Drew Roper），以及应用 AI 团队（Christian Ryan、Alexander Bricken）都做出了宝贵贡献。
¹ 除了训练底层 LLM 本身之外。
原文链接：https://www.anthropic.com/engineering/writing-tools-for-agents