Principle:Anthropics Anthropic sdk python Message Request With Tools

Knowledge Sources	Anthropic Python SDK Anthropic Tool Use Docs
Domains	Tool_Use, LLM, Function_Calling
Last Updated	2026-02-15 00:00 GMT

Overview

Message Request With Tools describes how the Anthropic Python SDK extends standard LLM message creation requests with tool definitions, enabling Claude to recognize available functions and decide whether to invoke them. This is the second step in the Tool Use Integration workflow: after defining tools, they must be sent alongside the conversation messages so the model knows what capabilities are available.

Theory: Extending LLM Requests with Tool Definitions

A standard messages.create() call sends a conversation (a sequence of user and assistant messages) to Claude and receives a text response. When tools are added, the request gains two additional dimensions:

1. Tool definitions (tools parameter): An array of tool schemas telling the model what functions exist, what they do, and what parameters they accept
2. Tool choice strategy (tool_choice parameter): A directive controlling whether and how the model should use the provided tools

The model processes both the conversation context and the tool definitions together, deciding on each turn whether the user's request is best served by generating text directly or by requesting a tool invocation.

Tool Choice Strategies

The tool_choice parameter accepts four strategy types, each encoded as a TypedDict with a type discriminator:

Strategy	Type Value	Behavior	Use Case
Auto	{"type": "auto"}	Model decides freely whether to call a tool or respond with text	Default for most applications; the model uses judgment
Any	{"type": "any"}	Model must call at least one tool	Force tool use when you know the request requires a function call
Tool	{"type": "tool", "name": "get_weather"}	Model must call the specific named tool	Force a particular tool for structured extraction
None	{"type": "none"}	Model cannot use any tools, even if definitions are provided	Temporarily disable tools without removing them from the request

All strategy types except none support an optional disable_parallel_tool_use boolean. When set to true, the model outputs at most one tool call per response (for auto) or exactly one (for any and tool).

How the Model Decides

When tool_choice is auto (or omitted, defaulting to auto behavior), Claude evaluates:

1. Relevance: Does the user's request match what any tool can do?
2. Necessity: Can the request be answered from the model's training data, or does it require live data / side effects?
3. Specificity: Which tool best matches, and does the model have enough information to fill required parameters?

If the model determines a tool call is warranted, it emits a response with stop_reason="tool_use" and one or more tool_use content blocks. Otherwise, it responds with text and stop_reason="end_turn".

The ToolUnionParam Type

The tools parameter accepts an Iterable[ToolUnionParam], which is a union of all supported tool parameter types:

ToolUnionParam = Union[
    ToolParam,                      # Custom user-defined tools
    ToolBash20250124Param,          # Built-in bash tool
    ToolTextEditor20250124Param,    # Built-in text editor (Jan 2025)
    ToolTextEditor20250429Param,    # Built-in text editor (Apr 2025)
    ToolTextEditor20250728Param,    # Built-in text editor (Jul 2025)
    WebSearchTool20250305Param,     # Built-in web search tool
]

For custom tools defined via @beta_tool, the .to_dict() method produces a ToolParam (or BetaToolParam) that fits directly into this union.

Request Structure Example

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "The city name"},
                    "unit": {"type": "string", "default": "celsius"}
                },
                "required": ["city"]
            }
        }
    ],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "What's the weather in London?"}]
)

Key Behaviors

• Multiple tools: You can pass many tool definitions in one request; the model selects the appropriate one(s)
• Parallel tool use: By default, the model may emit multiple tool_use blocks in a single response, calling several tools at once
• Tool descriptions matter: The model relies heavily on the description field to decide when and how to use each tool; detailed descriptions improve accuracy
• Schema enforcement: When strict: true is set on a tool, the API guarantees the model's output conforms to the schema

Related Pages

Implemented By

• Implementation:Anthropics_Anthropic_sdk_python_Messages_Create_With_Tools