Tool Search
The ToolSearch capability handles model-driven discovery of searchable tools marked with defer_loading=True, so agents with large toolsets only pay tokens for the tools the model needs. Like the provider-adaptive tools above, it picks the best path for the active model — native server-executed search on Anthropic and OpenAI Responses, a local search_tools function tool elsewhere — and is auto-injected into every agent when searchable deferred tools exist. Bundle-level disclosure is covered by on-demand capabilities.
Pass an explicit ToolSearch to pick a specific strategy ('keywords', 'bm25', 'regex', or a custom callable) or tune the local fallback:
from pydantic_ai import Agent
from pydantic_ai.capabilities import ToolSearch
agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[ToolSearch(strategy='keywords')])
When the local search_tools function tool is used, its retry budget follows the agent’s tool budget — so Agent(retries={'tools': N}) gives the model N attempts to correct a malformed queries argument, on the same precedence ladder as any other tool. A search that finds no matches returns normally and never spends a retry.
See Tool Search for when to reach for it, the full strategy table, and provider support details.