Implementation:Anthropics Anthropic sdk python BetaToolParam

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

Overview

BetaToolParam is a TypedDict that defines the parameter structure for a custom tool definition in the beta API. It specifies the tool's name, input schema, description, and various configuration options for how the tool is presented to and used by the model.

Description

BetaToolParam is the core tool definition type used to register custom tools with the beta Messages API. It defines a tool that the model can invoke by specifying:

• name -- The tool's identifier, used in tool_use blocks
• input_schema -- A JSON Schema defining the shape of the tool's expected input
• description -- A natural language description that helps the model understand when and how to use the tool

The file also defines a helper type InputSchema which is a union of InputSchemaTyped (a structured TypedDict with type, properties, and required) and a freeform Dict[str, object] for maximum flexibility.

Additional configuration options include:

• cache_control -- For prompt caching breakpoints
• defer_loading -- For lazy tool loading via tool search
• eager_input_streaming -- For incremental streaming of tool inputs
• strict -- For guaranteed schema validation on tool names and inputs
• allowed_callers -- To restrict which execution contexts can invoke the tool
• type -- Optional, can be "custom" or None

Usage

Use BetaToolParam when defining custom tools for the beta API. This is the most common tool definition type and covers any tool where you provide your own implementation. For built-in tools (computer use, bash, text editor, web search, etc.), use their specific versioned param types instead.

Code Reference

Source Location

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

Signature

class InputSchemaTyped(TypedDict, total=False):
    type: Required[Literal["object"]]
    properties: Optional[Dict[str, object]]
    required: Optional[SequenceNotStr[str]]

InputSchema: TypeAlias = Union[InputSchemaTyped, Dict[str, object]]


class BetaToolParam(TypedDict, total=False):
    input_schema: Required[InputSchema]
    name: Required[str]
    allowed_callers: List[Literal["direct", "code_execution_20250825"]]
    cache_control: Optional[BetaCacheControlEphemeralParam]
    defer_loading: bool
    description: str
    eager_input_streaming: Optional[bool]
    input_examples: Iterable[Dict[str, object]]
    strict: bool
    type: Optional[Literal["custom"]]

Import

from anthropic.types.beta import BetaToolParam

I/O Contract

BetaToolParam Fields

Field	Type	Required	Description
input_schema	InputSchema	Yes	JSON Schema defining the tool's input shape
name	str	Yes	Tool name used by the model in tool_use blocks
allowed_callers	List[Literal["direct", "code_execution_20250825"]]	No	Which callers may invoke this tool
cache_control	Optional[BetaCacheControlEphemeralParam]	No	Cache control breakpoint for this tool definition
defer_loading	bool	No	If true, tool is excluded from initial system prompt
description	str	No	Natural language description of the tool's purpose
eager_input_streaming	Optional[bool]	No	Enable incremental streaming of tool input parameters
input_examples	Iterable[Dict[str, object]]	No	Example inputs for the tool
strict	bool	No	When true, guarantees schema validation on tool names and inputs
type	Optional[Literal["custom"]]	No	Tool type; "custom" or None

InputSchema Structure

Field	Type	Required	Description
type	Literal["object"]	Yes	Always "object" per JSON Schema conventions
properties	Optional[Dict[str, object]]	No	Map of property names to their JSON Schema definitions
required	Optional[SequenceNotStr[str]]	No	List of required property names

Usage Examples

Simple Tool Definition

from anthropic.types.beta import BetaToolParam

tool: BetaToolParam = {
    "name": "get_weather",
    "description": "Get the current weather for a given location.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and state, e.g. 'San Francisco, CA'",
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit",
            },
        },
        "required": ["location"],
    },
}

Tool With Cache Control and Strict Validation

from anthropic.types.beta import BetaToolParam

tool: BetaToolParam = {
    "name": "search_database",
    "description": "Search a database for records matching a query.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "limit": {"type": "integer", "default": 10},
        },
        "required": ["query"],
    },
    "cache_control": {"type": "ephemeral"},
    "strict": True,
}

Tool With Eager Input Streaming

from anthropic.types.beta import BetaToolParam

tool: BetaToolParam = {
    "name": "write_file",
    "description": "Write content to a file. Supports streaming input.",
    "input_schema": {
        "type": "object",
        "properties": {
            "path": {"type": "string"},
            "content": {"type": "string"},
        },
        "required": ["path", "content"],
    },
    "eager_input_streaming": True,
}

Related Pages

• Anthropics_Anthropic_sdk_python_BetaToolUnionParam -- The union type that includes BetaToolParam and all built-in tool types
• 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