Knowledge-base server tools

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.

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" }
    ]
  }'

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);

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)

How retrieval works

orq:retrieve_knowledge_bases returns the key and description of each knowledge base in the workspace.
The model selects a key and calls orq:query_knowledge_base with a search query.
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.

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Server Tools

Common Scenarios

Quick start

How retrieval works

Model-supplied arguments

​Quick start

​How retrieval works

​Model-supplied arguments

Quick start

How retrieval works

Model-supplied arguments