Completing the Tool Use Cycle

In the previous lessons, you learned how to create tool schemas and understand Claude's responses when it wants to use tools. You can now recognize when Claude requests tool execution through the stop_reason: "tool_use" signal and extract the necessary details from tool use blocks. However, knowing what Claude wants to do is only half the story — you still need to actually execute those tools and complete the conversation cycle.

In this lesson, you'll learn how to bridge that gap by executing the functions Claude requests, capturing their results, and sending those results back to Claude in the proper format. By the end of this lesson, you'll have a complete tool execution pipeline that can handle Claude's tool requests from start to finish, maintaining proper conversation flow throughout the entire process.

Before we dive into the implementation, let's understand the complete workflow we'll be building in this lesson. Here's the step-by-step process that transforms Claude from a simple chatbot into a capable agent:

1. Set up the foundation - Create function mappings, tool schemas, and initial conversation messages
2. Send the initial request - Make the first API call to Claude with the user's question and available tools
3. Detect tool use requests - Check Claude's response for the "tool_use" stop reason
4. Extract tool information - Pull out the function name, parameters, and unique ID from each tool use block
5. Execute the requested functions - Use our function mapping to call the actual Python functions with Claude's parameters
6. Collect and format tool results - Structure all function outputs in the specific format Claude expects
7. Send results back to Claude - Make a second API call with the complete conversation including tool results
8. Display the final response - Show Claude's natural language answer that incorporates the tool outputs

This complete cycle enables Claude to seamlessly use tools as part of its reasoning process, transforming raw function outputs into conversational responses that directly answer user questions.

Before diving into tool execution, we need to establish the foundation that connects Claude's tool requests to our actual Python functions. As we covered in previous lessons, this involves creating a mapping dictionary and preparing our tool schemas and initial messages. The critical component here is the function mapping dictionary — this serves as the bridge between the tool names Claude uses and our actual Python functions.

import json
from anthropic import Anthropic
from functions import sum_numbers, multiply_numbers

# Initialize the Anthropic client
client = Anthropic()

# Create a dictionary mapping tool names to functions
# This is crucial - the keys must match our tool schema names exactly
tools = {
    "sum_numbers": sum_numbers,
    "multiply_numbers": multiply_numbers
}

# Choose a Claude model
model = "claude-sonnet-4-6"

# System prompt with explicit instructions to use tools
system_prompt = (
    "You are a helpful math assistant. "
    "Always use the available tools to perform calculations accurately."
)

# Load the schemas from JSON file
with open('schemas.json', 'r') as f:
    tool_schemas = json.load(f)

# Create a list of messages to send to Claude
messages = [
    {"role": "user", "content": "Please calculate 15 + 27"}
]

This setup creates everything we need for tool execution: the tools dictionary enables dynamic function lookup, the system_prompt guides Claude's behavior, the tool_schemas provide technical specifications, and the messages array starts the conversation. The function mapping is particularly important because it allows our code to execute the correct function based on Claude's string-based tool requests.

With our foundation in place, we can now send the initial request to Claude and immediately prepare for processing its response. This approach ensures we maintain proper conversation history from the start.

# Send the messages to Claude with all necessary components
response = client.messages.create(
    model=model,
    max_tokens=2000,
    messages=messages,     # The initial user message
    system=system_prompt,  # Instructions for Claude's behavior
    tools=tool_schemas.    # Available tools and their specifications
)

# Add the assistant's response content to messages immediately
# This maintains conversation history regardless of the response type
messages.append({
    "role": "assistant", 
    "content": response.content
})

This API call provides Claude with the complete context: the user's question through messages, behavioral guidance through system, and available capabilities through tools. By immediately adding Claude's response to the messages array, we ensure proper conversation flow whether Claude needs tools or can answer directly.

After receiving Claude's response and adding it to our conversation history, we examine the stop_reason field to determine if tool execution is needed. When Claude determines that tools are required, it signals this through the "tool_use" stop reason.

# Check if Claude wants to use any functions and execute them
if response.stop_reason == "tool_use":
    # Define a list to collect all tool results
    tool_results = []
    
    # Execute each tool use by iterating through response content
    for content_item in response.content:
        # Check if this content item is a tool use request
        if content_item.type == "tool_use":
            # Extract the three essential pieces of information
            tool_name = content_item.name    # Which function to call
            tool_input = content_item.input  # Parameters for the function
            tool_id = content_item.id       # Unique identifier for this tool use
            
            # Print the tool execution details for debugging
            print(f"Executing: {tool_name}({tool_input})")

