feat: add provider-agnostic tool_web_search() and tool_web_fetch()

Add built-in web search and URL fetch tools that work across providers:

- tool_web_search(): Works with OpenAI, Anthropic, and Google
- tool_web_fetch(): Works with Anthropic and Google

Each provider automatically translates the tool configuration to its
specific API format. Supports options like allowed_domains, blocked_domains,
user_location, and max_uses where applicable.

This is equivalent to tidyverse/ellmer#829 but with a cleaner provider-agnostic
API (one function instead of separate functions per provider).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: cpsievert

CLAUDE.md

@@ -49,6 +49,14 @@ The project uses `uv` for package management and Make for common tasks:
 4. **Content-Based Messaging**: All communication uses structured `Content` objects rather than raw strings
 5. **Tool Integration**: Seamless function calling with automatic JSON schema generation from Python type hints
 
+### Typing Best Practices
+
+This project prioritizes strong typing that leverages provider SDK types directly:
+
+- **Use provider SDK types**: Import and use types from `openai.types`, `anthropic.types`, `google.genai.types`, etc. rather than creating custom TypedDicts or dataclasses that mirror them. This ensures compatibility with SDK updates and provides better IDE support.
+- **Use `@overload` for provider-specific returns**: When a method returns different types based on a provider argument, use `@overload` with `Literal` types to give callers precise return type information.
+- **Explore SDK types interactively**: Use `python -c "from <sdk>.types import <Type>; print(<Type>.__annotations__)"` to inspect available fields and nested types when implementing provider-specific features.
+
 ### Testing Structure
 
 - Tests are organized by component (e.g., `test_provider_openai.py`, `test_tools.py`)

chatlas/__init__.py

@@ -35,6 +35,7 @@
 from ._provider_snowflake import ChatSnowflake
 from ._tokens import token_usage
 from ._tools import Tool, ToolBuiltIn, ToolRejectError
+from ._tools_builtin import tool_web_fetch, tool_web_search
 from ._turn import AssistantTurn, SystemTurn, Turn, UserTurn
 
 try:
@@ -86,6 +87,8 @@
     "Tool",
     "ToolBuiltIn",
     "ToolRejectError",
+    "tool_web_fetch",
+    "tool_web_search",
     "Turn",
     "UserTurn",
     "SystemTurn",

chatlas/_provider_anthropic.py

@@ -39,6 +39,7 @@
 )
 from ._tokens import get_price_info
 from ._tools import Tool, ToolBuiltIn, basemodel_to_param_schema
+from ._tools_builtin import ToolWebFetch, ToolWebSearch
 from ._turn import AssistantTurn, SystemTurn, Turn, UserTurn, user_turn
 from ._utils import split_http_client_kwargs
 
@@ -690,6 +691,11 @@ def _as_content_block(content: Content) -> "ContentBlockParam":
 
     @staticmethod
     def _anthropic_tool_schema(tool: "Tool | ToolBuiltIn") -> "ToolUnionParam":
+        if isinstance(tool, ToolWebSearch):
+            return tool.get_definition("anthropic")
+        if isinstance(tool, ToolWebFetch):
+            # TODO: why is this not apart of ToolUnionParam?
+            return tool.get_definition("anthropic")  # type: ignore
         if isinstance(tool, ToolBuiltIn):
             return tool.definition  # type: ignore
 

chatlas/_provider_google.py

@@ -22,6 +22,7 @@
 from ._provider import ModelInfo, Provider, StandardModelParamNames, StandardModelParams
 from ._tokens import get_price_info
 from ._tools import Tool, ToolBuiltIn
+from ._tools_builtin import ToolWebFetch, ToolWebSearch
 from ._turn import AssistantTurn, SystemTurn, Turn, UserTurn, user_turn
 
 if TYPE_CHECKING:
@@ -319,21 +320,36 @@ def _chat_perform_args(
             config.response_mime_type = "application/json"
 
         if tools:
-            config.tools = [
-                GoogleTool(
-                    function_declarations=[
-                        FunctionDeclaration.from_callable(
-                            client=self._client._api_client,
-                            callable=tool.func,
-                        )
-                        for tool in tools.values()
-                        # TODO: to support built-in tools, we may need a way to make
-                        # tool names (e.g., google_search to google.genai.types.GoogleSearch())
-                        if isinstance(tool, Tool)
-                    ]
-                )
+            # Separate regular tools from built-in tools
+            regular_tools = [t for t in tools.values() if isinstance(t, Tool)]
+            builtin_tools = [
+                tool.get_definition("google")
+                for tool in tools.values()
+                if isinstance(tool, (ToolWebSearch, ToolWebFetch))
             ]
 
+            google_tools: list[Any] = []
+
+            # Add regular function tools
+            if regular_tools:
+                google_tools.append(
+                    GoogleTool(
+                        function_declarations=[
+                            FunctionDeclaration.from_callable(
+                                client=self._client._api_client,
+                                callable=tool.func,
+                            )
+                            for tool in regular_tools
+                        ]
+                    )
+                )
+
+            # Add built-in tools
+            google_tools.extend(builtin_tools)
+
+            if google_tools:
+                config.tools = google_tools
+
         kwargs_full["config"] = config
 
         return kwargs_full

chatlas/_provider_openai.py

@@ -25,6 +25,7 @@
 from ._provider_openai_completions import load_tool_request_args
 from ._provider_openai_generic import BatchResult, OpenAIAbstractProvider
 from ._tools import Tool, ToolBuiltIn, basemodel_to_param_schema
+from ._tools_builtin import ToolWebFetch, ToolWebSearch
 from ._turn import AssistantTurn, Turn
 
 if TYPE_CHECKING:
@@ -235,7 +236,16 @@ def _chat_perform_args(
 
         tool_params: list["ToolParam"] = []
         for tool in tools.values():
-            if isinstance(tool, ToolBuiltIn):
+            if isinstance(tool, ToolWebSearch):
+                tool_params.append(tool.get_definition("openai"))
+            elif isinstance(tool, ToolWebFetch):
+                raise ValueError(
+                    "Web fetch is not supported by OpenAI. "
+                    "Use the MCP Fetch server instead via "
+                    "chat.register_mcp_tools_stdio_async(). "
+                    "See help(tool_web_fetch) for details."
+                )
+            elif isinstance(tool, ToolBuiltIn):
                 tool_params.append(cast("ToolParam", tool.definition))
             else:
                 schema = tool.schema