> ## 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.

# Knowledge-base server tools

> List and query knowledge bases during a response so a model can answer from workspace documents.

Two server tools give a model access to knowledge bases in the current workspace:

* `orq:retrieve_knowledge_bases` lists available knowledge bases and their keys.
* `orq:query_knowledge_base` retrieves document content from one knowledge base.

Both tools are available on `POST /v3/router/responses` and `POST /v3/router/chat/completions`. Use both tools when the knowledge-base key is not already known.

The unprefixed names `retrieve_knowledge_bases` and `query_knowledge_base` remain accepted as legacy aliases on the Responses API only. With the aliases, the model sees the tools under their bare names instead of `orq_retrieve_knowledge_bases` and `orq_query_knowledge_base`.

## 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/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.4-mini",
      "input": "What is the refund policy in the support knowledge base?",
      "tools": [
        { "type": "orq:retrieve_knowledge_bases" },
        { "type": "orq:query_knowledge_base" }
      ]
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await client.responses.create({
    model: 'openai/gpt-5.4-mini',
    input: 'What is the refund policy in the support knowledge base?',
    tools: [
      { type: 'orq:retrieve_knowledge_bases' },
      { type: 'orq:query_knowledge_base' },
    ] as any,
  });

  console.log(response.output_text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response = client.responses.create(
      model="openai/gpt-5.4-mini",
      input="What is the refund policy in the support knowledge base?",
      tools=[
          {"type": "orq:retrieve_knowledge_bases"},
          {"type": "orq:query_knowledge_base"},
      ],
  )

  print(response.output_text)
  ```
</CodeGroup>

## How retrieval works

1. `orq:retrieve_knowledge_bases` returns the key and description of each knowledge base in the workspace.
2. The model selects a key and calls `orq:query_knowledge_base` with a search query.
3. The query tool returns matching chunks to the model. Each result carries `text`, `chunk_id`, `file_name`, `file_type`, and `score`, plus `page_number` and `metadata` when available. An unknown key returns a not-found message to the model.

The list tool returns metadata, not document content. A model must call the query tool before it can answer from a knowledge base.

## Model-supplied arguments

The tool entries have no configuration fields beyond `type`. The model supplies these arguments when it calls them. All arguments are required by the tool schema.

| Tool                           | Argument               | Type    | Description                                                          |
| ------------------------------ | ---------------------- | ------- | -------------------------------------------------------------------- |
| `orq:retrieve_knowledge_bases` | `include_descriptions` | boolean | Accepted for schema compatibility. Descriptions are always included. |
| `orq:query_knowledge_base`     | `query`                | string  | Search query.                                                        |
| `orq:query_knowledge_base`     | `knowledge_base_key`   | string  | Key returned by `orq:retrieve_knowledge_bases`.                      |
| `orq:query_knowledge_base`     | `include_metadata`     | boolean | Include document metadata with the results.                          |

Knowledge-base calls are not included in `usage.server_tool_use`.