Tool Bridge
Keep the tool list the model sees fixed while the tools behind it are many or change during a run, so the tool definitions at the head of the prompt stay cached on every provider. Use it for large or dynamic tool populations, such as several MCP servers, on providers that have no cache-safe way to reveal a tool mid-run.
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
from pydantic_ai import Agent
from pydantic_ai_harness import ToolBridge
agent = Agent('anthropic:claude-opus-5-5', capabilities=[ToolBridge()])
ToolBridge replaces the agent’s tools with three tools whose definitions don’t depend on the tools behind them:
| Tool | Arguments | Returns |
|---|---|---|
tool_search | queries (a list of strings) | The name and description of each matching tool, at most max_results |
tool_describe | name | The tool’s name, description and parameters_json_schema |
tool_call | name, args_json | The tool’s result |
tool_call takes the arguments as a JSON object string rather than a nested object, because some models send nested free-form objects as null. An empty string is read as {}. tool_call has the tool kind TOOL_CALL_KIND (tool_bridge.tool_call), exported from pydantic_ai_harness.tool_bridge, so an approval UI or another capability can recognize it whatever it is named.
A tool added, removed or changed mid-run changes what tool_search finds, not the tool definitions sent to the provider. A tool reached through the bridge is validated and run through the same path as a direct call, under the tool_call call’s ID: argument validation, tool hooks, ModelRetry and usage limits apply to it as to any tool (approval works differently, see What stays native), and an unknown name or invalid arguments ask the model to retry. Both tool_call and the bridged tool count as tool calls, and tool_calls_limit is checked for both before the bridged tool runs. A bridged tool’s retries are counted under its own name, as for a direct call, so its ctx.retry and max_retries see only its own failures; each one also spends a retry of tool_call. If any bridged tool is sequential, so is tool_call.
tools(default'all'): which tools to bridge, as a list of names, a metadata dict such as{'bridge': True}(matching the tools whose metadata contains those entries, for example tools tagged bySetToolMetadata; like a list of names, it survives spec serialization), or a(ctx, tool_def) -> boolcallable, sync or async. The rest stay visible to the model as normal tools.search: ranks the bridged tools fortool_search’s queries, with the signature of aToolSearchFunc.None(default) ranks tools by how many of the queries’ words appear in their name or description.max_results(default10): the most tools onetool_searchreturns.max_retries(defaultNone, the agent’s tool retry budget, asAgent(retries={'tools': N})sets it): retries for each dispatcher tool, spent on unknown tool names, invalid arguments and retries the bridged tools ask for.
These tools are never bridged, so they reach the model as usual:
- Tools that need approval or run outside the agent (
requires_approval=True, external tools), so approval requests name the real tool. A bridged tool that raisesApprovalRequiredorCallDeferreditself can be resolved by aHandleDeferredToolCallshandler, which sees the tool’s own name; a denial is recorded as thetool_callcall’s denied outcome. Without a handler that resolves it, the run fails with aUserErrorrather than deferringtool_call, whose approval would cover whichever tool the model named. Keep such a tool native withtools, for example the tools of a toolset wrapped withapproval_required(), if it needs approval from outside the run. - Tools with a
tool_kind, such as tool search,load_capabilityandFileSystem’sread_file, which the run and other capabilities find by kind (ToolOutputLimits,Memoryand compaction among them), and tools that step aside for one withunless_tool_kind, so the run leaves out the same tools it would without the bridge. - Code-execution tools, such as Code Mode’s
run_codeand Shell’srun_command, which take a program as a string argument, so it isn’t sent JSON-escaped insideargs_json. - Local fallbacks for a provider-native tool (
unless_native), so the model can drop them when the provider runs the tool natively.
Tools with defer_loading=True are bridged and found with tool_search, so ToolSearch has nothing left to reveal. Deferred tools that a capability owns, such as the tools of a capability with defer_loading=True, stay native, so core’s tool search and load_capability reveal them as usual. The tool names tool_search, tool_describe and tool_call are reserved: an agent tool with one of them raises a UserError.
- Each bridged call takes an extra step: the model searches or describes a tool before it calls it, unless it already knows the name and arguments.
- The provider doesn’t validate a bridged tool’s arguments against its schema, so strict tool calling doesn’t apply to them; Pydantic AI still validates them before the tool runs.
- A bridged tool’s description and schema reach the model in tool results instead of the tool definitions.
Two ToolBridge capabilities on one agent merge into one; the later one’s settings win. One bridge per agent is supported: given distinct ids, the outer bridge refuses the inner one’s reserved tool names with a UserError. The bridge sits just inside tool search and outside every other capability that wraps the toolset, whatever order the capabilities are listed in, so wrappers such as SetToolMetadata and PrefixTools apply to the bridged tools. With CodeMode too, Code Mode exposes the three dispatchers as sandbox functions rather than the bridged tools; use Code Mode alone to put many tools behind run_code.
ToolBridge adds no spans of its own. With instrumentation on, tool_call and the bridged tool it runs each get a tool span, since the bridged call goes through the same tool hooks.
Bases: AbstractCapability[AgentDepsT]
Capability that puts the agent’s tools behind tool_search, tool_describe and tool_call.
The model sees only those three tools, whose definitions never change, so the tool definitions
at the head of the prompt stay cached however many tools sit behind them and however they change
mid-run. The model finds a tool with tool_search, reads its argument schema with
tool_describe, and runs it with tool_call, passing the arguments as a JSON string.
from pydantic_ai import Agent
from pydantic_ai_harness import ToolBridge
agent = Agent('openai:gpt-5', capabilities=[ToolBridge()])
Which tools to bridge; the rest stay visible to the model as normal tools.
'all'(default): every eligible tool.Sequence[str]: the tools with these names.dict[str, Any]: the tools whose metadata contains these entries, such as thoseSetToolMetadatatags.- Callable
(ctx, tool_def) -> bool | Awaitable[bool]: the tools it returnsTruefor.
Type: ToolSelector[AgentDepsT] Default: 'all'
Ranks the bridged tools for tool_search’s queries: (ctx, queries, tools) -> names, sync or async.
None (default) ranks tools by how many of the queries’ words appear in their name or description.
Type: ToolSearchFunc[AgentDepsT] | None Default: None
Maximum number of tool_search results.
Type: int Default: 10
Retries for each dispatcher tool, spent on unknown tool names, invalid arguments and bridged tools’ retries.
None (default) uses the agent’s tool retry budget, as Agent(retries={'tools': N}) sets it.
Type: int | None Default: None
An agent has one bridge, so two of them merge into one.
Two with distinct ids aren’t supported: the outer one refuses the inner one’s reserved tool names.
Type: str | None Default: 'tool_bridge'
def get_ordering() -> CapabilityOrdering
Sit just inside ToolSearch and outside every other wrapper.
Wrappers such as SetToolMetadata and PrefixTools then see the bridged tools whatever order the
capabilities are listed in.
CapabilityOrdering
def get_wrapper_toolset(
toolset: AbstractToolset[AgentDepsT],
) -> AbstractToolset[AgentDepsT]
Wrap the agent’s tools in the bridge.
AbstractToolset[AgentDepsT]
The kind of ToolBridge’s tool_call tool, so an approval UI or capability can tell it apart whatever it is named.
Default: ToolKind('tool_bridge', CALL_TOOL_NAME, args=ToolCallArgs)
Bases: TypedDict
Arguments of the tool_call dispatcher.
The bridged tool to call.
Type: str
The bridged tool’s arguments, as a JSON object string.
Type: str