Tool search server tool

The orq:tool_search tool defers function tools from the prompt until the model asks for them. Mark function tools with defer_loading: true, and the model receives only the search tool plus the non-deferred tools. When the model needs a capability, it searches the deferred tools with a regular expression, and the matching tools become callable on the next turn. Deferring tools reduces prompt tokens and keeps the tool list stable for prompt caching. It pays off from roughly ten tools or 10k tokens of tool definitions. The search runs on the AI Gateway, so it works with any model that supports tool calling.

Quick start

The examples use the client configuration from the Server tools overview.

curl -X POST https://my.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Book me a table for four tomorrow night and add it to my calendar.",
    "tools": [
      { "type": "orq:tool_search" },
      {
        "type": "function",
        "name": "book_restaurant",
        "description": "Reserve a restaurant table for a party at a given date and time.",
        "parameters": {
          "type": "object",
          "properties": {
            "party_size": { "type": "integer", "description": "Number of guests." },
            "datetime": { "type": "string", "description": "Reservation time as an ISO 8601 timestamp." }
          },
          "required": ["party_size", "datetime"]
        },
        "defer_loading": true
      },
      {
        "type": "function",
        "name": "create_calendar_event",
        "description": "Add an event to the user'"'"'s calendar.",
        "parameters": {
          "type": "object",
          "properties": {
            "title": { "type": "string", "description": "Event title." },
            "start": { "type": "string", "description": "Start time as an ISO 8601 timestamp." }
          },
          "required": ["title", "start"]
        },
        "defer_loading": true
      }
    ]
  }'

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Book me a table for four tomorrow night and add it to my calendar.',
  tools: [
    { type: 'orq:tool_search' },
    {
      type: 'function',
      name: 'book_restaurant',
      description: 'Reserve a restaurant table for a party at a given date and time.',
      parameters: {
        type: 'object',
        properties: {
          party_size: { type: 'integer', description: 'Number of guests.' },
          datetime: { type: 'string', description: 'Reservation time as an ISO 8601 timestamp.' },
        },
        required: ['party_size', 'datetime'],
      },
      defer_loading: true,
    },
  ] as any,
});

console.log(response.output);

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Book me a table for four tomorrow night and add it to my calendar.",
    tools=[
        {"type": "orq:tool_search"},
        {
            "type": "function",
            "name": "book_restaurant",
            "description": "Reserve a restaurant table for a party at a given date and time.",
            "parameters": {
                "type": "object",
                "properties": {
                    "party_size": {"type": "integer", "description": "Number of guests."},
                    "datetime": {"type": "string", "description": "Reservation time as an ISO 8601 timestamp."},
                },
                "required": ["party_size", "datetime"],
            },
            "defer_loading": True,
        },
    ],
)

print(response.output)

On Chat Completions, set defer_loading next to function on the tool object.

How it works

The model sees orq_tool_search and the tools that are not deferred.
When it needs a capability, it calls orq_tool_search with a regular expression, for example calendar|event.
The AI Gateway matches the pattern case-insensitively against the names, descriptions, and parameter names and descriptions of the deferred tools. A pattern of weather finds a tool whose only mention of weather is in a parameter description.
The matching tools are added to the model’s tool list. The model calls them like any other function tool, and the application handles the call as usual.

Revealing a tool does not change the tools already in the conversation, so the cached prompt prefix stays intact. On a continuation with previous_response_id or conversation, tools revealed in earlier turns are offered from the start.

Configuration

Parameter	Type	Required	Default	Description
`type`	string	Yes		Must be `orq:tool_search`.
`max_results`	integer	No	`5`	Maximum tools revealed per search. Accepted range: 1 to 50.

Set defer_loading: true on any function tool to hide it. Only function tools can be deferred; orq:tool_search itself is never deferred so the model always has a tool to call.

Rules

A request with a deferred tool must include orq:tool_search, otherwise it fails with tool_search_required.
tool_choice must be omitted, auto, or none. Forcing a tool call conflicts with tool search and fails with tool_choice_conflict.
A pattern is at most 200 characters. A malformed pattern is returned to the model as a tool error, not as a request failure.
A call to a deferred tool that no search revealed is rejected as a tool that was not offered.

Agents

Agents can use tool search as well. Add orq:tool_search to the agent’s tools and set configuration.defer_loading on the custom tools to hide:

{
  "tools": [
    { "type": "orq:tool_search", "configuration": { "max_results": 5 } },
    { "type": "http", "key": "book_restaurant", "configuration": { "defer_loading": true } },
    { "type": "http", "key": "create_calendar_event", "configuration": { "defer_loading": true } }
  ]
}

Without orq:tool_search on the agent, defer_loading has no effect and every tool stays visible.

Cost and usage

Tool searches have no additional charge. The number of searches appears at usage.server_tool_use.tool_search_requests. Each search is an orq:tool_search output item whose result lists the revealed tools.

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Server Tools

Common Scenarios

Quick start

How it works

Configuration

Rules

Agents

Cost and usage

​Quick start

​How it works

​Configuration

​Rules

​Agents

​Cost and usage

Quick start

How it works

Configuration

Rules

Agents

Cost and usage