Skip to main content
Beta
BetaServer tools are currently in beta. The API and behavior may change.
The openrouter:tool_search server tool lets a model work with a large tool library without paying for it on every request. You mark the tools that should stay hidden with defer_loading, and the model searches for what it needs when it needs it. This matters at scale for two reasons. Tool definitions are charged as input tokens on every turn, so a large library is a fixed cost on every request whether or not the model uses any of it. Tool selection accuracy also degrades as the list grows — a model choosing between several hundred similar tools picks wrong more often than one choosing between five. Tool search works on any model and any provider, not only those with native support for it.

​
Quick Start

Include the tool alongside your own, and mark the ones to withhold:
Request
The model searches for weather, finds get_weather, and calls it on the next turn. You handle that call exactly as you would any other function tool call — deferral changes when a tool becomes available, not how it works once it does.

​
Marking Tools as Deferred

Add defer_loading: true to any tool you want withheld. Deferred tools are hidden by default: the model cannot see or call one until a search returns it. One rule applies, and breaking it fails the request with a 400 rather than quietly ignoring the deferral:
  • openrouter:tool_search itself can never be deferred. It is what reveals the rest of the library, so deferring it would leave nothing able to load anything. This also guarantees at least one tool is always callable.
Using defer_loading without openrouter:tool_search remains valid and is unchanged: those requests route to a provider whose gateway expands deferred tools itself, and your own search tool is an ordinary function tool that provider recognizes. This provider-managed path is only available on Anthropic models and Anthropic-compatible endpoints that implement deferral; other models return a 400. With openrouter:tool_search in the request, deferral is managed by OpenRouter and works on any model and any provider. Keep your three to five most frequently used tools loaded. A tool the model needs on almost every request costs more in search round-trips than it saves in tokens.

​
Searching

The model supplies a regular expression, matched case-insensitively against each deferred tool’s name, description, argument names, and argument descriptions. A pattern of weather finds a tool whose only mention of weather is in a parameter description. Patterns are capped at 200 characters. A malformed pattern, or one that would take pathologically long to evaluate, returns an error result to the model rather than failing the request — the model can simply search again with a simpler pattern. Writing tool descriptions in the words your users actually use makes them far easier to find. Consistent name prefixes help too: naming tools github_issues_list and github_pulls_list lets one search reach the whole group.

​
Controlling Tool Choice

Tool search uses tool_choice to express which tools the model may call on each turn, widening it as tools are discovered. OpenRouter sets this up for you. If your request omits tool_choice, or sets it to the default "auto", nothing is required of you. If you set anything else, it must be {"type": "allowed_tools", ...} naming the tools that should be callable immediately. Deferred tools are added to that set as the model finds them. Any other tool_choice conflicts with deferral — forcing a specific tool, requiring a call, or forbidding calls entirely all contradict “reveal these tools gradually.” Rather than silently overriding what you asked for, the request fails with a 400:
tool_choice conflicts with openrouter:tool_search. Deferred tools are revealed through tool_choice, so it must be omitted or set to {"type": "allowed_tools", ...}. Remove tool_choice, or drop defer_loading from your tools to use it as-is.
The alternative would be worse in both directions: honoring tool_choice would silently disable deferral, and overriding it would silently ignore an explicit instruction. Neither is something you would want to discover from a bill or a wrong answer.

​
Prompt Caching

Discovering a tool does not disturb the tools already in the conversation, so prompt caching is preserved across a search. You can start a conversation with a small loaded set, let the model discover more as it goes, and keep your cache hit across every turn.

​
Supported APIs

Tool search is available through the Responses API and the Messages API. Requesting it on the Chat Completions API returns a 400 error. Each API’s native spelling is accepted as an alias and answered in kind, so an existing integration does not need rewriting: Only the regex variant is implemented. Requesting the BM25 variant — tool_search_tool_bm25 or tool_search_tool_bm25_20251119 — returns a 400:
tool_search_tool_bm25_20251119 is not supported yet. OpenRouter implements the regex tool-search variant only — use openrouter:tool_search (or tool_search_tool_regex_20251119) instead.

​
Configuration

​
When to Use It

Reach for tool search when your definitions exceed roughly 10k tokens, when you have more than about 10 tools, or when tool selection accuracy drops as the library grows. Standard tool calling is the better fit below about 10 tools, when every tool is used on every request, or when your definitions are small enough that the search round-trip costs more than it saves.