❗️

This tool use format is out of date

We highly recommend that you switch as soon as possible to our improved tool use structure, which is more reliable and enables higher quality performance, especially for more complex tool use tasks.

This tool use format is not optimized for Claude 3 and may result in poorer performance than our updated tool use format.

Note: The new tool use format is not yet available on Vertex AI or Amazon Bedrock, but is coming soon to those platforms.

How legacy tool use works

With legacy tool use, functions are defined within the prompt itself. When you provide Claude with descriptions of tools and functions it can use, Claude is able to intelligently decide when and how to use those tools to help answer questions and complete tasks.

For example, let's say you provide Claude (in the prompt) a function called get_weather(location) that retrieves the current weather for a given location. If a user then asks "What's the weather like in London right now?", Claude will recognize that it can use the get_weather function you provided to look up the answer.

Behind the scenes, this is a multi-step process:

1. The function definitions and user question are both passed to Claude in a single prompt
   • Claude not only needs the tools & their descriptions in order to successfully decide whether to use the tools, but likely also accompanying examples of situations in which such tools ought to be used, depending on the complexity of the use case and tools.
2. Claude assesses the user's question and decides which function(s) to call and with what arguments
3. Claude constructs a properly formatted function call
4. The function call is intercepted via client code with a clear stop_sequence, and the actual function is executed on the client side
5. The function result is passed back to Claude
6. Claude uses the function result to formulate its final response to the user

This technique allows Claude to leverage external knowledge and capabilities while still maintaining a conversational interface.

Defining functions

Functions are defined by providing Claude with a description of the function wrapped in XML tags. The description should include:

• The function name
• A plaintext explanation of what the function does
• The expected parameters, their types, and descriptions
• The return values and types
• Any exceptions that can be raised

Here is an example function definition:

<tool_description>
<tool_name>get_weather</tool_name>
<description>
Retrieves the current weather for a specified location.
Returns a dictionary with two fields:
- temperature: float, the current temperature in Fahrenheit 
- conditions: string, a brief description of the current weather conditions
Raises ValueError if the provided location cannot be found.
</description>
<parameters>
<parameter>
<name>location</name>
<type>string</type>
<description>The city and state, e.g. San Francisco, CA</description>
</parameter>
</parameters>
</tool_description>

Some tips for writing good function descriptions:

• Be clear and concise, but provide enough detail for Claude to understand when the function should be used
• Specify the types of the parameters and return values
• Mention any relevant exceptions that can be raised
• Use plaintext descriptions, not code syntax

Legacy tool use format

In order for Claude to call a function, it has to output a very specifically formatted XML block. The format looks like this:

<function_calls>
<invoke>
<tool_name>function_name</tool_name>
<parameters>
<param1>value1</param1>
<param2>value2</param2>
</parameters>
</invoke>
</function_calls>

The <function_calls> block can contain multiple <invoke> blocks if Claude is calling more than one function at the same time. Each <invoke> contains the name of the function being called and the parameters being passed in.

You should pass </function_calls> into your API call as a stop_sequence to ensure that Claude stops generating text once it has called a function.

After a <function_calls> block, and assuming you have the proper stop sequence in place, Claude will stop generating and wait for the function result to be passed back in a <function_results> block that looks like this:

<function_results>
<result>
<tool_name>function_name</tool_name>
<stdout>
function result goes here
</stdout>
</result>
</function_results>

The function result should be placed inside <stdout> tags. If the function raised an exception, that should be returned like:

<function_results>
<error>
error message goes here
</error>
</function_results>

The full function result should be passed back to Claude as a message that continues the conversation from before. After receiving the function results, Claude will continue generating to incorporate the results into its response.

Example legacy tool use prompt

Here is a full example of a prompt that provides Claude with two functions and a question that requires using them:

Here is how Claude would respond:

Claude first calls get_ticker_symbol to retrieve the ticker symbol for General Motors. We can recognize that Claude wants to call a function via the </function calls> stop sequence. We extract the relevant data from between the relevant XML tags and run the function on Claude's behalf. Then we pass the results back to Claude in <function_results> tags.

Now that it knows the ticker symbol, Claude will subsequently decide that it has to call get_current_stock_price and get the current price.

We pass back these results as well.

With this whole conversation chain providing Claude all the details it needs, Claude will be able to provide the user an answer as its final output.

Legacy tool use FAQ

How many tools can I pass to Claude in a given interaction?

You can define any number of tools and functions for Claude to use, although we currently recommend that you don't exceed 3-5 for this legacy tool use structure, depending on the complexity of your use case and the functions in question.

Does Claude have any built-in tools that it knows?

No. Any tools that you want Claude to use, you'll have to define yourself within a tool use prompt. Claude does not have a predetermined list of functions & definitions that work best.

When will the new tool use format come to Vertex AI or Amazon Bedrock?

In the near future!