Completing the Tool Use Cycle

Introduction & Overview

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.

The Complete Tool Execution Flow

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: Set up the foundation - Create function mappings, tool schemas, and initial conversation messages Send the initial request - Make the first API call to Claude with the user's question and available tools Detect tool use requests - Check Claude's response for the "tool_use" stop reason Extract tool information - Pull out the function name, parameters, and unique ID from each tool use block Execute the requested functions - Use our function mapping to call the actual TypeScript functions with Claude's parameters Collect and format tool results - Structure all function outputs in the specific format Claude expects Send results back to Claude - Make a second API call with the complete conversation, including tool results 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.

Setting Up the Foundation

Before diving into tool execution, we need to establish the foundation that connects Claude's tool requests to our actual TypeScript functions. As we covered in previous lessons, this involves creating a mapping object and preparing our tool schemas and initial messages. The critical component here is the function mapping object — this serves as the bridge between the tool names Claude uses and our actual TypeScript functions. TypeScriptimport fs from 'fs'; import Anthropic from "@anthropic-ai/sdk"; import { sumNumbers, multiplyNumbers } from './functions'; // Initialize the Anthropic client const client = new Anthropic(); // Create an object mapping tool names to functions // This is crucial - the keys must match our tool schema names exactly const tools: Record<string, Function> = { "sum_numbers": sumNumbers, "multiply_numbers": multiplyNumbers }; // Choose a Claude model const model = "claude-sonnet-4-6"; // System prompt with explicit instructions to use tools const systemPrompt = "You are a helpful math assistant. " + "Always use the available tools to perform calculations accurately."; // Load the schemas from JSON file const schemasJson = fs.readFileSync('schemas.json', 'utf-8'); const toolSchemas = JSON.parse(schemasJson); // Create an array of messages to send to Claude const messages: Anthropic.MessageParam[] = [ { role: "user", content: "Please calculate 15 + 27" } ];import fs from 'fs'; import Anthropic from "@anthropic-ai/sdk"; import { sumNumbers, multiplyNumbers } from './functions'; // Initialize the Anthropic client const client = new Anthropic(); // Create an object mapping tool names to functions // This is crucial - the keys must match our tool schema names exactly const tools: Record<string, Function> = { "sum_numbers": sumNumbers, "multiply_numbers": multiplyNumbers }; // Choose a Claude model const model = "claude-sonnet-4-6"; // System prompt with explicit instructions to use tools const systemPrompt = "You are a helpful math assistant. " + "Always use the available tools to perform calculations accurately."; // Load the schemas from JSON file const schemasJson = fs.readFileSync('schemas.json', 'utf-8'); const toolSchemas = JSON.parse(schemasJson); // Create an array of messages to send to Claude const messages: Anthropic.MessageParam[] = [ { role: "user", content: "Please calculate 15 + 27" } ]; This setup creates everything we need for tool execution: the tools object enables dynamic function lookup, the systemPrompt guides Claude's behavior, the toolSchemas 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.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

TypeScript

import fs from 'fs';
import Anthropic from "@anthropic-ai/sdk";
import { sumNumbers, multiplyNumbers } from './functions';

// Initialize the Anthropic client
const client = new Anthropic();

// Create an object mapping tool names to functions
// This is crucial - the keys must match our tool schema names exactly
const tools: Record<string, Function> = {
    "sum_numbers": sumNumbers,
    "multiply_numbers": multiplyNumbers
};

// Choose a Claude model
const model = "claude-sonnet-4-6";

// System prompt with explicit instructions to use tools
const systemPrompt = 
    "You are a helpful math assistant. " +
    "Always use the available tools to perform calculations accurately.";

// Load the schemas from JSON file
const schemasJson = fs.readFileSync('schemas.json', 'utf-8');
const toolSchemas = JSON.parse(schemasJson);

// Create an array of messages to send to Claude
const messages: Anthropic.MessageParam[] = [
    { role: "user", content: "Please calculate 15 + 27" }
];

TypeScript

// Send the messages to Claude with all necessary components
const response = await client.messages.create({
    model: model,
    max_tokens: 2000,
    messages: messages,      // The initial user message
    system: systemPrompt,    // Instructions for Claude's behavior
    tools: toolSchemas       // Available tools and their specifications
});

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

// Send the messages to Claude with all necessary components
const response = await client.messages.create({
    model: model,
    max_tokens: 2000,
    messages: messages,      // The initial user message
    system: systemPrompt,    // Instructions for Claude's behavior
    tools: toolSchemas       // Available tools and their specifications
});

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

