Use provider tools

Attach built-in, vendor-specific tools from OpenAI, Anthropic, Google, and Amazon Bedrock to a Phoenix prompt, and use the prompt from the Phoenix client.

Attach a provider tool to a Phoenix prompt so that the model can use a capability that the provider hosts, for example web search, file search, code execution, grounding, or computer use.

A provider tool (also called a vendor-specific or raw tool) is an opaque JSON payload. Phoenix sends it to the provider without changes. A function tool is a normalized, portable definition that works with all providers. For the difference, see Tools in the concepts guide.

This page tells you when to use a provider tool and how to add one in the Playground. It also gives the JSON shape for each supported provider.

​

Supported provider tools

Provider	Tools	Jump to
Anthropic	web_search, web_fetch, code_execution, tool_search_tool, bash, text_editor, computer, memory	Built-in tools
OpenAI Responses API	web_search, file_search, code_interpreter, computer, tool_search	Built-in tools
Google Gemini	google_search	Google Search grounding
Amazon Bedrock	nova_grounding	Nova web grounding

​

When to use a provider tool

Use a provider tool in these conditions:

• You need a built-in capability that the provider hosts, for example search, retrieval, code execution, or computer control.
• You have a production span that uses a vendor tool, and you want Phoenix to round-trip the exact payload into the Playground.
• You accept that the prompt version works with one provider only. The JSON shape is specific to the provider. Thus Phoenix removes provider tools automatically when you change the provider or API type.

If your tool is a generic function call that all providers can execute, use a function tool. A function tool stays when you change the provider, and it is portable across SDKs.

​

Adding a provider tool in the Playground

If you change the provider or API type on a prompt version, Phoenix removes all provider tools from it. The JSON is specific to one provider. Function tools stay. If you need the prompt for more than one provider, save one prompt version for each provider.

1. Open the Playground and select a model that supports the tool: Anthropic Claude, an OpenAI Responses-compatible model, Gemini, or Amazon Nova.
2. Click Add tool to open the JSON editor.
3. Paste the provider tool payload from the applicable provider section below.
4. Save the tool.
5. Save the prompt version.

When you save the tool, Phoenix examines the JSON. If the JSON matches the function-tool shape, Phoenix stores it as a function tool. If not, Phoenix stores it as a raw provider tool. Phoenix round-trips a raw provider tool without changes through the database, the GraphQL API, and the SDKs. One prompt can have both function tools and provider tools.

“Open in Playground” on a captured trace keeps provider tools exactly as Phoenix sent them to the model. Use it to replay a production call and change it.

​

Anthropic — built-in tools

Source of truth: the Anthropic tool reference and the tool pages linked below. The JSON shapes on this page are the same as in those docs. When Anthropic releases a new version, copy the exact payload from the Anthropic page.

The Anthropic Messages API has hosted (server-executed) tools and client-executed tools. Phoenix sends each tool as opaque JSON. To attach an Anthropic tool to a prompt, paste its definition into the Playground. This works for current and future Anthropic tools. For the full list and the type-string versioning rules, see the Anthropic tool reference.

Server tools (Anthropic executes them):

• web_search_20250305 / web_search_20260209: live web results with citations. The newer version adds dynamic filtering. Docs.
• web_fetch_20250910 / web_fetch_20260209: gets a specific URL and returns its content. Docs.
• code_execution_20250825 / code_execution_20260120: sandboxed Python and Bash with file operations. The newer version supports programmatic tool calling. Docs.
• tool_search_tool_regex_20251119 / tool_search_tool_bm25_20251119: defers tool loading. Claude finds tools from a larger catalog at runtime. This is the Anthropic equivalent of OpenAI tool_search. Docs.

Client tools (Anthropic defines the schema, and your application executes the call):

• bash_20250124: shell command execution. Docs.
• text_editor_20250124 / text_editor_20250728: file editing. Select the version that matches your model generation. Docs.
• computer_20250124 / computer_20251124: screen control through screenshots and actions. Requires a beta header. Docs.
• memory_20250818: persistent memory store for long-running agents. Docs.

Example: web search. Optional fields are max_uses, allowed_domains, blocked_domains, and user_location.

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}

To add the bash client tool, paste its definition into the Playground tool editor:

{
  "type": "bash_20250124",
  "name": "bash"
}

Editing an Anthropic bash tool in the Phoenix Playground.

The Anthropic tool_search_tool_* uses the defer_loading: true flag on individual tool definitions, as OpenAI tool_search does. For prompt-cache interactions, see the Anthropic tool search guide.

​

OpenAI Responses API — built-in tools

Source of truth: the OpenAI tools guide and the tool pages linked below. Phoenix only round-trips the JSON. For current fields and model support, refer to the OpenAI docs.

The OpenAI Responses API has hosted tools. The model invokes them without a return trip to your code. To add a hosted tool, put a single-key JSON object in the tools array.

