Writing effective tools for AI agents—using AI agents
打开互动全文版（逐段中英对照 + 图/公式 + 论文问答）→智能体的效能取决于我们赋予的工具。我们分享如何编写高质量工具和评估方法，以及如何通过让 Claude 自我优化工具来提升性能。模型上下文协议（MCP）可以为 LLM 智能体提供数百个工具来解决实际任务。但如何使这些工具发挥最大效用？在本文中，我们描述了在多种智能体 AI 系统中提升性能的最有效技术。
Agents are only as effective as the tools we give them. We share how to write high-quality tools and evaluations, and how you can boost performance by using Claude to optimize its tools for itself. The Model Context Protocol (MCP) can empower LLM agents with potentially hundreds of tools to solve real-world tasks. But how do we make those tools maximally effective? In this post, we describe our most effective techniques for improving performance in a variety of agentic AI systems 1.
智能体的效能取决于我们赋予它们的工具。我们分享如何编写高质量的工具和评估，以及如何通过让 Claude 自行优化工具来提升性能。
Agents are only as effective as the tools we give them. We share how to write high-quality tools and evaluations, and how you can boost performance by using Claude to optimize its tools for itself.
模型上下文协议（MCP）可以为 LLM 智能体提供数百种工具，以解决现实世界的任务。但如何使这些工具发挥最大效用？
The Model Context Protocol (MCP) can empower LLM agents with potentially hundreds of tools to solve real-world tasks. But how do we make those tools maximally effective?
在本文中，我们描述了在多种智能体式 AI 系统中提升性能的最有效技术。
In this post, we describe our most effective techniques for improving performance in a variety of agentic AI systems 1.
* 构建并测试工具的原型
* Build and test prototypes of your tools
* 创建并运行针对智能体工具的全面评估
* Create and run comprehensive evaluations of your tools with agents
* 与 Claude Code 等智能体协作，自动提升工具性能
* Collaborate with agents like Claude Code to automatically increase the performance of your tools
最后，我们总结了在过程中识别出的编写高质量工具的关键原则：
We conclude with key principles for writing high-quality tools we’ve identified along the way:
* 选择实现（和不实现）合适的工具
* Choosing the right tools to implement (and not to implement)
* 对工具进行命名空间划分，以定义清晰的功能边界
* Namespacing tools to define clear boundaries in functionality
* 从工具向智能体返回有意义的上下文
* Returning meaningful context from tools back to agents
* 优化工具响应以提升词元效率
* Optimizing tool responses for token efficiency
* 对工具描述和规格进行提示工程优化
* Prompt-engineering tool descriptions and specs
构建评估可以让你系统地衡量工具的性能。你可以使用 Claude Code 根据此评估自动优化你的工具。
Building an evaluation allows you to systematically measure the performance of your tools. You can use Claude Code to automatically optimize your tools against this evaluation.
在计算中，确定性系统在给定相同输入时每次都会产生相同的输出，而像智能体这样的非确定性系统即使在相同的起始条件下也可能生成不同的响应。
In computing, deterministic systems produce the same output every time given identical inputs, while non-deterministic systems—like agents—can generate varied responses even with the same starting conditions.
当我们传统地编写软件时，我们是在确定性系统之间建立一种契约。例如，像 getWeather(“NYC”) 这样的函数调用每次都会以完全相同的方式获取纽约市的天气。
When we traditionally write software, we’re establishing a contract between deterministic systems. For instance, a function call like getWeather(“NYC”) will always fetch the weather in New York City in the exact same manner every time it is called.
工具是一种新型软件，它反映了确定性系统与非确定性智能体之间的契约。当用户问“我今天应该带伞吗？”时，智能体可能会调用天气工具、根据常识回答，甚至先询问一个关于位置的澄清问题。有时，智能体可能会产生幻觉，甚至无法理解如何使用工具。
Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents. When a user asks "Should I bring an umbrella today?,” an agent might call the weather tool, answer from general knowledge, or even ask a clarifying question about location first. Occasionally, an agent might hallucinate or even fail to grasp how to use a tool.
这意味着在编写面向智能体的软件时需要从根本上重新思考：我们不再像为其他开发者或系统编写函数和 API 那样编写工具和 MCP 服务器，而是需要为智能体设计它们。
This means fundamentally rethinking our approach when writing software for agents: instead of writing tools and MCP servers the way we’d write functions and APIs for other developers or systems, we need to design them for agents.
我们的目标是增加智能体能够通过使用工具追求各种成功策略从而有效解决广泛任务的范围。幸运的是，根据我们的经验，那些对智能体最“符合人体工程学”的工具最终对人类来说也出奇地直观易懂。
Our goal is to increase the surface area over which agents can be effective in solving a wide range of tasks by using tools to pursue a variety of successful strategies. Fortunately, in our experience, the tools that are most “ergonomic” for agents also end up being surprisingly intuitive to grasp as humans.
在本节中，我们将描述如何与智能体协作，编写并改进您提供给它们的工具。首先，快速搭建工具原型并在本地测试。接着，运行全面评估以衡量后续变更。与智能体并肩工作，您可以重复评估和改进工具的过程，直到智能体在真实任务上表现出色。
In this section, we describe how you can collaborate with agents both to write and to improve the tools you give them. Start by standing up a quick prototype of your tools and testing them locally. Next, run a comprehensive evaluation to measure subsequent changes. Working alongside agents, you can repeat the process of evaluating and improving your tools until your agents achieve strong performance on real-world tasks.
如果不亲自动手，很难预测哪些工具对智能体来说符合人体工程学，哪些则不然。首先快速搭建一个工具原型。如果你使用 Claude Code 来编写工具（可能一次性完成），建议为 Claude 提供工具所依赖的任何软件库、API 或 SDK（可能包括 MCP SDK）的文档。LLM 友好的文档通常可以在官方文档网站的 llms.txt 文件中找到（这里是我们 API 的文档）。
It can be difficult to anticipate which tools agents will find ergonomic and which tools they won’t without getting hands-on yourself. Start by standing up a quick prototype of your tools. If you’re using Claude Code to write your tools (potentially in one-shot), it helps to give Claude documentation for any software libraries, APIs, or SDKs (including potentially the MCP SDK) your tools will rely on. LLM-friendly documentation can commonly be found in flat llms.txt files on official documentation sites (here’s our API’s).
将你的工具封装在本地 MCP 服务器或桌面扩展（DXT）中，将允许你在 Claude Code 或 Claude Desktop 应用中连接并测试你的工具。
Wrapping your tools in a local MCP server or Desktop extension (DXT) will allow you to connect and test your tools in Claude Code or the Claude Desktop app.
要将本地 MCP 服务器连接到 Claude Code，请运行 claude mcp add <name> <command> [args...]。
To connect your local MCP server to Claude Code, run claude mcp add <name> <command> [args...].
要将本地 MCP 服务器或 DXT 连接到 Claude Desktop 应用，请分别导航到“设置”>“开发者”或“设置”>“扩展”。
To connect your local MCP server or DXT to the Claude Desktop app, navigate to Settings > Developer or Settings > Extensions, respectively.
工具也可以直接传入 Anthropic API 调用中进行程序化测试。
Tools can also be passed directly into Anthropic API calls for programmatic testing.
亲自测试工具以发现任何粗糙之处。收集用户反馈，以建立对工具预期支持的用例和提示的直觉。
Test the tools yourself to identify any rough edges. Collect feedback from your users to build an intuition around the use-cases and prompts you expect your tools to enable.
接下来，你需要通过运行评估来衡量 Claude 使用工具的效果。首先，基于真实世界用例生成大量评估任务。我们建议与智能体协作，帮助你分析结果并确定如何改进工具。请参阅我们的工具评估指南，了解端到端的流程。
Next, you need to measure how well Claude uses your tools by running an evaluation. Start by generating lots of evaluation tasks, grounded in real world uses. We recommend collaborating with an agent to help analyze your results and determine how to improve your tools. See this process end-to-end in our tool evaluation cookbook.
我们内部 Slack 工具的留出测试集性能
Held-out test set performance of our internal Slack tools
借助早期原型，Claude Code 可以快速探索你的工具，并创建数十个提示和响应配对。提示应源于真实世界用例，并基于真实数据源和服务（例如内部知识库和微服务）。我们建议避免过于简单或肤浅的“沙盒”环境，这些环境无法以足够的复杂性对工具进行压力测试。强大的评估任务可能需要多次工具调用——可能多达数十次。
With your early prototype, Claude Code can quickly explore your tools and create dozens of prompt and response pairs. Prompts should be inspired by real-world uses and be based on realistic data sources and services (for example, internal knowledge bases and microservices). We recommend you avoid overly simplistic or superficial “sandbox” environments that don’t stress-test your tools with sufficient complexity. Strong evaluation tasks might require multiple tool calls—potentially dozens.
* 下周与 Jane 安排一次会议，讨论我们最新的 Acme Corp 项目。附上我们上次项目规划会议的笔记，并预订一间会议室。
* Schedule a meeting with Jane next week to discuss our latest Acme Corp project. Attach the notes from our last project planning meeting and reserve a conference room.
* 客户 ID 9182 报告称，他们在一次购买尝试中被收取了三次费用。查找所有相关日志条目，并确定是否有其他客户受到同一问题的影响。
* Customer ID 9182 reported that they were charged three times for a single purchase attempt. Find all relevant log entries and determine if any other customers were affected by the same issue.
* 客户 Sarah Chen 刚刚提交了取消请求。准备一份挽留方案。确定：(1)他们离开的原因，(2)最具吸引力的挽留方案，以及(3)在提出方案前我们应注意的风险因素。
* Customer Sarah Chen just submitted a cancellation request. Prepare a retention offer. Determine: (1) why they're leaving, (2) what retention offer would be most compelling, and (3) any risk factors we should be aware of before making an offer.
* 下周与 jane@acme.corp 安排一次会议。
* Schedule a meeting with jane@acme.corp next week.
* 在支付日志中搜索 purchase_complete 和 customer_id=9182。
* Search the payment logs for purchase_complete and customer_id=9182.
* 查找客户 ID 45892 的取消请求。
* Find the cancellation request by Customer ID 45892.
每个评估提示都应配对一个可验证的响应或结果。你的验证器可以简单到对真实答案和采样响应进行精确字符串比较，也可以高级到让 Claude 来评判响应。避免过于严格的验证器，这些验证器会因格式、标点或有效替代措辞等无关差异而拒绝正确的响应。
Each evaluation prompt should be paired with a verifiable response or outcome. Your verifier can be as simple as an exact string comparison between ground truth and sampled responses, or as advanced as enlisting Claude to judge the response. Avoid overly strict verifiers that reject correct responses due to spurious differences like formatting, punctuation, or valid alternative phrasings.
对于每个提示-响应配对，你还可以选择指定你期望智能体在解决任务时调用的工具，以衡量智能体在评估过程中是否成功掌握每个工具的用途。然而，由于可能存在多种正确解决问题的路径，尽量避免过度指定或过度拟合策略。
For each prompt-response pair, you can optionally also specify the tools you expect an agent to call in solving the task, to measure whether or not agents are successful in grasping each tool’s purpose during evaluation. However, because there might be multiple valid paths to solving tasks correctly, try to avoid overspecifying or overfitting to strategies.
我们建议通过直接调用 LLM API 以编程方式运行评估。使用简单的智能体循环（while 循环，交替进行 LLM API 调用和工具调用）：每个评估任务一个循环。每个评估智能体应获得一个单一任务提示和你的工具。
We recommend running your evaluation programmatically with direct LLM API calls. Use simple agentic loops (while-loops wrapping alternating LLM API and tool calls): one loop for each evaluation task. Each evaluation agent should be given a single task prompt and your tools.
在评估智能体的系统提示中，我们建议指示智能体不仅输出结构化响应块（用于验证），还要输出推理和反馈块。指示智能体在工具调用和响应块之前输出这些内容，可能通过触发思维链行为来提高 LLM 的有效智能。
In your evaluation agents’ system prompts, we recommend instructing agents to output not just structured response blocks (for verification), but also reasoning and feedback blocks. Instructing agents to output these before tool call and response blocks may increase LLMs’ effective intelligence by triggering chain-of-thought (CoT) behaviors.
如果你使用 Claude 运行评估，可以启用交错思考以获得类似的“开箱即用”功能。这将帮助你探究智能体为何调用或不调用某些工具，并突出工具描述和规范中需要改进的具体领域。
If you’re running your evaluation with Claude, you can turn on interleaved thinking for similar functionality “off-the-shelf”. This will help you probe why agents do or don’t call certain tools and highlight specific areas of improvement in tool descriptions and specs.
除了顶层准确率，我们建议收集其他指标，如单个工具调用和任务的总运行时间、工具调用总数、总令牌消耗以及工具错误。跟踪工具调用有助于揭示智能体通常遵循的工作流程，并为工具整合提供机会。
As well as top-level accuracy, we recommend collecting other metrics like the total runtime of individual tool calls and tasks, the total number of tool calls, the total token consumption, and tool errors. Tracking tool calls can help reveal common workflows that agents pursue and offer some opportunities for tools to consolidate.
我们内部 Asana 工具的留出测试集性能
Held-out test set performance of our internal Asana tools
智能体是你发现问题的得力助手，它们能对从矛盾的工具描述到低效的工具实现和令人困惑的工具模式等一切提供反馈。然而，请记住，智能体在反馈和响应中遗漏的内容往往比包含的内容更重要。LLM 并不总是言如其意。
Agents are your helpful partners in spotting issues and providing feedback on everything from contradictory tool descriptions to inefficient tool implementations and confusing tool schemas. However, keep in mind that what agents omit in their feedback and responses can often be more important than what they include. LLMs don’t always say what they mean.
观察你的智能体在何处陷入困境或困惑。阅读评估智能体的推理和反馈（或思维链），以识别粗糙之处。审查原始记录（包括工具调用和工具响应），以捕捉智能体思维链中未明确描述的任何行为。读懂言外之意；记住，你的评估智能体不一定知道正确答案和策略。
Observe where your agents get stumped or confused. Read through your evaluation agents’ reasoning and feedback (or CoT) to identify rough edges. Review the raw transcripts (including tool calls and tool responses) to catch any behavior not explicitly described in the agent’s CoT. Read between the lines; remember that your evaluation agents don’t necessarily know the correct answers and strategies.
分析你的工具调用指标。大量冗余的工具调用可能表明需要调整分页或令牌限制参数；大量因无效参数导致的工具错误可能表明工具需要更清晰的描述或更好的示例。当我们推出 Claude 的网页搜索工具时，我们发现 Claude 不必要地在工具的查询参数后附加了 2025，这偏向了搜索结果并降低了性能（我们通过改进工具描述将 Claude 引导到了正确的方向）。
Analyze your tool calling metrics. Lots of redundant tool calls might suggest some rightsizing of pagination or token limit parameters is warranted; lots of tool errors for invalid parameters might suggest tools could use clearer descriptions or better examples. When we launched Claude’s web search tool, we identified that Claude was needlessly appending 2025 to the tool’s query parameter, biasing search results and degrading performance (we steered Claude in the right direction by improving the tool description).
你甚至可以让智能体分析你的结果并为你改进工具。只需将评估智能体的对话记录拼接起来，粘贴到 Claude Code 中。Claude 擅长分析对话记录并一次性重构大量工具——例如，确保在做出新更改时，工具实现和描述保持自洽。
You can even let agents analyze your results and improve your tools for you. Simply concatenate the transcripts from your evaluation agents and paste them into Claude Code. Claude is an expert at analyzing transcripts and refactoring lots of tools all at once—for example, to ensure tool implementations and descriptions remain self-consistent when new changes are made.
事实上，本文中的大部分建议都来自使用 Claude Code 反复优化我们内部工具实现的过程。我们的评估建立在内部工作空间之上，反映了内部工作流程的复杂性，包括真实项目、文档和消息。
In fact, most of the advice in this post came from repeatedly optimizing our internal tool implementations with Claude Code. Our evaluations were created on top of our internal workspace, mirroring the complexity of our internal workflows, including real projects, documents, and messages.
我们依赖留出的测试集来确保不会过拟合到“训练”评估。这些测试集表明，即使超越“专家”工具实现——无论这些工具是由我们的研究人员手动编写还是由 Claude 自身生成——我们仍能提取额外的性能改进。
We relied on held-out test sets to ensure we did not overfit to our “training” evaluations. These test sets revealed that we could extract additional performance improvements even beyond what we achieved with "expert" tool implementations—whether those tools were manually written by our researchers or generated by Claude itself.
在下一节中，我们将分享从这一过程中学到的一些经验。
In the next section, we’ll share some of what we learned from this process.
在本节中，我们将所学提炼为编写有效工具的几条指导原则。
In this section, we distill our learnings into a few guiding principles for writing effective tools.
更多工具并不总能带来更好的结果。我们观察到的一个常见错误是，工具仅仅封装了现有软件功能或 API 端点——无论这些工具是否适合智能体。这是因为智能体与传统软件具有不同的“可供性”——即，它们以不同的方式感知使用这些工具可能采取的行动。
More tools don’t always lead to better outcomes. A common error we’ve observed is tools that merely wrap existing software functionality or API endpoints—whether or not the tools are appropriate for agents. This is because agents have distinct “affordances” to traditional software—that is, they have different ways of perceiving the potential actions they can take with those tools
LLM 智能体的“上下文”有限（即，它们一次能处理的信息量有限），而计算机内存既便宜又充足。考虑在通讯录中搜索联系人的任务。传统软件程序可以高效地逐个存储和处理联系人列表，检查每个联系人后再继续。
LLM agents have limited "context" (that is, there are limits to how much information they can process at once), whereas computer memory is cheap and abundant. Consider the task of searching for a contact in an address book. Traditional software programs can efficiently store and process a list of contacts one at a time, checking each one before moving on.
然而，如果 LLM 智能体使用一个返回所有联系人的工具，然后必须逐个词元地读取每个联系人，它就在不相关的信息上浪费了有限的上下文空间（想象一下通过从上到下逐页阅读来搜索通讯录中的联系人——即通过暴力搜索）。更好且更自然的方法（对智能体和人类都一样）是首先跳到相关页面（也许按字母顺序找到它）。
However, if an LLM agent uses a tool that returns ALL contacts and then has to read through each one token-by-token, it's wasting its limited context space on irrelevant information (imagine searching for a contact in your address book by reading each page from top-to-bottom—that is, via brute-force search). The better and more natural approach (for agents and humans alike) is to skip to the relevant page first (perhaps finding it alphabetically).
我们建议构建几个针对特定高影响力工作流的深思熟虑的工具，这些工具与你的评估任务相匹配，并从此处开始扩展。在通讯录案例中，你可能选择实现一个 search_contacts 或 message_contact 工具，而不是 list_contacts 工具。
We recommend building a few thoughtful tools targeting specific high-impact workflows, which match your evaluation tasks and scaling up from there. In the address book case, you might choose to implement a search_contacts or message_contact tool instead of a list_contacts tool.
工具可以整合功能，在底层处理可能多个离散操作（或 API 调用）。例如，工具可以用相关元数据丰富工具响应，或在单个工具调用中处理频繁链式的多步骤任务。
Tools can consolidate functionality, handling potentially multiple discrete operations (or API calls) under the hood. For example, tools can enrich tool responses with related metadata or handle frequently chained, multi-step tasks in a single tool call.
* 与其实现 list_users、list_events 和 create_event 工具，不如考虑实现一个 schedule_event 工具，它可以查找可用性并安排事件。 * 与其实现 read_logs 工具，不如考虑实现一个 search_logs 工具，它只返回相关的日志行和一些周围上下文。 * 与其实现 get_customer_by_id、list_transactions 和 list_notes 工具，不如实现一个 get_customer_context 工具，它一次性编译所有客户最近和相关的信息。
* Instead of implementing a list_users, list_events, and create_event tools, consider implementing a schedule_event tool which finds availability and schedules an event.
确保你构建的每个工具都有清晰、独特的目的。工具应使智能体能够像人类一样细分和解决问题，前提是拥有相同的基础资源，同时减少原本会被中间输出消耗的上下文。
* Instead of implementing a read_logs tool, consider implementing a search_logs tool which only returns relevant log lines and some surrounding context.
太多工具或重叠的工具也会分散智能体追求高效策略的注意力。仔细、有选择地规划你构建（或不构建）的工具可以带来显著回报。
* Instead of implementing get_customer_by_id, list_transactions, and list_notes tools, implement a get_customer_context tool which compiles all of a customer’s recent & relevant information all at once.
Make sure each tool you build has a clear, distinct purpose. Tools should enable agents to subdivide and solve tasks in much the same way that a human would, given access to the same underlying resources, and simultaneously reduce the context that would have otherwise been consumed by intermediate outputs.
Too many tools or overlapping tools can also distract agents from pursuing efficient strategies. Careful, selective planning of the tools you build (or don’t build) can really pay off.
你的 AI 智能体可能会访问数十个 MCP 服务器和数百个不同工具——包括其他开发者开发的工具。当工具功能重叠或用途模糊时，智能体会对使用哪个工具感到困惑。
Your AI agents will potentially gain access to dozens of MCP servers and hundreds of different tools–including those by other developers. When tools overlap in function or have a vague purpose, agents can get confused about which ones to use.
命名空间（将相关工具分组在共同前缀下）有助于划分大量工具之间的边界；MCP 客户端有时会默认这样做。例如，按服务（如 asana_search, jira_search）和按资源（如 asana_projects_search, asana_users_search）对工具进行命名空间划分，可以帮助智能体在正确的时间选择正确的工具。
Namespacing (grouping related tools under common prefixes) can help delineate boundaries between lots of tools; MCP clients sometimes do this by default. For example, namespacing tools by service (e.g., asana_search, jira_search) and by resource (e.g., asana_projects_search, asana_users_search), can help agents select the right tools at the right time.
我们发现选择基于前缀和后缀的命名空间对工具使用评估有显著影响。效果因 LLM 而异，我们鼓励你根据自己的评估选择命名方案。
We have found selecting between prefix- and suffix-based namespacing to have non-trivial effects on our tool-use evaluations. Effects vary by LLM and we encourage you to choose a naming scheme according to your own evaluations.
智能体可能调用错误的工具、用错误参数调用正确工具、调用工具过少或错误处理工具响应。通过有选择地实现名称反映任务自然细分的工具，你同时减少了加载到智能体上下文中的工具和工具描述的数量，并将智能体式计算从智能体上下文卸载回工具调用本身。这降低了智能体整体出错的风险。
Agents might call the wrong tools, call the right tools with the wrong parameters, call too few tools, or process tool responses incorrectly. By selectively implementing tools whose names reflect natural subdivisions of tasks, you simultaneously reduce the number of tools and tool descriptions loaded into the agent’s context and offload agentic computation from the agent’s context back into the tool calls themselves. This reduces an agent’s overall risk of making mistakes.
同样，工具实现应注意只向智能体返回高信号信息。它们应优先考虑上下文相关性而非灵活性，并避免使用低级技术标识符（例如：uuid、256px_image_url、mime_type）。像 name、image_url 和 file_type 这样的字段更有可能直接指导智能体的后续行动和响应。
In the same vein, tool implementations should take care to return only high signal information back to agents. They should prioritize contextual relevance over flexibility, and eschew low-level technical identifiers (for example: uuid, 256px_image_url, mime_type). Fields like name, image_url, and file_type are much more likely to directly inform agents’ downstream actions and responses.
智能体在处理自然语言名称、术语或标识符时，通常比处理晦涩的标识符要成功得多。我们发现，仅仅将随机的字母数字 UUID 解析为更具语义意义和可解释性的语言（甚至是基于 0 的索引 ID 方案），就能显著提高 Claude 在检索任务中的精确度，减少幻觉。
Agents also tend to grapple with natural language names, terms, or identifiers significantly more successfully than they do with cryptic identifiers. We’ve found that merely resolving arbitrary alphanumeric UUIDs to more semantically meaningful and interpretable language (or even a 0-indexed ID scheme) significantly improves Claude’s precision in retrieval tasks by reducing hallucinations.
在某些情况下，智能体可能需要灵活地与自然语言和技术标识符输出交互，即使只是为了触发下游工具调用（例如，search_user(name='jane') → send_message(id=12345)）。你可以通过在工具中暴露一个简单的 response_format 枚举参数来同时支持两者，从而允许你的智能体控制工具返回“简洁”或“详细”的响应（如下图所示）。
In some instances, agents may require the flexibility to interact with both natural language and technical identifiers outputs, if only to trigger downstream tool calls (for example, search_user(name=’jane’) → send_message(id=12345)). You can enable both by exposing a simple response_format enum parameter in your tool, allowing your agent to control whether tools return “concise” or “detailed” responses (images below).
你可以添加更多格式以获得更大的灵活性，类似于 GraphQL，你可以精确选择想要接收的信息片段。以下是一个 ResponseFormat 枚举示例，用于控制工具响应的详细程度：
You can add more formats for even greater flexibility, similar to GraphQL where you can choose exactly which pieces of information you want to receive. Here is an example ResponseFormat enum to control tool response verbosity:
以下是一个详细工具响应示例（206 个 token）：
Here’s an example of a detailed tool response (206 tokens):
以下是一个简洁工具响应示例（72 个 token）：
Here’s an example of a concise tool response (72 tokens):
Slack 线程和线程回复由唯一的 thread_ts 标识，获取线程回复需要该标识。thread_ts 和其他 ID（channel_id、user_id）可以从“详细”工具响应中检索，以支持需要这些 ID 的进一步工具调用。“简洁”工具响应仅返回线程内容并排除 ID。在此示例中，使用“简洁”工具响应时，我们使用了约 1/3 的 token。
Slack threads and thread replies are identified by unique thread_ts which are required to fetch thread replies. thread_ts and other IDs (channel_id, user_id) can be retrieved from a “detailed” tool response to enable further tool calls that require these. “concise” tool responses return only thread content and exclude IDs. In this example, we use ~⅓ of the tokens with “concise” tool responses.
甚至你的工具响应结构——例如 XML、JSON 或 Markdown——也会对评估性能产生影响：没有一刀切的解决方案。这是因为 LLM 是在下一个词预测任务上训练的，并且往往在与训练数据匹配的格式上表现更好。最佳响应结构会因任务和智能体而异。我们鼓励你根据自己的评估选择最佳的响应结构。
Even your tool response structure—for example XML, JSON, or Markdown—can have an impact on evaluation performance: there is no one-size-fits-all solution. This is because LLMs are trained on next-token prediction and tend to perform better with formats that match their training data. The optimal response structure will vary widely by task and agent. We encourage you to select the best response structure based on your own evaluation.
优化上下文的质量很重要，但优化工具响应返回给智能体的上下文_数量_同样重要。
Optimizing the quality of context is important. But so is optimizing the quantity of context returned back to agents in tool responses.
我们建议对任何可能消耗大量上下文的工具响应，采用分页、范围选择、过滤和/或截断的组合，并设置合理的默认参数值。对于 Claude Code，我们默认将工具响应限制为 25,000 个词元。我们预计智能体的有效上下文长度会随时间增长，但对上下文高效工具的需求将保持不变。
We suggest implementing some combination of pagination, range selection, filtering, and/or truncation with sensible default parameter values for any tool responses that could use up lots of context. For Claude Code, we restrict tool responses to 25,000 tokens by default. We expect the effective context length of agents to grow over time, but the need for context-efficient tools to remain.
如果选择截断响应，请务必用有用的指令引导智能体。你可以直接鼓励智能体采用更节省词元的策略，例如在知识检索任务中进行多次小范围、有针对性的搜索，而不是一次宽泛的搜索。类似地，如果工具调用引发错误（例如在输入验证期间），你可以通过提示工程使错误响应清晰地传达具体且可操作的改进建议，而不是晦涩的错误代码或回溯信息。
If you choose to truncate responses, be sure to steer agents with helpful instructions. You can directly encourage agents to pursue more token-efficient strategies, like making many small and targeted searches instead of a single, broad search for a knowledge retrieval task. Similarly, if a tool call raises an error (for example, during input validation), you can prompt-engineer your error responses to clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks.
以下是一个截断工具响应的示例：
Here’s an example of a truncated tool response:
以下是一个无帮助的错误响应示例：
Here’s an example of an unhelpful error response:
以下是一个有帮助的错误响应示例：
Here’s an example of a helpful error response:
工具截断和错误响应可以引导智能体采用更节省词元的工具使用行为（使用过滤器或分页），或提供正确格式化的工具输入示例。
Tool truncation and error responses can steer agents towards more token-efficient tool-use behaviors (using filters or pagination) or give examples of correctly formatted tool inputs.
现在我们讨论改进工具最有效的方法之一：通过提示工程优化工具描述和规格说明。由于这些内容会被加载到智能体的上下文中，它们可以共同引导智能体采取有效的工具调用行为。
We now come to one of the most effective methods for improving tools: prompt-engineering your tool descriptions and specs. Because these are loaded into your agents’ context, they can collectively steer agents toward effective tool-calling behaviors.
在编写工具描述和规格说明时，请思考你会如何向团队新成员描述你的工具。考虑你可能隐含带入的上下文——专门的查询格式、专业术语的定义、底层资源之间的关系——并将其明确化。通过清晰描述（并使用严格的数据模型强制执行）预期的输入和输出来避免歧义。特别是，输入参数应明确命名：不要使用名为 user 的参数，而应尝试使用名为 user_id 的参数。
When writing tool descriptions and specs, think of how you would describe your tool to a new hire on your team. Consider the context that you might implicitly bring—specialized query formats, definitions of niche terminology, relationships between underlying resources—and make it explicit. Avoid ambiguity by clearly describing (and enforcing with strict data models) expected inputs and outputs. In particular, input parameters should be unambiguously named: instead of a parameter named user, try a parameter named user_id.
通过评估，你可以更有信心地衡量提示工程的影响。即使是对工具描述的小幅改进也能带来显著的提升。Claude Sonnet 3.5 在对工具描述进行精确改进后，在 SWE-bench Verified 评估中取得了最先进的性能，大幅降低了错误率并提高了任务完成度。
With your evaluation you can measure the impact of your prompt engineering with greater confidence. Even small refinements to tool descriptions can yield dramatic improvements. Claude Sonnet 3.5 achieved state-of-the-art performance on theSWE-bench Verified evaluation after we made precise refinements to tool descriptions, dramatically reducing error rates and improving task completion.
你可以在我们的开发者指南中找到其他关于工具定义的最佳实践。如果你正在为 Claude 构建工具，我们还建议阅读关于工具如何动态加载到 Claude 系统提示中的内容。最后，如果你正在为 MCP 服务器编写工具，工具注释有助于披露哪些工具需要开放世界访问或进行破坏性更改。
You can find other best practices for tool definitions in our Developer Guide. If you’re building tools for Claude, we also recommend reading about how tools are dynamically loaded into Claude’s system prompt. Lastly, if you’re writing tools for an MCP server, tool annotations help disclose which tools require open-world access or make destructive changes.
为了构建有效的智能体工具，我们需要将软件开发实践从可预测的确定性模式转向非确定性模式。
To build effective tools for agents, we need to re-orient our software development practices from predictable, deterministic patterns to non-deterministic ones.
通过本文所述迭代的、评估驱动的方法，我们识别出了工具成功的持续模式：有效的工具有意且清晰定义，明智地使用智能体上下文，可在多样化工作流中组合，并使智能体能够直观地解决现实世界任务。
Through the iterative, evaluation-driven process we’ve described in this post, we've identified consistent patterns in what makes tools successful: Effective tools are intentionally and clearly defined, use agent context judiciously, can be combined together in diverse workflows, and enable agents to intuitively solve real-world tasks.
未来，我们预计智能体与世界交互的具体机制将不断演进——从 MCP 协议的更新到底层 LLM 本身的升级。通过系统化、评估驱动的方法来改进智能体工具，我们可以确保随着智能体能力的增强，它们所使用的工具也将随之演进。
In the future, we expect the specific mechanisms through which agents interact with the world to evolve—from updates to the MCP protocol to upgrades to the underlying LLMs themselves. With a systematic, evaluation-driven approach to improving tools for agents, we can ensure that as agents become more capable, the tools they use will evolve alongside them.