Query Tool Setup

Overview

The Query Tool is the underlying mechanism that powers Sulus's Knowledge Base feature. While the general Knowledge Base page covers the concept and the fastest dashboard-based path to attaching files to an assistant, this page is specifically about the type: "query" tool object itself — how to build one directly through the API, reference multiple knowledge bases in a single tool, and attach it to an assistant with fine-grained control.

If you just want the quickest way to give an assistant a knowledge base, see the Knowledge Base page. Use this page when you need the API-level detail: managing file IDs directly, combining several knowledge bases in one tool, or troubleshooting why an assistant isn't using its knowledge base.

Before creating a query tool, upload the source files it will search. This can be done through the dashboard (Build > Files > Upload File) or via the Files API:

curl --location 'https://api.sulus.ai/file' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--form 'file=@"<PATH_TO_YOUR_FILE>"'

The response includes a file id — note it down, since the query tool references files by ID rather than by name. Supported formats include .txt, .pdf, .docx, .csv, .md, .json, and .xml. See the Files API page for the full reference on uploading, listing, updating, and deleting files.

Create a tool with "type": "query", referencing your uploaded file IDs inside a knowledgeBases array:

curl --location 'https://api.sulus.ai/tool/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "type": "query",
    "function": {
        "name": "product-query"
    },
    "knowledgeBases": [
        {
            "provider": "google",
            "name": "product-kb",
            "description": "Contains comprehensive product information, service details, and company offerings",
            "fileIds": [
                "41a2bd44-d13c-4914-bbf7-b19807dd2cf4",
                "ef82ae15-21b2-47bd-bde4-dea3922c1e49"
            ]
        }
    ]
}'

The description field matters more than it looks — it's what the assistant uses to decide when a particular knowledge base is relevant, so write it as a clear, specific summary of that knowledge base's content rather than a generic label.

A single query tool can hold more than one knowledge base, which is useful when an assistant needs to draw from clearly separated topics (for example, product documentation versus troubleshooting guides):

"knowledgeBases": [
    {
        "provider": "google",
        "name": "product-documentation",
        "description": "Contains detailed product specifications, feature descriptions, and technical details",
        "fileIds": ["file-id-1", "file-id-2"]
    },
    {
        "provider": "google",
        "name": "troubleshooting-guide",
        "description": "Contains troubleshooting guides, support procedures, and problem resolution steps",
        "fileIds": ["file-id-3", "file-id-4"]
    }
]

Keep each knowledge base scoped to one topic area rather than combining unrelated content into a single entry — this improves retrieval accuracy since the assistant is choosing between clearly distinct descriptions.

Attach the query tool to an assistant with a PATCH request referencing the tool's ID in toolIds:

curl --location --request PATCH 'https://api.sulus.ai/assistant/ASSISTANT_ID' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "model": {
        "temperature": 0.2,
        "provider": "openai",
        "model": "gpt-4o",
        "toolIds": [
            "9441840b-6f2f-4b0f-a0fc-de8512549a0c"
        ]
    }
}'

Important: this PATCH request replaces the entire model object. Include every existing field you want to keep — not just toolIds — or you will overwrite the rest of the model configuration.

This is the step most setups miss: attaching the query tool and writing a good knowledge base description is not enough on its own. You must also explicitly instruct the assistant, in its system prompt, to use the tool by name and describe when it should reach for it.

{
  "role": "system",
  "content": "You are a helpful customer support assistant. When users ask about products, pricing, features, or need troubleshooting help, use the 'knowledge-search' tool to search our knowledge base for accurate information."
}

Replace 'knowledge-search' with the actual function.name you set when creating the query tool. Without this explicit instruction, the assistant may never invoke the tool even though it's attached — the knowledge base description alone only helps the assistant choose which knowledge base to search once it has decided to use the tool, not whether to use it at all.

• Keep individual files under 300KB for optimal retrieval performance
• Write clear, specific knowledge base descriptions — this is what the assistant reads to choose the right knowledge base
• Always update the system prompt to name the tool explicitly and describe when to use it
• Split unrelated topics into separate knowledge base entries rather than one large mixed file set
• Test with a range of real user queries after setup to confirm retrieval accuracy

For the simpler dashboard-driven path to knowledge bases (which creates a query tool automatically behind the scenes), see the Knowledge Base page. For the full file management reference, see the Files API page.