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

# Server tool Tool search

> Mantenha grandes bibliotecas de ferramentas fora do prompt e permita que o modelo pesquise as ferramentas de que precisa com a server tool orq:tool_search.

A ferramenta `orq:tool_search` adia o carregamento de function tools no prompt até que o modelo as solicite. Marque as function tools com `defer_loading: true`, e o modelo receberá apenas a ferramenta de busca e as ferramentas não adiadas. Quando o modelo precisa de um recurso, ele pesquisa as ferramentas adiadas com uma expressão regular, e as ferramentas correspondentes passam a poder ser chamadas no turno seguinte.

Adiar ferramentas reduz os tokens do prompt e mantém a lista de ferramentas estável para o prompt caching. Isso compensa a partir de aproximadamente dez ferramentas ou 10k tokens de definições de ferramentas. A busca é executada no **AI Gateway**; portanto, funciona com qualquer modelo compatível com tool calling.

## Início rápido

Os exemplos usam a configuração de cliente da [Visão geral das server tools](/docs/pt-BR/ai-gateway/features/server-tools.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_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
      }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

Em Chat Completions, defina `defer_loading` ao lado de `function` no objeto da ferramenta.

## Como funciona

1. O modelo vê `orq_tool_search` e as ferramentas que não foram adiadas.
2. Quando precisa de um recurso, ele chama `orq_tool_search` com uma expressão regular, por exemplo, `calendar|event`.
3. O **AI Gateway** compara o padrão, sem diferenciar maiúsculas de minúsculas, com os nomes, as descrições e os nomes e descrições dos parâmetros das ferramentas adiadas. Um padrão `weather` encontra uma ferramenta cuja única menção a clima está na descrição de um parâmetro.
4. As ferramentas correspondentes são adicionadas à lista de ferramentas do modelo. O modelo as chama como qualquer outra function tool, e a aplicação trata a chamada normalmente.

Revelar uma ferramenta não altera as ferramentas que já estão na conversa; assim, o prefixo de prompt em cache permanece intacto. Em uma continuação com `previous_response_id` ou `conversation`, as ferramentas reveladas em turnos anteriores são oferecidas desde o início.

## Configuração

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `type` | string | Sim | | Deve ser `orq:tool_search`. |
| `max_results` | integer | Não | `5` | Máximo de ferramentas reveladas por busca. Intervalo aceito: de 1 a 50. |

Defina `defer_loading: true` em qualquer ferramenta `function` para ocultá-la. Apenas function tools podem ser adiadas; o próprio `orq:tool_search` nunca é adiado, para que o modelo sempre tenha uma ferramenta para chamar.

## Regras

* Uma solicitação com uma ferramenta adiada precisa incluir `orq:tool_search`; caso contrário, falha com `tool_search_required`.
* `tool_choice` precisa ser omitido, `auto` ou `none`. Forçar uma chamada de ferramenta entra em conflito com o tool search e falha com `tool_choice_conflict`.
* Um padrão tem no máximo 200 caracteres. Um padrão malformado é retornado ao modelo como erro de ferramenta, e não como falha da solicitação.
* Uma chamada a uma ferramenta adiada que nenhuma busca revelou é rejeitada como uma ferramenta que não foi oferecida.

## Agentes

Os agentes também podem usar o tool search. Adicione `orq:tool_search` às ferramentas do agente e defina `configuration.defer_loading` nas ferramentas personalizadas que devem ser ocultadas:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 } }
  ]
}
```

Sem `orq:tool_search` no agente, `defer_loading` não tem efeito e todas as ferramentas permanecem visíveis.

## Custo e uso

As buscas de ferramentas não têm cobrança adicional. O número de buscas aparece em `usage.server_tool_use.tool_search_requests`. Cada busca é um item de saída `orq:tool_search` cujo resultado lista as ferramentas reveladas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.