Implementation:Anthropics Anthropic sdk python WebSearchTool 20250305

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

Overview

WebSearchTool20250305Param is a TypedDict that defines the configuration parameters for the stable (non-beta) web search server tool. This tool enables Claude to perform web searches during a conversation, retrieving relevant results to provide up-to-date information in responses.

Description

The WebSearchTool20250305Param class is a typed dictionary for configuring the web_search server tool in stable API requests. It requires two fields: name (always "web_search") and type (always "web_search_20250305").

Domain filtering is available through mutually exclusive fields:

• allowed_domains -- If provided, only these domains appear in results. Cannot be used with blocked_domains.
• blocked_domains -- If provided, these domains never appear in results. Cannot be used with allowed_domains.

The file also defines a nested UserLocation TypedDict for providing approximate geographic location to improve search relevance. It accepts:

• type (required, always "approximate")
• city, country (ISO 3166-1 alpha-2), region, timezone (IANA format) -- all optional.

Additional options include:

• cache_control -- Sets a cache control breakpoint via CacheControlEphemeralParam.
• max_uses -- Limits how many times the tool can be invoked per request.
• strict -- Enables schema validation on tool names and inputs.

Compared to the beta version (BetaWebSearchTool20250305Param), this stable version does not include allowed_callers or defer_loading fields.

Usage

Use WebSearchTool20250305Param when you want to give Claude the ability to search the web in a stable (non-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 or filtering search results by domain.
• Localizing search results using the user_location parameter.

Code Reference

Source Location

• Repository: Anthropic SDK Python
• File: src/anthropic/types/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 WebSearchTool20250305Param(TypedDict, total=False):
    name: Required[Literal["web_search"]]
    type: Required[Literal["web_search_20250305"]]
    allowed_domains: Optional[SequenceNotStr[str]]
    blocked_domains: Optional[SequenceNotStr[str]]
    cache_control: Optional[CacheControlEphemeralParam]
    max_uses: Optional[int]
    strict: bool
    user_location: Optional[UserLocation]

Import

from anthropic.types import WebSearchTool20250305Param

I/O Contract

WebSearchTool20250305Param 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_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[CacheControlEphemeralParam]	No	Cache control breakpoint configuration.
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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What are the top news stories today?"}],
    tools=[
        {
            "name": "web_search",
            "type": "web_search_20250305",
            "blocked_domains": ["example-spam.com"],
            "user_location": {
                "type": "approximate",
                "country": "GB",
                "city": "London",
                "timezone": "Europe/London",
            },
            "max_uses": 3,
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Related Pages

• BetaWebSearchTool_20250305 -- Beta version of the web search tool with additional fields like allowed_callers and defer_loading.
• MessageCountTokensParams -- Token counting parameters that accept web search tools.