> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search models server tool

> Let a model search the Orq.ai catalog by provider, context length, capability, or input cost.

The `orq:search_models` tool searches the **Orq.ai** model catalog during a response. It is useful when a model needs to choose another model based on context length, tool support, vision support, or input cost.

Results come from the public model registry plus the private models enabled in the current workspace; public results are not filtered to models enabled in the workspace. Only chat models are returned.

## Quick start

The examples use the client configuration from the [Server tools overview](/ai-gateway/features/server-tools).

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://my.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.4-mini",
      "messages": [
        { "role": "user", "content": "Find a model with vision and tool support for a document workflow." }
      ],
      "tools": [
        { "type": "orq:search_models", "max_results": 5 }
      ]
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await client.chat.completions.create({
    model: 'openai/gpt-5.4-mini',
    messages: [
      {
        role: 'user',
        content:
          'Find a model with vision and tool support for a document workflow.',
      },
    ],
    tools: [{ type: 'orq:search_models', max_results: 5 }] as any,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response = client.chat.completions.create(
      model="openai/gpt-5.4-mini",
      messages=[
          {
              "role": "user",
              "content": "Find a model with vision and tool support for a document workflow.",
          }
      ],
      tools=[
          {"type": "orq:search_models", "max_results": 5}
      ],
  )

  print(response.choices[0].message.content)
  ```
</CodeGroup>

## Configuration

| Parameter     | Type    | Required | Default | Description                                       |
| ------------- | ------- | -------- | ------- | ------------------------------------------------- |
| `type`        | string  | Yes      |         | Must be `orq:search_models`.                      |
| `max_results` | integer | No       | `5`     | Maximum models returned. Accepted range: 1 to 20. |

## Model-supplied filters

The model can combine these filters in a tool call:

| Filter               | Description                                       |
| -------------------- | ------------------------------------------------- |
| `query`              | Match model name, display name, or model family.  |
| `provider`           | Match one provider.                               |
| `min_context_length` | Require at least this many context tokens.        |
| `require_tools`      | Return only models that support function calling. |
| `require_vision`     | Return only models that support image input.      |
| `max_input_cost`     | Maximum input cost in USD per 1,000 tokens.       |

`query` matches the bare model name, not the `provider/model` id, so `gpt-5.4-mini` matches and `openai/gpt-5.4-mini` does not. Combine `query` with `provider` to narrow to one provider.

The result contains `models`, `total_results` (all matches), and `showing` (the number returned). Each model includes an `id` field (`provider/model`, e.g. `openai/gpt-5.4-mini`), which is the canonical routable identifier to pass as `model` in subsequent requests, since the bare model name is not unique across providers. Private workspace models carry the `workspaceKey@` prefix (e.g. `my-workspace@openai/my-finetune`). Results are sorted by `id` and include model costs, context length, and capability flags.

## Cost and usage

Catalog searches have no additional charge. The number of searches appears at `usage.server_tool_use.search_models_requests`.

Pair this tool with [Subagent](/ai-gateway/features/server-tools/subagent) when the calling model should select a worker model before delegating a task.