[Platform][Anthropic] Support server-side tools via server_tools option

[soyuka]

Q	A
Bug fix?	no
New feature?	yes
Docs?	no
Issues	-
License	MIT

Adds a server_tools option to the Anthropic ModelClient. Server-side (Anthropic-hosted) tools such as web_search are fully-formed Anthropic tool specs that must be passed through verbatim rather than mapped from a name. Each entry is appended to the request tools array, so the bridge stays forward-compatible with any future server tool without a name-to-type mapping.

Merging happens before the existing cache-control block, so server tools join the cached tools prefix and are covered by tool_choice: auto.

$platform->invoke('claude-sonnet-4', $messages, [
    'server_tools' => [
        ['type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 3],
    ],
]);

The transport-only server_tools key is stripped before the request body is sent. Tests cover appending with and without function tools, cache-control placement on the last tool, and key removal.

[chr-hertel]

Hey @soyuka, thanks for that - let's use to sort the situation a bit - thinking out loud here:

• with [Platform][Anthropic] Return MultiPartResult for multi-part responses #1937 we brought in an example and docs for folding those server tools for anthropic into the existing tools option - what you under the hood do here as well
• with Gemini/Vertex Server Tools we use the server_tools option

on the one hand i feel like adopting server_tools feels more consistent and i bet every dev also differentiates between local and server tools - but on the other hand, if it ends up in the same option - a bit weird 🤔

i think i would appreciate to streamline docs for promoting server_tools - we don't need to block the usage via tools

cc @valtzu

[soyuka]

I can document that if needed lmk.

[valtzu]

It would be nice to have some abstraction so that the same would work for any platform that supports the feature. Then it would be very similar to capabilities, or maybe we could even use capabilities?

E.g. a model would have Capability::WebSearchServerTool

Then you'd have

ai:
  platform:
    antropic:
      # ..
      server_tools:
        web_search: true
    gemini:
      # ..
      server_tools:
        web_search: true
    failover:
      anthropic_to_gemini:
        platforms:
          - 'ai.platform.anthorpic'
          - 'ai.platform.gemini'

and then do the routing & constructing the request instead of current pass-through as-is.

For simple things like web search and code execution having the platform-specific config in yaml is not an issue, but some server tools take input (e.g. location-based ones) so for those its usually not feasible to have them within platform config, and by putting them into code you make the code platform-specific, which may be unacceptable in failover setups.

And of course it must still be possible to define platform-specific tools (in a pass-thru manner), not to handcuff people from using the latest features that have not yet landed on symfony/ai.

---

I understand this may be a stretch.