Anthropic 智能体工具开发指南：从原型到优化，附 Claude 协作技巧

智能体的效能取决于我们为其提供的工具。我们将分享如何编写高质量的工具和评估方法，以及如何利用Claude自我优化工具来提升性能。

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

本文我们将介绍在各种智能体AI系统中提升性能的最有效技术。

我们首先介绍如何：

• 构建和测试工具原型
• 创建并运行全面的工具评估（通过智能体）
• 与Claude Code等智能体协作，自动提升工具性能

最后总结我们在实践中得出的编写高质量工具的关键原则：

• 选择正确的工具实现（及避免实现的工具）
• 通过命名空间划分工具功能边界
• 从工具向智能体返回有意义的上下文
• 优化工具响应的token效率
• 提示工程优化工具描述和规范

构建评估体系可以帮助你系统地衡量工具的性能。你可以利用 Claude Code 根据该评估结果自动优化你的工具。

什么是工具？

在计算领域，确定性系统在给定相同输入时每次都会产生相同输出，而非确定性系统（如智能体）即使在相同初始条件下也可能产生不同的响应。

传统软件开发是在确定性系统之间建立契约。例如，像getWeather("NYC")这样的函数调用，每次都会以完全相同的方式获取纽约市的天气数据。

工具是一种新型软件，它反映了确定性系统与非确定性智能体之间的契约。当用户询问"今天需要带伞吗？"时，智能体可能调用天气工具，根据常识回答，甚至先询问位置信息。有时，智能体可能会产生幻觉或无法理解工具的使用方法。

这意味着我们需要从根本上重新思考为智能体编写软件的方法：不应像为其他开发人员或系统编写函数和API那样编写工具和MCP服务器，而需要为智能体设计它们。

我们的目标是通过使用工具来追求各种成功策略，扩大智能体有效解决各种任务的范围。幸运的是，根据我们的经验，对智能体最"符合人体工学"的工具最终对人类来说也出奇地直观。

如何编写工具

在本节中，我们将介绍如何与智能体协作编写和改进工具。首先快速建立工具原型并进行本地测试，然后运行全面评估以衡量后续更改。与智能体协作，您可以重复评估和改进工具的过程，直到智能体在现实任务中表现出色。

构建原型

如果不亲自动手，很难预测智能体会觉得哪些工具好用，哪些不好用。首先快速建立工具原型。如果使用Claude Code编写工具（可能一次性完成），最好为Claude提供工具所依赖的任何软件库、API或SDK（可能包括MCP SDK）的文档。LLM友好文档通常可以在官方文档网站的扁平llms.txt文件中找到（这是我们的API文档）。

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

要将本地MCP服务器连接到Claude Code，运行claude mcp add <名称> <命令> [参数...]。

要将本地MCP服务器或DXT连接到Claude桌面应用，分别导航到设置 > 开发者或设置 > 扩展。

工具也可以直接传入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不必要地在工具的查询参数后附加2025，偏置搜索结果并降低性能（通过改进工具描述将Claude引导到正确方向）。

与智能体协作

您甚至可以让智能体分析结果并为您改进工具。只需将评估智能体的记录连接起来并粘贴到Claude Code中。Claude是分析记录和一次性重构大量工具的专家——例如，确保在进行新更改时工具实现和描述保持自一致。

事实上，本文中的大部分建议来自使用Claude Code反复优化我们的内部工具实现。我们的评估建立在内部工作空间之上，反映了内部工作流程的复杂性，包括真实项目、文档和消息。

我们依赖保留测试集确保不会过度拟合"训练"评估。这些测试集显示，即使超越"专家"工具实现（无论这些工具是由研究人员手动编写还是由Claude自身生成），我们仍能提取额外的性能改进。

在下一节中，我们将分享从这一过程中学到的一些经验。

编写有效工具的原则

在本节中，我们将所学提炼为一些编写有效工具的指导原则。

为智能体选择正确的工具

更多工具并不总是带来更好的结果。我们观察到一个常见错误是工具仅仅包装现有软件功能或API端点——无论这些工具是否适合智能体。这是因为智能体与传统软件具有不同的"可供性"——也就是说，它们感知可以使用这些工具采取的潜在行动的方式不同。

LLM智能体的"上下文"有限（即它们一次可以处理的信息量有限），而计算机内存廉价且丰富。以在地址簿中搜索联系人的任务为例。传统软件程序可以高效地存储和处理联系人列表，一次检查一个然后继续。