• web_search: internet search with citations. Docs.
• file_search: semantic and keyword retrieval over files in a vector store. Docs.
• code_interpreter: sandboxed Python execution for analysis, charts, and math. Docs.
• computer: UI control through screenshots and actions. Docs.
• tool_search: defers tool loading. The model searches a larger catalog at runtime. Docs.

Example payload with two hosted tools:

[
  { "type": "web_search" },
  {
    "type": "file_search",
    "vector_store_ids": ["vs_abc123"]
  }
]

For the full list of hosted tools, see the OpenAI tools guide.

​

Deferred tool search

Use tool_search to attach a large catalog of function tools to a prompt. You do not pay for all of their schemas on each request. Mark each tool to hold back with "defer_loading": true. The model then sends a tool_search call to load only the applicable tools into context. It adds the loaded tools at the end, so the prefix cache stays valid. tool_search is available on gpt-5.4 and later Responses-capable models.

Select one of the two execution modes:

• Hosted (default): OpenAI matches deferred tools on the server and returns the loaded tools automatically. Add the tool with no other fields:

{ "type": "tool_search" }

• Client: the model sends a tool_search_call, and your application returns a tool_search_output with the matching tools. Use this mode if your tool catalog is outside OpenAI, for example in an internal registry or an MCP server:

{
  "type": "tool_search",
  "execution": "client",
  "description": "Find project-specific tools needed to continue the task.",
  "parameters": {
    "type": "object",
    "properties": {
      "goal": { "type": "string" }
    },
    "required": ["goal"],
    "additionalProperties": false
  }
}

To use deferred loading for a function tool, set defer_loading on its definition. Phoenix keeps the field without changes when it round-trips the prompt:

{
  "type": "function",
  "name": "get_invoice",
  "description": "Look up an invoice by ID.",
  "defer_loading": true,
  "parameters": {
    "type": "object",
    "properties": { "invoice_id": { "type": "string" } },
    "required": ["invoice_id"]
  }
}

For the largest token savings, put deferred tools into namespaces or serve them from MCP servers. When a search result is in a namespace, OpenAI loads all the tools in that namespace.

​

Google Gemini — Google Search grounding

Source of truth: the Google Grounding with Google Search page. Phoenix sends the tool block without changes.

With Gemini Grounding with Google Search, the model grounds responses in live search results and returns groundingMetadata with citations. Use the google_search tool on current Gemini models. Use the legacy google_search_retrieval only for older Gemini 1.x models.

{
  "google_search": {}
}

The same tool is available on Vertex AI. See Grounding with Google Search on Vertex AI.

​

Amazon Bedrock — Nova web grounding

Source of truth: the AWS Nova Web Grounding page. Bedrock requires the systemTool wrapper. Phoenix does not add or remove it.

Amazon Nova has Web Grounding, a built-in tool that gets cited public sources. Put it in a systemTool wrapper, not in the usual toolSpec.

Do not add nova_grounding as a toolSpec entry. If you do, Bedrock returns an error. Phoenix keeps your JSON exactly as you write it, so the systemTool wrapper below is required.

{
  "systemTool": {
    "name": "nova_grounding"
  }
}

Editing a Nova grounding tool in the Phoenix Playground.

Nova web grounding is available on the Amazon Nova model family in us-east-1, us-east-2, and us-west-2. For capabilities and billing, see the AWS announcement.

​

Pulling and using a prompt with provider tools

The Phoenix client libraries send provider tools to the target SDK without changes.

1. Pull the prompt as usual.
2. Send the formatted parameters to the provider client.

For the full pull-and-format procedure, see Use a prompt.

Python

from openai import OpenAI
from phoenix.client import Client

client = Client()
prompt = client.prompts.get(prompt_identifier="research-assistant", tag="staging")
formatted_prompt = prompt.format(variables={"question": "What's new in LLM evals?"})

# Provider tools (e.g. {"type": "web_search"}) are forwarded as-is.
oai = OpenAI()
response = oai.responses.create(**formatted_prompt)

TypeScript

import { getPrompt, toSDK } from "@arizeai/phoenix-client/prompts";
import OpenAI from "openai";

const openai = new OpenAI();
const prompt = await getPrompt({
  prompt: { name: "research-assistant", tag: "staging" },
});

const params = toSDK({
  sdk: "openai",
  prompt,
  variables: { question: "What's new in LLM evals?" },
});

// Provider tools round-trip through toSDK without modification.
const response = await openai.responses.create(params);

​

Limitations

• Phoenix removes provider tools when you change the provider or API type on a prompt version. Phoenix keeps function tools.
• You cannot use provider tools on evaluator prompts. Evaluators use the normalized function-tool output schema.
• Phoenix only checks that the payload is a non-empty JSON object. The provider checks semantic validity, for example model support, regional availability, and required fields.