Code beginner · 3 min read

How to use tool use with Claude API in python

Q: How to use tool use with Claude API in python

Use the anthropic.Anthropic client with the messages.create method, passing system instructions and a messages array including tool use commands in the user content to invoke tools with Claude API in Python.

Direct answer

Use the anthropic.Anthropic client with the messages.create method, passing system instructions and a messages array including tool use commands in the user content to invoke tools with Claude API in Python.

Setup

Install

bash

pip install anthropic

Env vars

ANTHROPIC_API_KEY

Imports

python

import os
import anthropic

Examples

inUse a calculator tool to add 5 and 7.

outThe calculator tool result is 12.

inUse a web search tool to find the latest news on AI.

outHere's a summary of the latest AI news from the web search tool...

inUse a translation tool to translate 'Hello' to Spanish.

outThe translation tool output: 'Hola'.

Integration steps

Install the Anthropic Python SDK and set the ANTHROPIC_API_KEY environment variable.
Import the anthropic library and initialize the Anthropic client with the API key from os.environ.
Construct the system prompt describing the assistant's role and tool use capabilities.
Create a messages array with user content specifying the tool use command or query.
Call client.messages.create with the model, system prompt, and messages to invoke the tool use.
Extract the response text from the returned message content and handle or display it.

Full code

python

import os
import anthropic

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

system_prompt = "You are an AI assistant that can use external tools when requested."

messages = [
    {"role": "user", "content": "Use a calculator tool to add 5 and 7."}
]

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    system=system_prompt,
    messages=messages
)

print("Response from Claude with tool use:")
print(response.content[0].text)

output

Response from Claude with tool use:
The calculator tool result is 12.

API trace

Request

json

{"model": "claude-3-5-sonnet-20241022", "max_tokens": 200, "system": "You are an AI assistant that can use external tools when requested.", "messages": [{"role": "user", "content": "Use a calculator tool to add 5 and 7."}]}

Response

json

{"id": "chatcmpl-xxx", "object": "chat.completion", "created": 1680000000, "model": "claude-3-5-sonnet-20241022", "choices": [{"index": 0, "message": {"role": "assistant", "content": ["The calculator tool result is 12."]}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 30, "completion_tokens": 10, "total_tokens": 40}}

Extractresponse.content[0].text

Variants

Streaming tool use response ›

Use streaming to display partial results immediately for long or interactive tool use responses.

python

import os
import anthropic

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

system_prompt = "You are an AI assistant that can use external tools when requested."

messages = [{"role": "user", "content": "Use a calculator tool to add 5 and 7."}]

for chunk in client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=200,
    system=system_prompt,
    messages=messages
):
    print(chunk.content[0].text, end='', flush=True)

Async tool use call ›

Use async calls to integrate tool use in concurrent or event-driven Python applications.

python

import os
import asyncio
import anthropic

async def main():
    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
    system_prompt = "You are an AI assistant that can use external tools when requested."
    messages = [{"role": "user", "content": "Use a calculator tool to add 5 and 7."}]
    response = await client.messages.acreate(
        model="claude-3-5-sonnet-20241022",
        max_tokens=200,
        system=system_prompt,
        messages=messages
    )
    print(response.content[0].text)

asyncio.run(main())

Use a smaller Claude model for cost savings ›

Use a smaller Claude model variant to reduce cost and latency when high precision is not critical.

python

import os
import anthropic

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

system_prompt = "You are an AI assistant that can use external tools when requested."

messages = [{"role": "user", "content": "Use a calculator tool to add 5 and 7."}]

response = client.messages.create(
    model="claude-3-5-haiku-20241022",
    max_tokens=200,
    system=system_prompt,
    messages=messages
)

print(response.content[0].text)

Performance

Latency~800ms for claude-3-5-sonnet-20241022 non-streaming calls

Cost~$0.003 per 500 tokens for claude-3-5-sonnet-20241022

Rate limitsTier 1: 300 RPM / 20K TPM

Keep system prompts concise but clear to reduce prompt tokens.
Limit max_tokens to the expected response length to avoid unnecessary cost.
Reuse context where possible to avoid resending large message histories.

Approach	Latency	Cost/call	Best for
Standard call	~800ms	~$0.003	General tool use with Claude
Streaming call	Starts in ~300ms, streams over time	~$0.003	Long or interactive tool use responses
Async call	~800ms	~$0.003	Concurrent or event-driven Python apps
Smaller model (haiku)	~600ms	~$0.0015	Cost-sensitive or lower precision needs

✓

Quick tip

Always include a clear system prompt describing tool use capabilities to guide Claude's behavior effectively.

⚠

Common mistake

Beginners often forget to use the <code>system</code> parameter for tool use instructions, causing the model to ignore tool invocation.

Verified 2026-04 · claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022

Verify ↗