Implementation:Anthropics Anthropic sdk python BetaToolUnionParam

Knowledge Sources	Anthropic SDK Python
Domains	API_Types, Beta_Features
Last Updated	2026-02-15 12:00 GMT

Overview

BetaToolUnionParam is a central union type alias that represents all possible tool definition types that can be passed to the beta Messages API. It encompasses custom tools, built-in Anthropic tools (computer use, bash, text editor, code execution), web search, web fetch, tool search, memory tools, and MCP toolsets.

Description

BetaToolUnionParam is defined as a TypeAlias using typing.Union and aggregates 17 distinct tool definition types. This union is the type expected for individual elements in the tools parameter of a beta Messages API request.

The union includes:

BetaToolParam -- Custom user-defined tools with JSON Schema input
BetaToolBash20241022Param / BetaToolBash20250124Param -- Bash shell tool (two versions)
BetaCodeExecutionTool20250522Param / BetaCodeExecutionTool20250825Param -- Code execution tools (two versions)
BetaToolComputerUse20241022Param / BetaToolComputerUse20250124Param / BetaToolComputerUse20251124Param -- Computer use tools (three versions)
BetaMemoryTool20250818Param -- Memory persistence tool
BetaToolTextEditor20241022Param / BetaToolTextEditor20250124Param / BetaToolTextEditor20250429Param / BetaToolTextEditor20250728Param -- Text editor tools (four versions)
BetaWebSearchTool20250305Param -- Web search tool
BetaWebFetchTool20250910Param -- Web fetch tool
BetaToolSearchToolBm25_20251119Param / BetaToolSearchToolRegex20251119Param -- Tool search tools (BM25 and regex)
BetaMCPToolsetParam -- MCP (Model Context Protocol) toolset

Usage

Use BetaToolUnionParam as the type annotation for tool lists when constructing beta API requests. The tools parameter accepts a list of BetaToolUnionParam items, allowing you to mix custom tools with built-in tools in a single request.

Code Reference

Source Location

Repository: Anthropic SDK Python
File: src/anthropic/types/beta/beta_tool_union_param.py

Signature

BetaToolUnionParam: TypeAlias = Union[
    BetaToolParam,
    BetaToolBash20241022Param,
    BetaToolBash20250124Param,
    BetaCodeExecutionTool20250522Param,
    BetaCodeExecutionTool20250825Param,
    BetaToolComputerUse20241022Param,
    BetaMemoryTool20250818Param,
    BetaToolComputerUse20250124Param,
    BetaToolTextEditor20241022Param,
    BetaToolComputerUse20251124Param,
    BetaToolTextEditor20250124Param,
    BetaToolTextEditor20250429Param,
    BetaToolTextEditor20250728Param,
    BetaWebSearchTool20250305Param,
    BetaWebFetchTool20250910Param,
    BetaToolSearchToolBm25_20251119Param,
    BetaToolSearchToolRegex20251119Param,
    BetaMCPToolsetParam,
]

Import

from anthropic.types.beta import BetaToolUnionParam

I/O Contract

BetaToolUnionParam is a pure type alias for request construction. Each variant is a TypedDict distinguished by its type field.

Variant Type	`type` Value	Category
`BetaToolParam`	`"custom"` or `None`	Custom tool
`BetaToolBash20241022Param`	`"bash_20241022"`	Built-in: Bash
`BetaToolBash20250124Param`	`"bash_20250124"`	Built-in: Bash
`BetaCodeExecutionTool20250522Param`	`"code_execution_20250522"`	Built-in: Code execution
`BetaCodeExecutionTool20250825Param`	`"code_execution_20250825"`	Built-in: Code execution
`BetaToolComputerUse20241022Param`	`"computer_20241022"`	Built-in: Computer use
`BetaToolComputerUse20250124Param`	`"computer_20250124"`	Built-in: Computer use
`BetaToolComputerUse20251124Param`	`"computer_20251124"`	Built-in: Computer use
`BetaMemoryTool20250818Param`	`"memory_20250818"`	Built-in: Memory
`BetaToolTextEditor20241022Param`	`"text_editor_20241022"`	Built-in: Text editor
`BetaToolTextEditor20250124Param`	`"text_editor_20250124"`	Built-in: Text editor
`BetaToolTextEditor20250429Param`	`"text_editor_20250429"`	Built-in: Text editor
`BetaToolTextEditor20250728Param`	`"text_editor_20250728"`	Built-in: Text editor
`BetaWebSearchTool20250305Param`	`"web_search_20250305"`	Built-in: Web search
`BetaWebFetchTool20250910Param`	`"web_fetch_20250910"`	Built-in: Web fetch
`BetaToolSearchToolBm25_20251119Param`	`"tool_search_bm25_20251119"`	Built-in: Tool search
`BetaToolSearchToolRegex20251119Param`	`"tool_search_regex_20251119"`	Built-in: Tool search
`BetaMCPToolsetParam`	`"mcp"`	MCP toolset

Usage Examples

Mixing Custom and Built-In Tools

from anthropic.types.beta import BetaToolUnionParam

tools: list[BetaToolUnionParam] = [
    # Custom tool
    {
        "name": "get_weather",
        "description": "Get weather for a location.",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"],
        },
    },
    # Built-in computer use tool
    {
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1920,
        "display_height_px": 1080,
        "enable_zoom": True,
    },
    # Built-in web search tool
    {
        "type": "web_search_20250305",
        "name": "web_search",
    },
]

Passing Tools to the API

import anthropic

client = anthropic.Anthropic()

message = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    tools=[
        {
            "name": "calculator",
            "description": "Perform arithmetic calculations.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string"},
                },
                "required": ["expression"],
            },
        },
        {
            "type": "bash_20250124",
            "name": "bash",
        },
    ],
    messages=[{"role": "user", "content": "What is 2^100? Use the calculator tool."}],
    betas=["beta-feature-flag"],
)

Related Pages

Anthropics_Anthropic_sdk_python_BetaToolParam -- The custom tool definition type (most common variant)
Anthropics_Anthropic_sdk_python_BetaToolComputerUse_20241022 -- Computer use tool (Oct 2024)
Anthropics_Anthropic_sdk_python_BetaToolComputerUse_20250124 -- Computer use tool (Jan 2025)
Anthropics_Anthropic_sdk_python_BetaToolComputerUse_20251124 -- Computer use tool (Nov 2025)
Anthropics_Anthropic_sdk_python_BetaMessage -- The response model that carries tool use results
Anthropics_Anthropic_sdk_python_Messages_Create_With_Tools -- API method for creating messages with tools

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment