Fix markdown in builtin tools api docs (#2826)

Co-authored-by: Douwe Maan <[email protected]>

Author: samuelcolvin

.gitignore

@@ -20,3 +20,4 @@ node_modules/
 .coverage*
 /test_tmp/
 .mcp.json
+.claude/

docs/builtin-tools.md

@@ -26,25 +26,38 @@ making it ideal for queries that require up-to-date data.
 
 | Provider | Supported | Notes |
 |----------|-----------|-------|
-| OpenAI | ✅ | Full feature support |
+| OpenAI Responses | ✅ | Full feature support |
 | Anthropic | ✅ | Full feature support |
 | Groq | ✅ | Limited parameter support. To use web search capabilities with Groq, you need to use the [compound models](https://console.groq.com/docs/compound). |
 | Google | ✅ | No parameter support. Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| OpenAI Chat Completions | ❌ | Not supported |
 | Bedrock | ❌ | Not supported |
 | Mistral | ❌ | Not supported |
 | Cohere | ❌ | Not supported |
 | HuggingFace | ❌ | Not supported |
 
 ### Usage
 
-```py title="web_search_basic.py"
+```py title="web_search_anthropic.py"
 from pydantic_ai import Agent, WebSearchTool
 
 agent = Agent('anthropic:claude-sonnet-4-0', builtin_tools=[WebSearchTool()])
 
 result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
-# > Scientists have developed a universal AI detector that can identify deepfake videos.
+print(result.output)
+#> Scientists have developed a universal AI detector that can identify deepfake videos.
+```
+
+With OpenAI, you must use their responses API to access the web search tool.
+
+```py title="web_search_openai.py"
+from pydantic_ai import Agent, WebSearchTool
+
+agent = Agent('openai-responses:gpt-4.1', builtin_tools=[WebSearchTool()])
 
+result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
+print(result.output)
+#> Scientists have developed a universal AI detector that can identify deepfake videos.
 ```
 
 ### Configuration Options

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -26,8 +26,9 @@ class WebSearchTool(AbstractBuiltinTool):
     The parameters that PydanticAI passes depend on the model, as some parameters may not be supported by certain models.
 
     Supported by:
+
     * Anthropic
-    * OpenAI
+    * OpenAI Responses
     * Groq
     * Google
     """
@@ -36,15 +37,17 @@ class WebSearchTool(AbstractBuiltinTool):
     """The `search_context_size` parameter controls how much context is retrieved from the web to help the tool formulate a response.
 
     Supported by:
-    * OpenAI
+
+    * OpenAI Responses
     """
 
     user_location: WebSearchUserLocation | None = None
     """The `user_location` parameter allows you to localize search results based on a user's location.
 
     Supported by:
+
     * Anthropic
-    * OpenAI
+    * OpenAI Responses
     """
 
     blocked_domains: list[str] | None = None
@@ -53,8 +56,9 @@ class WebSearchTool(AbstractBuiltinTool):
     With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both.
 
     Supported by:
-    * Anthropic (https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering)
-    * Groq (https://console.groq.com/docs/agentic-tooling#search-settings)
+
+    * Anthropic, see <https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering>
+    * Groq, see <https://console.groq.com/docs/agentic-tooling#search-settings>
     """
 
     allowed_domains: list[str] | None = None
@@ -63,14 +67,16 @@ class WebSearchTool(AbstractBuiltinTool):
     With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both.
 
     Supported by:
-    * Anthropic (https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering)
-    * Groq (https://console.groq.com/docs/agentic-tooling#search-settings)
+
+    * Anthropic, see <https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering>
+    * Groq, see <https://console.groq.com/docs/agentic-tooling#search-settings>
     """
 
     max_uses: int | None = None
     """If provided, the tool will stop searching the web after the given number of uses.
 
     Supported by:
+
     * Anthropic
     """
 
@@ -79,8 +85,9 @@ class WebSearchUserLocation(TypedDict, total=False):
     """Allows you to localize search results based on a user's location.
 
     Supported by:
+
     * Anthropic
-    * OpenAI
+    * OpenAI Responses
     """
 
     city: str
@@ -100,8 +107,9 @@ class CodeExecutionTool(AbstractBuiltinTool):
     """A builtin tool that allows your agent to execute code.
 
     Supported by:
+
     * Anthropic
-    * OpenAI
+    * OpenAI Responses
     * Google
     """
 
@@ -110,5 +118,6 @@ class UrlContextTool(AbstractBuiltinTool):
     """Allows your agent to access contents from URLs.
 
     Supported by:
+
     * Google
     """