Implementation:Anthropics Anthropic sdk python BetaWebSearchTool 20250305

Knowledge Sources	Anthropic SDK Python
Domains	API Types, Beta, Tools
Last Updated	2026-02-15 12:00 GMT

Overview

BetaWebSearchTool20250305Param is a TypedDict that defines the configuration parameters for the beta web search server tool. This tool enables Claude to perform web searches during a conversation, returning relevant results that the model can use to answer queries with up-to-date information.

Description

The BetaWebSearchTool20250305Param class is a typed dictionary for configuring the web_search server tool in beta API requests. It has two required fields: name (always "web_search") and type (always "web_search_20250305"). Domain filtering is available through mutually exclusive allowed_domains and blocked_domains fields.

The file also defines a nested UserLocation TypedDict that provides approximate geographic location data to improve search result relevance. UserLocation accepts city, country (ISO 3166-1 alpha-2), region, and timezone (IANA format) fields, all optional except for the required type field (always "approximate").

Additional configuration options:

• allowed_callers -- Restricts which callers may invoke the tool.
• cache_control -- Sets a cache control breakpoint.
• defer_loading -- Excludes tool from the initial system prompt.
• max_uses -- Limits how many times the tool can be invoked per request.
• strict -- Enables schema validation on tool names and inputs.

Usage

Use BetaWebSearchTool20250305Param when you want to give Claude the ability to search the web in a beta API request. Include it in the tools list when creating messages. This is useful for:

• Providing Claude with access to current information beyond its training data.
• Restricting search results to specific domains or blocking unwanted domains.
• Localizing search results using the user_location parameter.

Code Reference

Source Location

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

Signature

class UserLocation(TypedDict, total=False):
    type: Required[Literal["approximate"]]
    city: Optional[str]
    country: Optional[str]
    region: Optional[str]
    timezone: Optional[str]


class BetaWebSearchTool20250305Param(TypedDict, total=False):
    name: Required[Literal["web_search"]]
    type: Required[Literal["web_search_20250305"]]
    allowed_callers: List[Literal["direct", "code_execution_20250825"]]
    allowed_domains: Optional[SequenceNotStr[str]]
    blocked_domains: Optional[SequenceNotStr[str]]
    cache_control: Optional[BetaCacheControlEphemeralParam]
    defer_loading: bool
    max_uses: Optional[int]
    strict: bool
    user_location: Optional[UserLocation]

Import

from anthropic.types.beta import BetaWebSearchTool20250305Param

I/O Contract

BetaWebSearchTool20250305Param Fields

Field	Type	Required	Description
name	Literal["web_search"]	Yes	Name of the tool. Always "web_search".
type	Literal["web_search_20250305"]	Yes	Tool type identifier.
allowed_callers	List[Literal["direct", "code_execution_20250825"]]	No	Which callers may invoke this tool.
allowed_domains	Optional[SequenceNotStr[str]]	No	Domains to include in results. Cannot be used with blocked_domains.
blocked_domains	Optional[SequenceNotStr[str]]	No	Domains to exclude from results. Cannot be used with allowed_domains.
cache_control	Optional[BetaCacheControlEphemeralParam]	No	Cache control breakpoint configuration.
defer_loading	bool	No	If true, tool is not included in the initial system prompt.
max_uses	Optional[int]	No	Maximum number of times the tool can be used in the request.
strict	bool	No	When true, guarantees schema validation on tool names and inputs.
user_location	Optional[UserLocation]	No	Approximate user location for search result relevance.

UserLocation Fields

Field	Type	Required	Description
type	Literal["approximate"]	Yes	Location type. Always "approximate".
city	Optional[str]	No	The city of the user.
country	Optional[str]	No	ISO 3166-1 alpha-2 country code.
region	Optional[str]	No	The region of the user.
timezone	Optional[str]	No	IANA timezone of the user.

Usage Examples

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What are the latest AI research papers?"}],
    tools=[
        {
            "name": "web_search",
            "type": "web_search_20250305",
            "allowed_domains": ["arxiv.org", "scholar.google.com"],
            "user_location": {
                "type": "approximate",
                "country": "US",
                "timezone": "America/New_York",
            },
            "max_uses": 5,
        }
    ],
    betas=["web-search-2025-03-05"],
)

Related Pages

• WebSearchTool_20250305 -- Stable (non-beta) version of the web search tool configuration.
• BetaWebFetchTool_20250910 -- Beta web fetch tool for retrieving specific URLs.
• Beta MessageCountTokensParams -- Beta token counting parameters that accept this tool in the tools list.