Anthropic releases official tutorial on "Writing Tools for Intelligent Agents"

Anthropicintelligentbody"Writing Tools" mainly explores how to...intelligentbodyDevelop effective tools. The article points out that tools connect deterministic systems (such as APIs) and non-deterministic systems.AIA bridge for proxies. A detailed introduction to the three key steps in developing tools: prototyping, runtime evaluation, and...intelligentbodyCollaborative optimization tools. This article summarizes several important principles for writing effective tools, adhering to five key principles: accuracy, namespaces, rich context, token efficiency, and clear description. By following these methods, tool performance can be improved.intelligentbodyMore capable of solving real-world tasksHigh efficiency.

"forintelligentbodyThe core content of "Writing Tools"

intelligentbodyIts effectiveness depends entirely on the tools we provide. We will share how to write high-quality tools and evaluation methods, and how to use them...ClaudeSelf-optimization tools improve performance.

ModelContext Protocol (MCP)Able toLLMintelligentbodyEquipped with hundreds of tools to solve real-world tasks. How can you maximize the effectiveness of these tools?

This article will introduce various typesintelligentAIThe most effective technique to improve system performance.

First, it covers how:

Prototype of building and testing tools
Create and runintelligentbodyComprehensive evaluation of the tools
andClaude Code, etc.intelligentbodycooperation,automaticImprove tool performance
Finally, we summarize the key principles for writing high-quality tools discovered during this process:

Choose the right tools for implementation (and the tools that should not be implemented):

Define clear functional boundaries through namespaces.
Return meaningful context from the tool.intelligentbody
Optimize tool response to improve token efficiency
Provide descriptions and specifications of the engineering optimization tools.

What are tools?

In the field of computation, deterministic systems produce the same output every time given the same input, while nondeterministic systems, such as...intelligentbodyDifferent responses can be produced even under the same initial conditions.

When we traditionally write software, we are establishing contracts between deterministic systems. For example, a function call like getWeather(“NYC”) retrieves the weather information for New York City in exactly the same way every time it is called.

The tool is a new type of software that reflects the differences between deterministic and nondeterministic systems.intelligentbodyThe contract between them. When a user asks, "Should I bring an umbrella today?",intelligentbodyThey will use weather tools, answer questions based on general knowledge, and even ask clarifying questions about the location first.intelligentbodyHallucinations may occur, and the user may be unable to control how to use the tools.

In order tointelligentbodyWhen writing software, we need to fundamentally rethink our approach: we need to...intelligentbodyDesign tools andMCP serverThey are not written like functions and APIs for other developers or systems.

Our goal is to pursue various successful strategies by using tools to increase...intelligentbodyIt can effectively solve a wide range of tasks.

How to write tools

In this section, we will provide how to...intelligentbodyCollaboratively develop and improve the tools provided to them. FirstfastBuild a tool prototype and test it locally. Run a comprehensive evaluation to measure subsequent changes.intelligentbodyCollaborative work allows for repeated evaluation and improvement of tools until...intelligentbodyAchieve robust performance in real-world tasks.

Building a prototype

It's hard to predict without experiencing it firsthand.intelligentbodyWhich tools do you think are ergonomic, and which are not?fastBuild a tool prototype. If using...Claude The code writing tool (which may be completed in one go) should ideally include any software libraries, APIs, or SDKs that the tool depends on (including...).MCP SDKDocumentation is provided. Suitable documentation can be found on the official documentation website.LLMThe flattened llms.txt file (this is ours)API documentation).

Pack the tools inLocal MCP serverorDesktop extensionIn (DXT), it will be possible toClaude Code orClaudeConnection and testing tools in desktop applications.

To connect the local MCP serverClaude For code, please run `claude mcp add <name> <command> [parameters...]`.

To connect a local MCP server or DXT to the Claude desktop application, navigate to Settings > Developers or Settings > Extensions, respectively.

The tool can be directly passed inAnthropic APIPerform programmatic testing during the call.

Test the tool yourself to identify its shortcomings. Gather user feedback to build an intuitive understanding of the use cases and prompts that you expect the tool to support.

Operational assessment

Next, it is necessary to measure through operational evaluation.ClaudeThe effectiveness of using the tool. A large number of evaluation tasks are generated based on real-world use cases. Recommendations and...intelligentbodyCollaboration helps analyze results and determine how to improve the tool. Please visit our...Tool Evaluation GuideView this end-to-end process in [the context].

1. Generate evaluation tasks

