Appendix 10.2: Tool Use

• Lesson
• Exercises
• Example Playground

Setup

Run the following setup cell to load your API key and establish the get_completion helper function.

Lesson

While it might seem conceptually complex at first, tool use, a.k.a. function calling, is actually quite simple! You already know all the skills necessary to implement tool use, which is really just a combination of substitution and prompt chaining.

In previous substitution exercises, we substituted text into prompts. With tool use, we substitute tool or function results into prompts. Claude can't literally call or access tools and functions. Instead, we have Claude:

1. Output the tool name and arguments it wants to call
2. Halt any further response generation while the tool is called
3. Then we reprompt with the appended tool results

Function calling is useful because it expands Claude's capabilities and enables Claude to handle much more complex, multi-step tasks. Some examples of functions you can give Claude:

• Calculator
• Word counter
• SQL database querying and data retrieval
• Weather API

You can get Claude to do tool use by combining these two elements:

1. A system prompt, in which we give Claude an explanation of the concept of tool use as well as a detailed descriptive list of the tools it has access to
2. The control logic with which to orchestrate and execute Claude's tool use requests

Tool use roadmap

This lesson teaches our current tool use format. However, we will be updating and improving tool use functionality in the near future, including:

• A more streamlined format for function definitions and calls
• More robust error handling and edge case coverage
• Tighter integration with the rest of our API
• Better reliability and performance, especially for more complex tool use tasks

Examples

To enable tool use in Claude, we start with the system prompt. In this special tool use system prompt, wet tell Claude:

• The basic premise of tool use and what it entails
• How Claude can call and use the tools it's been given
• A detailed list of tools it has access to in this specific scenario

Here's the first part of the system prompt, explaining tool use to Claude. This part of the system prompt is generalizable across all instances of prompting Claude for tool use. The tool calling structure we're giving Claude (<function_calls> [...] </function_calls>) is a structure Claude has been specifically trained to use, so we recommend that you stick with this.

Here's the second part of the system prompt, which defines the exact tools Claude has access to in this specific situation. In this example, we will be giving Claude a calculator tool, which takes three parameters: two operands and an operator.

Then we combine the two parts of the system prompt.

Now we can give Claude a question that requires use of the calculator tool. We will use <function_calls\> in stop_sequences to detect if and when Claude calls the function.

Now, we can extract out the parameters from Claude's function call and actually run the function on Claude's behalf.

First we'll define the function's code.

Then we'll extract the parameters from Claude's function call response. If all the parameters exist, we run the calculator tool.

Now that we have a result, we have to properly format that result so that when we pass it back to Claude, Claude understands what tool that result is in relation to. There is a set format for this that Claude has been trained to recognize:

<function_results>
<result>
<tool_name>{TOOL_NAME}</tool_name>
<stdout>
{TOOL_RESULT}
</stdout>
</result>
</function_results>

Run the cell below to format the above tool result into this structure.

Now all we have to do is send this result back to Claude by appending the result to the same message chain as before, and we're good!

Congratulations on running an entire tool use chain end to end!

Now what if we give Claude a question that doesn't that doesn't require using the given tool at all?

Success! As you can see, Claude knew not to call the function when it wasn't needed.

If you would like to experiment with the lesson prompts without changing any content above, scroll all the way to the bottom of the lesson notebook to visit the Example Playground.

Exercises

• Exercise 10.2.1 - SQL

Exercise 10.2.1 - SQL

In this exercise, you'll be writing a tool use prompt for querying and writing to the world's smallest "database". Here's the initialized database, which is really just a dictionary.

And here is the code for the functions that write to and from the database.

To solve the exercise, start by defining a system prompt like system_prompt_tools_specific_tools above. Make sure to include the name and description of each tool, along with the name and type and description of each parameter for each function. We've given you some starting scaffolding below.

When you're ready, you can try out your tool definition system prompt on the examples below. Just run the below cell!

If you did it right, the function calling messages should call the add_user, add_product, get_user, and get_product functions correctly.

For extra credit, add some code cells and write parameter-parsing code. Then call the functions with the parameters Claude gives you to see the state of the "database" after the call.

❓ If you want to see a possible solution, run the cell below!

Congrats!

Congratulations on learning tool use and function calling! Head over to the last appendix section if you would like to learn more about search & RAG.

Example Playground

This is an area for you to experiment freely with the prompt examples shown in this lesson and tweak prompts to see how it may affect Claude's responses.