How to Intermediate · 3 min read

How to use tool use for structured output in Claude

Q: How to use tool use for structured output in Claude

Use the tool use feature in Claude by specifying a tool object in your messages with a name and parameters schema. This guides Claude to produce structured JSON output matching the tool's schema. Use the anthropic.Anthropic SDK with system= and messages=[{"role": "user", "content": ...}] to invoke the model and parse the structured response.

Quick answer

Use the tool use feature in Claude by specifying a tool object in your messages with a name and parameters schema. This guides Claude to produce structured JSON output matching the tool's schema. Use the anthropic.Anthropic SDK with system= and messages=[{"role": "user", "content": ...}] to invoke the model and parse the structured response.

PREREQUISITES

Python 3.8+
Anthropic API key
pip install anthropic>=0.20

Setup

Install the Anthropic Python SDK and set your API key as an environment variable.

Run pip install anthropic to install the SDK.
Set your API key in your shell: export ANTHROPIC_API_KEY='your_api_key_here'.

bash

pip install anthropic

Step by step

Use the tool use feature by defining a tool with a JSON schema for the expected structured output. Pass this tool definition in the tools parameter and call client.messages.create with the tool_use message referencing the tool name. The response will contain structured JSON matching the schema.

python

import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# Define the tool with a JSON schema for structured output
my_tool = {
    "name": "get_user_info",
    "description": "Extract user information as structured JSON.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "User's full name"},
            "age": {"type": "integer", "description": "User's age"},
            "email": {"type": "string", "description": "User's email address"}
        },
        "required": ["name", "age", "email"]
    }
}

# Compose the messages with tool_use referencing the tool
messages = [
    {"role": "tool_use", "content": {"tool": "get_user_info", "input": "Please provide user info for John Doe, 30 years old, email john@example.com."}}
]

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    system="You are a helpful assistant that outputs structured JSON using the tool schema.",
    messages=messages,
    tools=[my_tool],
    max_tokens=300
)

# The structured JSON output is in response.content[0].text
print(response.content[0].text)

output

{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com"
}

Common variations

You can use different Claude models like claude-sonnet-4-5 or claude-opus-4 for structured output. Async calls are not supported in the Anthropic SDK currently. You can also define multiple tools and invoke them by name in tool_use messages. Adjust max_tokens and system prompt for more complex schemas.

Troubleshooting

If the output is not valid JSON, ensure your tool schema is correct and the system prompt instructs Claude to strictly follow the schema.
If you get an error about missing tools, verify the tools parameter includes your tool definitions.
Check your API key environment variable if authentication fails.

✅

Key Takeaways

Use the tools parameter with a JSON schema to define expected structured output in Claude.
Invoke structured output by sending a tool_use message referencing the tool name.
Parse the structured JSON from response.content[0].text after the API call.
Use the system= parameter to instruct Claude to strictly follow the schema.
Verify environment variables and tool definitions if output is not as expected.

Verified 2026-04 · claude-3-5-sonnet-20241022, claude-sonnet-4-5, claude-opus-4

Verify ↗