TypeScript

// Check if Claude wants to use any functions and execute them
if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    // Execute each tool use by iterating through response content
    for (const contentItem of response.content) {
        // Check if this content item is a tool use request
        if (contentItem.type === "tool_use") {
            // Extract the three essential pieces of information
            const toolName = contentItem.name;    // Which function to call
            const toolInput = contentItem.input;  // Parameters for the function
            const toolId = contentItem.id;        // Unique identifier for this tool use
            
            // Print the tool execution details for debugging
            console.log(`Executing: ${toolName}(${JSON.stringify(toolInput)})`);

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            // Use try-catch to handle both missing tools and execution errors
            let result: any;
            try {
                // Check if the requested tool exists and execute it
                if (toolName in tools) {
                    result = tools[toolName](toolInput.a, toolInput.b);
                } else {
                    result = `Error: Function ${toolName} not found`;
                }
            } catch (e: any) {
                // Handle any errors that occur during function execution
                result = `Error executing ${toolName}: ${e.message}`;
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",         // Special content type for tool results
                tool_use_id: toolId,         // Links result to original request
                content: String(result)      // The actual function output as string
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",                        // Results come from user perspective
        content: toolResults                 // Array of all tool results
    });

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",         // Special content type for tool results
                tool_use_id: toolId,         // Links result to original request
                content: String(result)      // The actual function output as string
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",                        // Results come from user perspective
        content: toolResults                 // Array of all tool results
    });

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",
                tool_use_id: toolId,
                content: String(result)
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",
        content: toolResults
    });
    
    // Send the complete conversation with tool results back to Claude
    const finalResponse = await client.messages.create({
        model: model,
        max_tokens: 2000,
        messages: messages,  // Now includes tool results
        system: systemPrompt,
        tools: toolSchemas
    });
    
    // Add Claude's final response to maintain conversation history
    messages.push({
        role: "assistant",
        content: finalResponse.content
    });
    
    // Display Claude's final response to the user
    console.log("\nClaude's final response:");
    const textContent = finalResponse.content.find(block => block.type === "text");
    if (textContent && textContent.type === "text") {
        console.log(textContent.text);
    }
}

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",
                tool_use_id: toolId,
                content: String(result)
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",
        content: toolResults
    });
    
    // Send the complete conversation with tool results back to Claude
    const finalResponse = await client.messages.create({
        model: model,
        max_tokens: 2000,
        messages: messages,  // Now includes tool results
        system: systemPrompt,
        tools: toolSchemas
    });
    
    // Add Claude's final response to maintain conversation history
    messages.push({
        role: "assistant",
        content: finalResponse.content
    });
    
    // Display Claude's final response to the user
    console.log("\nClaude's final response:");
    const textContent = finalResponse.content.find(block => block.type === "text");
    if (textContent && textContent.type === "text") {
        console.log(textContent.text);
    }
}

text

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

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

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

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

TypeScript

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else {
    // Handle non-tool responses by displaying Claude's direct answer
}

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else {
    // Handle non-tool responses by displaying Claude's direct answer
}

TypeScript

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else if (response.stop_reason === "end_turn") {
    // Handle end_turn responses by displaying Claude's direct answer
}

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else if (response.stop_reason === "end_turn") {
    // Handle end_turn responses by displaying Claude's direct answer
}

TypeScript

// Print the complete messages history to understand the conversation flow
console.log("\nMessages history:");
// Loop through each message to see the conversation development
messages.forEach((message, i) => {
    console.log(`\nMessage ${i + 1} - Role: ${message.role}`);
    // Handle different content formats (string vs array)
    if (typeof message.content === 'string') {
        console.log(`Content: ${message.content}`);
    } else {
        // For array content, print each item separately
        message.content.forEach((content, j) => {
            console.log(`Content ${j + 1}: ${JSON.stringify(content)}`);
        });
    }
});

text

Messages history:

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

Message 2 - Role: assistant
Content 1: {"type":"text","text":"I'll calculate 15 + 27 for you using the sum function."}
Content 2: {"type":"tool_use","id":"toolu_019bJn2Ty6F4Pdn6ugx4d2iS","name":"sum_numbers","input":{"a":15,"b":27}}

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

Message 4 - Role: assistant
Content 1: {"type":"text","text":"The result of 15 + 27 is 42."}

TypeScript