The stop_reason == "tool_use" condition indicates that Claude has identified tools it wants to execute and is waiting for their results before continuing. We initialize a tool_results list to collect all the results from this tool execution cycle. The extraction process identifies each tool use block within Claude's response and pulls out the three critical pieces of information: the function name, the input parameters, and the unique identifier. The tool_id is particularly important because we'll need it to match results back to their corresponding tool requests.

With the tool information extracted, we can now execute the actual Python functions using our mapping dictionary. This is where the tool names from Claude's requests get translated into actual function calls.

if response.stop_reason == "tool_use":
    # Define a list to collect all tool results
    tool_results = []
    
    for content_item in response.content:
        if content_item.type == "tool_use":
            # Extract tool name, input and id...
            
            # Use try-except to handle both missing tools and execution errors
            try:
                # Check if the requested tool exists and execute it
                if tool_name in tools:
                    result = tools[tool_name](**tool_input)
                else:
                    result = f"Error: Function {tool_name} not found"
            except Exception as e:
                # Handle any errors that occur during function execution
                result = f"Error executing {tool_name}: {str(e)}"
            
            # Print the result for debugging and verification
            print(f"Result: {result}")

Using a try-except block provides comprehensive error handling that catches not only missing tools but also any runtime errors that might occur during function execution. For example, if a function receives invalid parameters (like trying to divide by zero), the exception will be caught and converted into an error message that can be sent back to Claude. The tools[tool_name] lookup retrieves the actual function object from our mapping dictionary, while **tool_input unpacks the input dictionary as keyword arguments. This approach allows dynamic function execution based on Claude's string-based requests while gracefully handling both missing functions and execution failures.

After executing each tool (or encountering an error), we must format the results in the specific structure that Claude expects and collect them all before sending them back. This ensures that all tool results are sent together as a single message.

if response.stop_reason == "tool_use":
    # Define a list to collect all tool results
    tool_results = []
    
    for content_item in response.content:
        if content_item.type == "tool_use":
            # Extract tool name, input and id...
            
            try:
                # Execute the tool if it exists...
            except Exception as e:
                # Handle errors...
            
            # Print the result for debugging and verification
            print(f"Result: {result}")
            
            # Append a properly structured tool_result for this specific tool_use
            tool_results.append({
                "type": "tool_result",         # Special content type for tool results
                "tool_use_id": tool_id,        # Links result to original request
                "content": str(result)         # The actual function output as string
            })

    # Add all tool results as a single user message
    messages.append({
        "role": "user",                        # Results come from user perspective
        "content": tool_results                # List of all tool results
    })

The tool result structure has specific requirements: each result needs a "tool_result" type, the tool_use_id must exactly match the id from the original tool use block, and the content must be converted to a string. By collecting all results in a list and sending them as a single message, we maintain proper conversation structure while ensuring Claude receives results for all requested tools.

It's critical that you provide a tool result for every tool use request that Claude makes. If you skip providing a result for any tool_use_id, your next API call to Claude will fail with an error because Claude expects to receive results for all the tools it requested. This is why we handle both successful executions and errors in the same way - Claude needs to know what happened with each tool request, whether it succeeded or failed.

Once we've executed all requested tools and added their results to the messages array as a single message, we can send the updated conversation back to Claude to get the final response that incorporates the tool results.

if response.stop_reason == "tool_use":
    # Define a list to collect all tool results
    tool_results = []
    
    for content_item in response.content:
        if content_item.type == "tool_use":
            # Extract tool name, input and id...
            
            try:
                # Execute the tool if it exists...
            except Exception as e:
                # Handle errors...
            
            # Print the result for debugging and verification
            print(f"Result: {result}")
            
            # Append a properly structured tool_result for this specific tool_use
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": tool_id,
                "content": str(result)
            })

    # Add all tool results as a single user message
    messages.append({
        "role": "user",
        "content": tool_results
    })
    
    # Send the complete conversation with tool results back to Claude
    final_response = client.messages.create(
        model=model,
        max_tokens=2000,
        messages=messages,  # Now includes tool results
        system=system_prompt,
        tools=tool_schemas
    )
    
    # Add Claude's final response to maintain conversation history
    messages.append({
        "role": "assistant",
        "content": final_response.content
    })
    
    # Display Claude's final response to the user
    print("\nClaude's final response:")
    print(final_response.content[0].text)