Use an early prototype.Claude Code canfastExplore the tools and create dozens of hint and response pairs. Hints should be inspired by real-world use cases and based on real data sources and services (e.g., internal knowledge bases and microservices). We recommend avoiding overly...SimpleOr a superficial "sandbox" environment, which cannot stress test the tool with sufficient complexity.powerfulThe evaluation task requires multiple tool calls—potentially dozens of times.

Here are somepowerfulExample of a task:

I've arranged a meeting with Jane next week to discuss our...up to dateThe Acme Corp project. Attached are the minutes of our last project planning meeting and the booked meeting room.
Customer ID 9182 reported being charged three times during a single purchase attempt. Locate all relevant log entries and determine if other customers are affected by the same issue.
Customer Sarah Chen has just submitted a cancellation request. We are preparing to retain the offer. We need to determine: (1) the reasons for their departure, (2) which retention offer is most attractive, and (3) any risk factors we should be aware of before offering the offer.

Here are some examples of weaker tasks:

Schedule a meeting next week with jane@acme.corp.
Search for purchase_complete and customer_id=9182 in the payment logs.
Find the cancellation request for customer ID 45892.

Each evaluation prompt should be accompanied by a verifiable response or result. The verifier can...SimpleFrom performing precise string comparisons between the actual answers and sampled responses, or even more complex tasks...ClaudeJudge the response. Avoid using overly strict validators, which may reject correct responses due to spurious differences such as formatting, punctuation, or valid alternative expressions.

For each prompt-response pair, select the desired outcome.intelligentbodyThe tools used when solving a task, and the measurementintelligentbodyDuring the evaluation, assess whether the purpose of each tool has been successfully understood. Since there may be multiple valid paths to correctly solve the task, try to avoid over-specifying or overfitting strategies.

2. Operational Assessment

We recommend going through a direct approach.LLM API calls are used to run the evaluation programmatically.SimpleofintelligentbodyCirculation (alternating packaging)LLM (while loop for API and tool calls): one loop per evaluation task. Each evaluation...intelligentbodyThey are given individual task prompts and tools.

In assessmentintelligentbodyThe system prompt suggests/instructsintelligentbodyOutput a structured response block (for verification), as well as inference and feedback blocks. InstructionsintelligentbodyOutputting this content before tool calls and response blocks improves performance by triggering thought chain (CoT) behavior.LLMeffectiveintelligent.

If usingClaudeOperational assessment, enabledInterlaced thinkingTo obtain similar "out-of-the-box" functionality will help in the exploration.intelligentbodyExplain why certain tools should be used or not, highlighting specific areas for improvement in the tool descriptions and specifications.

In addition to top-level accuracy, it is recommended to collect other metrics such as total runtime for individual tool calls and tasks, total number of tool calls, total token consumption, and tool errors. Tracking tool calls can help reveal...intelligentbodyThe pursuit of common workflows provides opportunities for tool integration.

3. Analysis Results

intelligentbodyIt is a useful partner for identifying problems and providing feedback, covering everything from conflicting tool descriptions to inefficient tool implementations and confusing tool patterns.intelligentbodyThe content omitted in feedback and response is often more important than the content included.LLMThey don't always accurately express their true meaning.

observeintelligentbodyWhere are you stuck or confused? Read through the assessment.intelligentbodyThe reasoning and feedback (or thought chain) are used to identify shortcomings. Reviewing the original records (including tool calls and tool responses) helps capture...intelligentbodyAny behavior not explicitly described in the thought process. Understand the meaning between the lines; remember the evaluation.intelligentbodyThey may not know the correct answer or strategy.

Analyze tool call metrics. A large number of redundant tool calls may indicate a need to adjust pagination or token limit parameters; numerous tool errors with invalid parameters may suggest the tool requires clearer descriptions or better examples. When we launch...Claudeweb search toolsAt that time, we discoveredClaudeUnnecessarily appending 2025 to the tool's query parameters skews search results and reduces performance (we address this by improving the tool description).Claude(Guide them in the right direction).

4. withintelligentbodycooperation

You can even letintelligentbodyAnalyze the results and improve the tools. Simply submit the assessment.intelligentbodyConnect the records and paste them intoClaude In the code.ClaudeThey are experts in analyzing records and refactoring large numbers of tools at once—for example, ensuring that tool implementations and descriptions remain consistent when new changes are made.

In fact, most of the suggestions in this article come from using...Claude Code iteratively optimizes our internal tool implementations. Our evaluations are built upon internal workspaces that reflect the complexity of our internal workflows, including real projects, documentation, and messaging.

We rely on the retained test set to ensure we don't overfit our "training" evaluation. The test set demonstrates that we can extract additional performance improvements, even beyond the performance achieved by "expert" tools—regardless of whether the tools were written manually by our researchers or by [other entities].ClaudeSelf-generated.