// Send the messages to Claude with all necessary components
const response = await client.messages.create({
    model: model,
    max_tokens: 2000,
    messages: messages,      // The initial user message
    system: systemPrompt,    // Instructions for Claude's behavior
    tools: toolSchemas       // Available tools and their specifications
});

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

TypeScript

// Check if Claude wants to use any functions and execute them
if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    // Execute each tool use by iterating through response content
    for (const contentItem of response.content) {
        // Check if this content item is a tool use request
        if (contentItem.type === "tool_use") {
            // Extract the three essential pieces of information
            const toolName = contentItem.name;    // Which function to call
            const toolInput = contentItem.input;  // Parameters for the function
            const toolId = contentItem.id;        // Unique identifier for this tool use
            
            // Print the tool execution details for debugging
            console.log(`Executing: ${toolName}(${JSON.stringify(toolInput)})`);

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            // Use try-catch to handle both missing tools and execution errors
            let result: any;
            try {
                // Check if the requested tool exists and execute it
                if (toolName in tools) {
                    result = tools[toolName](toolInput.a, toolInput.b);
                } else {
                    result = `Error: Function ${toolName} not found`;
                }
            } catch (e: any) {
                // Handle any errors that occur during function execution
                result = `Error executing ${toolName}: ${e.message}`;
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",         // Special content type for tool results
                tool_use_id: toolId,         // Links result to original request
                content: String(result)      // The actual function output as string
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",                        // Results come from user perspective
        content: toolResults                 // Array of all tool results
    });

TypeScript

if (response.stop_reason === "tool_use") {
    // Define an array to collect all tool results
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const contentItem of response.content) {
        if (contentItem.type === "tool_use") {
            // Extract tool name, input and id...
            
            try {
                // Execute the tool if it exists...
            } catch (e: any) {
                // Handle errors...
            }
            
            // Print the result for debugging and verification
            console.log(`Result: ${result}`);
            
            // Append a properly structured tool_result for this specific tool_use
            toolResults.push({
                type: "tool_result",
                tool_use_id: toolId,
                content: String(result)
            });
        }
    }

    // Add all tool results as a single user message
    messages.push({
        role: "user",
        content: toolResults
    });
    
    // Send the complete conversation with tool results back to Claude
    const finalResponse = await client.messages.create({
        model: model,
        max_tokens: 2000,
        messages: messages,  // Now includes tool results
        system: systemPrompt,
        tools: toolSchemas
    });
    
    // Add Claude's final response to maintain conversation history
    messages.push({
        role: "assistant",
        content: finalResponse.content
    });
    
    // Display Claude's final response to the user
    console.log("\nClaude's final response:");
    const textContent = finalResponse.content.find(block => block.type === "text");
    if (textContent && textContent.type === "text") {
        console.log(textContent.text);
    }
}

text

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

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

TypeScript

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else {
    // Handle non-tool responses by displaying Claude's direct answer
}

TypeScript

if (response.stop_reason === "tool_use") {
    // Execute tools and get final response...
} else if (response.stop_reason === "end_turn") {
    // Handle end_turn responses by displaying Claude's direct answer
}

TypeScript

// Print the complete messages history to understand the conversation flow
console.log("\nMessages history:");
// Loop through each message to see the conversation development
messages.forEach((message, i) => {
    console.log(`\nMessage ${i + 1} - Role: ${message.role}`);
    // Handle different content formats (string vs array)
    if (typeof message.content === 'string') {
        console.log(`Content: ${message.content}`);
    } else {
        // For array content, print each item separately
        message.content.forEach((content, j) => {
            console.log(`Content ${j + 1}: ${JSON.stringify(content)}`);
        });
    }
});

text

Messages history:

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

Message 2 - Role: assistant
Content 1: {"type":"text","text":"I'll calculate 15 + 27 for you using the sum function."}
Content 2: {"type":"tool_use","id":"toolu_019bJn2Ty6F4Pdn6ugx4d2iS","name":"sum_numbers","input":{"a":15,"b":27}}

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

Message 4 - Role: assistant
Content 1: {"type":"text","text":"The result of 15 + 27 is 42."}

Introduction & Overview

The Complete Tool Execution Flow

Setting Up the Foundation

Join the 1M+ learners on CodeSignal

Sending the Initial Request

Detecting Tool Use Requests

Executing the Requested Functions

Collecting and Formatting Tool Results

Getting Claude's Final Response

Handling Non-Tool Responses

Visualizing the Complete Conversation History

Summary & Practice Preparation