然而，如果LLM智能体使用返回所有联系人的工具，然后必须逐个token阅读每个联系人，它就在无关信息上浪费了有限的上下文空间（想象一下通过从上到下阅读每一页来在地址簿中搜索联系人——即通过暴力搜索）。更好更自然的方法（对智能体和人类 alike）是首先跳到相关页面（可能按字母顺序找到它）。

我们建议构建一些针对特定高影响力工作流程的周到工具，与您的评估任务匹配，并从此扩展。在地址簿案例中，您可能选择实现search_contacts或message_contact工具，而不是list_contacts工具。

工具可以整合功能，在底层处理 potentially 多个离散操作（或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枚举参数来实现两者，允许智能体控制工具返回"简洁"还是"详细"响应（下图）。

您可以添加更多格式以获得更大灵活性，类似于GraphQL，您可以选择确切想要接收的信息片段。以下是控制工具响应详细程度的ResponseFormat枚举示例：

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

以下是一个详细工具响应的示例（包含206个 tokens）：

以下是一个简洁工具响应的示例（包含72个 tokens）：

Slack中的主题对话及其回复通过唯一的thread_ts标识符来区分，这些标识符是获取回复所必需的。thread_ts以及其他标识符（如channel_id、user_id）可以从“详细”工具响应中获取，以便后续需要这些信息的工具调用。而“简洁”工具响应仅返回主题对话内容，不包含标识符。在这个示例中，我们使用了“简洁”工具响应中约三分之一的标记数量。

即使是工具响应结构——例如XML、JSON或Markdown——也会对评估性能产生影响：没有一刀切的解决方案。这是因为LLM经过下一token预测训练，往往在与其训练数据匹配的格式上表现更好。最优响应结构因任务和智能体而异。我们鼓励您根据自身评估选择最佳响应结构。

优化工具响应的token效率

优化上下文质量很重要。但优化在工具响应中返回给智能体的上下文数量也很重要。

我们建议为任何可能消耗大量上下文的工具响应实现分页、范围选择、过滤和/或截断的某种组合，并设置合理的默认参数值。对于Claude Code，我们默认将工具响应限制为25,000个token。我们期望智能体的有效上下文长度随时间增长，但对上下文高效工具的需求将保持不变。

如果选择截断响应，请确保通过有用指令引导智能体。您可以直接鼓励智能体追求更token高效的策略，例如在知识检索任务中进行多次小型定向搜索，而不是单次广泛搜索。同样，如果工具调用引发错误（例如在输入验证期间），您可以提示工程错误响应，以清晰传达具体和可操作的改进，而不是模糊的错误代码或回溯。

以下是截断工具响应示例：

以下是无效错误响应示例：

以下是有效错误响应示例：

工具截断和错误提示可以引导代理采用更高效的使用工具的方式（例如使用过滤器或分页功能），或者提供正确格式化的工具输入示例。

提示工程优化工具描述

现在我们来到改进工具的最有效方法之一：提示工程优化工具描述和规范。因为这些内容会加载到智能体的上下文中，它们可以共同引导智能体采取有效的工具调用行为。

编写工具描述和规范时，思考如何向团队新成员描述您的工具。考虑您可能隐含带来的上下文——专业查询格式、利基术语定义、底层资源之间的关系——并将其明确化。通过清晰描述（并通过严格数据模型强制执行）预期输入和输出避免歧义。特别是，输入参数应明确命名：与其使用名为user的参数，不如尝试使用user_id参数。

通过评估，您可以更自信地衡量提示工程的影响。即使对工具描述进行微小改进也能产生显著改善。在我们对工具描述进行精确改进后，Claude Sonnet 3.5在SWE-bench Verified评估中实现了最先进的性能，显著降低了错误率并提高了任务完成度。

您可以在我们的开发指南中找到工具定义的其他最佳实践。如果为Claude构建工具，我们还建议阅读工具如何动态加载到Claude系统提示中的相关内容。最后，如果为MCP服务器编写工具，工具注释有助于披露哪些工具需要开放世界访问或进行破坏性更改。

展望未来

要为智能体构建有效工具，我们需要将软件开发实践从可预测的确定性模式重新定位到非确定性模式。

通过本文描述的迭代、评估驱动过程，我们确定了工具成功的 consistent 模式：有效工具是 intentional 和清晰定义的，明智地使用智能体上下文，可以在多样化工作流程中组合使用，并使智能体能够直观解决现实世界任务。

未来，我们期望智能体与世界交互的具体机制将不断发展——从MCP协议更新到底层LLM本身升级。通过系统化、评估驱动的方法改进智能体工具，我们可以确保随着智能体能力增强，它们使用的工具也将随之发展。（来源）