In the next section, we will share some lessons learned from this process.

writeHigh efficiencyPrinciples of Tools

In this section, we will distill the knowledge we have learned into some writing...High efficiencyThe guiding principles of the tools.

forintelligentbodyChoose the appropriate tools

More tools don't always lead to better results. A common mistake we've observed is that tools simply wrap existing software functionality or API endpoints—regardless of whether the tool is suitable.intelligentbodyThis is becauseintelligentbodyThey have a different “functional visibility” than traditional software – they perceive and use tools in a completely different way than traditional software.

LLMintelligentbodyThey have limited "context" (i.e., they can process a limited amount of information at a time), and computer memory is cheap and plentiful. Take the task of searching for contacts in an address book as an example. Traditional software programs can...High efficiencyStore and process the contact list one by one, checking each contact before proceeding.

ifLLMintelligentbodyUsing a tool that returns all contacts requires reading each contact token by token, wasting limited context space on irrelevant information (imagine searching for contacts in an address book by reading every page from top to bottom—a brute-force search). A better, more natural approach (for...)intelligentbody(And humans alike) is to first jump to the relevant page (maybe find it in alphabetical order).

We recommend starting by building a small set of well-thought-out tools for high-value workflows, tailored to the assessment tasks, and then expanding from there. In the address book case, choose to implement either the `search_contacts` or `message_contact` tools, rather than...SimpleIt provides the list_contacts tool.

The tool has integration capabilities, handling multiple discrete operations (or API calls) at the underlying level. For example, the tool enriches tool responses with relevant metadata, or handles frequently linked multi-step tasks within a single tool call.

Here are some examples:

Instead of implementing list_users, list_events, and create_event tools, consider implementing a schedule_event tool that can check availability and schedule events.
Instead of implementing a read_logs tool, consider implementing a search_logs tool that only returns relevant log lines and some surrounding context.
Instead of implementing tools like get_customer_by_id, list_transactions, and list_notes, it would be better to implement a tool like get_customer_context, which can compile all recent customer-related information at once.

Ensure that every tool you build has a clear and unique purpose. Tools should make...intelligentbodyIt can break down and solve tasks in a similar way to how humans would do when they have access to the same underlying resources, while reducing the context that would otherwise be consumed by intermediate outputs.

Too many tools or tools with overlapping functions can also lead to fragmentation.intelligentbodyPursueHigh efficiencyStrategic focus. Careful and selective planning on which tools to build (or not build) can indeed pay off.

Set namespaces for tools

AIintelligentbodyThis could grant access to dozens of MCP servers and hundreds of different tools—including those provided by other developers. When tool functionality overlaps or their purpose is ambiguous,intelligentbodyYou might be confused about which tools to use.

Namespaces (grouping related tools under a common prefix) help to define boundaries between a large number of tools; MCP clients sometimes do this by default. For example, dividing namespaces by service (such as asana_search, jira_search) and by resource (such as asana_projects_search, asana_users_search) helps...intelligentbodyChoose the right tool at the right time.

We found that prefix and suffix-based namespace selection has a significant impact on our tool usage evaluation.LLMHowever, we recommend choosing a naming scheme based on your own assessment.

intelligentbodyIt may invoke the wrong tool, invoke the correct tool with incorrect parameters, invoke too few tools, or respond with error handling tools. By selectively implementing tools whose names reflect the natural breakdown of the task, it can simultaneously reduce the amount of data loaded.intelligentbodyThe number of tools and tool descriptions in the context willintelligentbodyThe computation is unloaded from the context back to the tool call itself. (This reduces...)intelligentbodyThe overall risk of making mistakes.

Similarly, tool implementations should ensure that they only direct to...intelligentbodyReturn high-value information. Contextual relevance should be prioritized over flexibility, avoiding low-level technical identifiers (e.g., UUID, 256px_image_url, MIME_type). Fields like name, image_url, and file_type are more likely to provide direct guidance.intelligentbodyDownstream actions and responses.

intelligentbodyThe success rate of processing natural language names, terms, or identifiers is significantly higher than that of processing obscure identifiers. We found that simply resolving arbitrary alphanumeric UUIDs into a more semantically meaningful and interpretable language (even a zero-indexed ID scheme) can significantly improve performance by reducing illusions.ClaudeAccuracy in retrieval tasks.

In some cases,intelligentbodyIt may be necessary to flexibly handle both natural language and technical identifier outputs, even if only to trigger downstream tool calls (e.g., search_user(name='jane') → send_message(id=12345)). You can do this by exposing a [specific identifier] in the tool.SimpleThe `response_format` enumeration parameter enables both, allowing...intelligentbodyThe control tool returns either a "concise" or "verbal" response (see image below).