This second API call uses the same parameters as the first, but now the messages array contains the complete conversation history including all tool results in a single message. Claude can now provide a comprehensive answer that incorporates the tool execution results, transforming raw calculation outputs into natural, conversational responses.

The complete execution flow produces the following output, showing both the tool execution and Claude's final response:

Executing: sum_numbers({'a': 15, 'b': 27})
Result: 42

Claude's final response:
The result of 15 + 27 is 42.

This output demonstrates the complete tool execution cycle: our code executes the requested function with the provided parameters, captures the numerical result, and then Claude transforms that raw output into a natural, conversational response that directly answers the user's original question.

Not every user request will require tool usage. When Claude can answer directly without needing to execute functions, it will respond with a different stop_reason. Since we've already added Claude's response to our messages array, we just need to handle the display of non-tool responses.

if response.stop_reason == "tool_use":
    # Execute tools and get final response...
else:
    # Handle non-tool responses by displaying Claude's direct answer

This else block catches any stop_reason that isn't "tool_use" and handles it appropriately. The most common alternative stop_reason is "end_turn", which indicates Claude has finished its response and doesn't need any tools to answer the user's question.

If you prefer to be more explicit about which stop reasons you're handling, you can replace the general else with a specific condition:

if response.stop_reason == "tool_use":
    # Execute tools and get final response...
elif response.stop_reason == "end_turn":
    # Handle end_turn responses by displaying Claude's direct answer

Both approaches accomplish the same goal, but the explicit elif makes it clear that you're specifically handling the "end_turn" case. For example, if a user asks "What is the capital of France?", Claude would respond directly with stop_reason: "end_turn" since no mathematical calculations are needed. This ensures your application handles both tool-requiring and non-tool scenarios gracefully, maintaining proper conversation flow in all cases.

Throughout the tool execution cycle, maintaining proper conversation history enables Claude to understand context and provide coherent responses. Let's examine how the complete conversation flow develops through each step of the process.

# Print the complete messages history to understand the conversation flow
print("Messages history:")
# Loop through each message to see the conversation development
for i, message in enumerate(messages):
    print(f"\nMessage {i+1} - Role: {message['role']}")
    # Handle different content formats (string vs list)
    if isinstance(message['content'], str):
        print(f"Content: {message['content']}")
    else:
        # For list content, print each item separately
        for j, content in enumerate(message['content']):
            print(f"Content {j+1}: {content}")

We check for strings vs lists because message content can be either format: simple user messages are often strings (like our initial "Please calculate 15 + 27"), while SDK responses and tool results are always lists of structured content blocks. Without this check, iterating over a string would print each character separately instead of the full message.

This debugging output reveals the complete conversation structure that enables Claude's tool-using capabilities:

Messages history:

Message 1 - Role: user
Content: Please calculate 15 + 27

Message 2 - Role: assistant
Content 1: TextBlock(citations=None, text="I'll calculate 15 + 27 for you using the sum function.", type='text')
Content 2: ToolUseBlock(id='toolu_01WoJkVy95JFbdu633otcc5W', input={'a': 15, 'b': 27}, name='sum_numbers', type='tool_use')

Message 3 - Role: user
Content 1: {'type': 'tool_result', 'tool_use_id': 'toolu_01WoJkVy95JFbdu633otcc5W', 'content': '42'}

Message 4 - Role: assistant
Content 1: TextBlock(citations=None, text='The result of 15 + 27 is 42.', type='text')

This conversation history shows the complete tool execution cycle: the user's initial request, Claude's response containing both explanation and tool request, our tool result with the matching ID, and Claude's final response incorporating the tool output. This structure demonstrates how proper message management creates seamless conversation flow that transforms Claude into a capable agent.

You now understand the complete tool execution workflow that transforms Claude from a text-only assistant into an agent capable of performing actions and calculations. The process involves detecting tool use requests through stop reasons, executing functions through mapping dictionaries, collecting and formatting all results together, and maintaining conversation history throughout the entire cycle.

The key components work together to create a robust system: function mapping enables dynamic execution, proper result collection ensures all tools are handled, correct message formatting allows Claude to understand results, and conversation history maintains context across the entire interaction. This foundation allows Claude to act as an intelligent agent that can reason about when to use tools and incorporate their results into natural responses.

In the upcoming practice exercises, you'll implement this complete workflow yourself, working with different types of tools and handling various scenarios, including multiple tool uses and error handling. Happy coding!