Understanding How Claude Uses Tools

Welcome to understanding how Claude responds when it decides to use your tools! In the previous lesson, you learned how to create tool schemas that describe your functions to Claude. Now you'll discover how to include these tools in your API requests and, more importantly, how to interpret Claude's responses when it wants to use them.

In this lesson, you'll learn how to configure your requests to enable tool use, understand the different types of responses Claude can provide, and extract the specific information you need to execute the tools Claude requests. By the end, you'll be able to recognize when Claude wants to use a tool and gather all the details needed to make that happen.

While Claude will automatically see and can use any tools you provide in your request, mentioning tools in your system prompt can help ensure more consistent behavior and guide Claude toward using them appropriately.

Here's an example of how you can improve your system prompt:

from anthropic import Anthropic

# Initialize the Anthropic client
client = Anthropic()

# System prompt with optional tool usage guidance
system_prompt = (
    "You are a helpful math assistant. "
    "When performing calculations, use the available tools for accuracy."
)

This guidance helps Claude understand your preferences for when and how to use tools, but it's not required for tool functionality. Claude can still recognize and use tools based solely on their availability in the request.

The tools parameter is the essential component that makes your functions available to Claude. This parameter accepts the JSON array of schemas you created in the previous lesson:

import json

# Load your tool schemas
with open('schemas.json', 'r') as f:
    tool_schemas = json.load(f)

# Create a message requesting a calculation
messages = [
    {"role": "user", "content": "Please calculate 15 + 27"}
]

# Send the request with tools enabled
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2000,
    messages=messages,
    system=system_prompt,
    tools=tool_schemas  # This makes your tools available to Claude
)

Claude will recognize the available tools from the tools parameter alone. The system prompt guidance can be helpful for encouraging consistent tool usage patterns, but Claude will still be able to see and use your tools even without explicit instructions in the system prompt.

When Claude decides to use a tool, the response structure changes significantly from a simple text response. Let's examine what a complete tool use response looks like by printing the entire response structure:

# Print the complete response structure
print(json.dumps(response.model_dump(), indent=2))

This will output a detailed JSON structure showing all the components of Claude's response:

{
  "id": "msg_01LioNGfNM9nEiE1peb9ixAu",
  "content": [
    {
      "text": "I'll calculate 15 + 27 for you using the sum function.",
      "type": "text"
    },
    {
      "id": "toolu_01ErJzJmxjYisApSybjcTcs4",
      "input": {
        "a": 15,
        "b": 27
      },
      "name": "sum_numbers",
      "type": "tool_use"
    }
  ],
  "model": "claude-sonnet-4-6",
  "role": "assistant",
  "stop_reason": "tool_use",
  "type": "message",
  "usage": {...}
}

Notice two key differences from regular text responses:

• The stop_reason is "tool_use" instead of "end_turn"
• The content array contains both text and tool use blocks

This structure allows Claude to explain what it's doing while providing the structured information your system needs to execute the requested functions.

The stop_reason field is your primary indicator for determining what action to take next in your agent logic. Let's extract and examine this field to understand its possible values:

# Check the stop reason to determine next steps
print(f"Stop Reason: {response.stop_reason}")

When you run this code, you'll see the following output:

Stop Reason: tool_use

The stop_reason acts as a control flow signal for your agent. Here are the main values you'll encounter:

• "tool_use": Claude has requested tool execution and is waiting for results
• "end_turn": Claude has completed its response and the conversation can continue normally
• "max_tokens": Claude reached the token limit and may have more to say
• "stop_sequence": Claude encountered a predefined stop sequence

Understanding these values helps you build proper agent logic that responds appropriately to Claude's intentions.

When stop_reason is "tool_use", the content array contains a mix of text explanations and tool use requests. Claude includes text blocks to explain its reasoning and what it's about to do, making the interaction more transparent and user-friendly. The content array can also contain multiple tool use blocks when Claude wants to execute several tools in parallel. Each content item has a type field that tells you how to handle it.

Let's iterate through the content array to examine each item:

# Process each content item
for i, content_item in enumerate(response.content):
    print(f"\nContent Item {i+1}:")
    print(f"Type: {content_item.type}")
    
    if content_item.type == "text":
        print(f"Text: {content_item.text}")
    elif content_item.type == "tool_use":
        print(f"Tool Name: {content_item.name}")
        print(f"Tool Input: {content_item.input}")
        print(f"Tool ID: {content_item.id}")

Running this code will show you the structure of each content item:

Content Item 1:
Type: text
Text: I'll calculate 15 + 27 for you using the sum function.

Content Item 2:
Type: tool_use
Tool Name: sum_numbers
Tool Input: {'a': 15, 'b': 27}
Tool ID: toolu_01ErJzJmxjYisApSybjcTcs4

Each tool use block contains three essential pieces of information that your system needs to execute the requested function:

• name: The function name that matches your tool schema (e.g., "sum_numbers")
• input: A dictionary of parameters to pass to your function, with keys matching your schema's parameter names
• id: A unique identifier for this specific tool use request, which you'll need when sending results back to Claude

These fields work together to provide everything you need to execute the tool and maintain proper conversation flow.

You now understand how Claude communicates its tool use intentions through structured API responses. When Claude decides to use tools, it provides both human-readable explanations and machine-readable tool use blocks within the content array, with the stop_reason field acting as a control signal for your system.

In the upcoming practice exercises, you'll work with these response structures hands-on, learning to parse tool use requests and prepare for the next step: actually executing the requested tools and sending results back to Claude to complete the conversation flow.