You can add more formats for greater flexibility, similar to GraphQL, to select the exact pieces of information you want to receive. Below is an example of the ResponseFormat enumeration for controlling the level of detail in a tool's response:

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

Here is an example of a detailed tool response (206 tokens):

Here is an example of a concise tool response (72 tokens):

The tool's response structure—such as XML, JSON, or Markdown—also impacts performance evaluation; there is no one-size-fits-all solution. This is because...LLMIt is trained by predicting the next token and tends to perform better on formats that match its training data. The optimal response structure will vary depending on the task and...intelligentbodyThe differences can be significant. We recommend choosing the optimal response structure based on your own assessment.

Optimize the token efficiency of the tool's response

Optimizing context quality is important. However, the optimization tool's response should return...intelligentbodyThe number of contexts is equally important.

We recommend implementing some combination of pagination, range selection, filtering, and/or truncation for any tool response that may consume significant context, and setting reasonable default parameter values. ForClaude For Code, we default to limiting the tool's response to 25,000 tokens. We expect...intelligentbodyThe effective context length increases over time, but for contextHigh efficiencyThe need for tools will always exist.

If you choose to truncate the response, be sure to guide it with helpful instructions.intelligentbodyYou can directly encourageintelligentbodyPursue a more token-efficient strategy, such as performing multiple small, targeted searches, rather than a single, broad search for a knowledge retrieval task. If a tool call triggers an error (e.g., during input validation), you can communicate specific and actionable improvement suggestions clearly by prompting the engineered error response, rather than providing obscure error codes or traceback information.

Here is an example of a truncation tool response:

Here is an example of a useless error response:

Here is a useful example of an error response:

Now let's discuss one of the most effective ways to improve tools: tool description and specification hinting engineering. Because this content will be loaded into...intelligentbodyIn the context of their respective contexts, they can work together to guide...intelligentbodyTake effective tool invocation actions.

When writing tool descriptions and specifications, envision how you would describe your tool to new team members. Consider any implicitly introduced context—specific query formats, definitions of technical terms, relationships between underlying resources—and make them explicit. Avoid ambiguity by clearly describing (and enforcing this through a rigorous data model) the expected inputs and outputs. In particular, ensure that input parameter names are unambiguous: avoid using a parameter named "user" and try using one named "user_id".

Through evaluation, you can more confidently measure the impact of tooltip engineering. Even small improvements to the tool description can lead to significant gains. After we made precise improvements to the tool description,Claude Sonnet 3.5 inSWE-bench VerifiedThe evaluation achieves state-of-the-art performance, significantly reducing error rates and improving task completion rates.

In ourDeveloper GuideYou can find other best practices defined by the tool there. If you are working on...ClaudeFor build tools, we recommend reading about how tools are dynamically loaded.ClaudeSystem promptThe instructions are in the document. If you are writing tools for an MCP server,Tool NotesThis helps to disclose which tools require open-world access or disruptive changes.

Looking to the future

To build an effectiveintelligentbodyTools: We need to reposition software development practices from a predictable, deterministic model to a non-deterministic model.

Through the iterative, evaluation-driven process described in this paper, we find a consistent pattern for tool success: effective tools have clear and well-defined features and can be used appropriately.intelligentbodyContext can be combined and used in diverse workflows, enablingintelligentbodyIt can intuitively solve real-world tasks.

Looking to the future, predictionsintelligentbodyThe specific mechanisms for interacting with the world will continue to evolve—from updates to the MCP protocol to the underlying layers.LLMThe upgrade itself. Improved through a systematic, evaluation-driven approach.intelligentbodyTools that can ensure that, withintelligentbodyAs their capabilities increase, the tools they use will also evolve in tandem.

"forintelligentbodyThe official website address for "Writing Tools"

Official website addresshttps://www.anthropic.com/engineering/writing-tools-for-agents

"forintelligentbodyWho is the target audience for "Writing Tools"?

artificialintelligentEngineers and developersProvides specific methods for building, testing, and optimizing tools to help improve...intelligentbodyPerformance and efficiency.
Data scientists andMachine LearningexpertThe evaluation and optimization techniques in the article help combine models with tools to improve the overall performance of the system.
Software architectThe article's advanced guidance helps users design more...High efficiencyA flexible system architecture willintelligentbodyIntegrate tools and technologies into existing systems.
Product ManagerThe article helps users understand the key aspects of tool development, enabling them to better plan product features and evaluate technical solutions.
ResearchersThe best practices and case studies in the article provide references for users' research and help them explore new research directions.

All Categories