Knowledge Base Tool

The Knowledge Base tool lets your agent search uploaded documents during a live call. When the caller asks a question that requires specific information -- a return policy, product spec, pricing detail -- the LLM calls the retrieval function, the platform searches your documents using RAG, and the relevant content is returned so the agent can answer accurately.

There are two ways to use knowledge base retrieval during calls:

1. Dashboard tool -- create a persistent knowledge_base tool in the Tools page and attach it to agents, just like any other tool.
2. Inline query tool (API) -- pass a {"type": "query", ...} tool inline when making a call via the API, useful for transient or override agent configurations.

Creating via Dashboard

Use the dashboard when you want a reusable, persistent tool that can be attached to multiple agents.

Once saved, attach the tool to any agent. During calls, the LLM sees a retrieve_from_knowledge_base function and calls it when the conversation matches the tool's description.

Using via API (Inline Query Tools)

When making calls via the API with a transient or override agent configuration, you can pass knowledge base tools inline -- no need to pre-create them in the dashboard.

Inline Query Tool Schema

{
  "type": "query",
  "function": {
    "name": "search_product_docs",
    "description": "Search product documentation for answers to customer questions"
  },
  "knowledgeBases": [
    {
      "name": "Product Docs",
      "description": "Product documentation and user guides",
      "documentIds": ["uuid-1", "uuid-2"]
    }
  ],
  "timeout": 5
}

Field Reference

Example: Call with Inline KB Tool

curl -X POST https://dashboard.zoxa.ai/api/v1/call \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "agent": {
      "name": "Support Agent",
      "systemPrompt": "You are a helpful support agent. Answer questions using the product documentation.",
      "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
      "tts": { "provider": "elevenlabs", "model": "eleven_flash_v2_5" },
      "stt": { "provider": "soniox", "model": "stt-rt-v5" },
      "tools": [
        {
          "type": "query",
          "function": {
            "name": "search_product_docs",
            "description": "Search product documentation when the caller asks about features, setup, troubleshooting, or usage."
          },
          "knowledgeBases": [
            {
              "name": "Product Docs",
              "description": "Product documentation, setup guides, and troubleshooting articles",
              "documentIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
            }
          ],
          "timeout": 5
        },
        { "type": "endCall" }
      ]
    }
  }'

All Inline Tool Types

The tools array in a transient or override agent config accepts these formats:

Multi-Group KB Routing

When you define multiple knowledgeBases entries in a single query tool, the platform uses an intelligent routing step to determine which group(s) to search.

How It Works

Caller: "What's the return policy for electronics?"
    |
    v
LLM calls search tool with query: "return policy for electronics"
    |
    v
KB Router (gpt-4.1-mini) classifies the query:
  - Group 1: "Return Policies" --> MATCH
  - Group 2: "Product Specs"   --> NO MATCH
    |
    v
Platform searches only the "Return Policies" documents
    |
    v
Results returned to LLM --> agent answers the caller

Example: Multiple KB Groups

{
  "type": "query",
  "function": {
    "name": "search_company_docs",
    "description": "Search company documentation for policies, product info, or HR questions"
  },
  "knowledgeBases": [
    {
      "name": "Product Catalog",
      "description": "Product specifications, features, pricing, and availability",
      "documentIds": ["uuid-products-1", "uuid-products-2"]
    },
    {
      "name": "Company Policies",
      "description": "Return policies, warranty terms, shipping policies, and customer service guidelines",
      "documentIds": ["uuid-policies-1"]
    },
    {
      "name": "HR Handbook",
      "description": "Employee benefits, PTO policies, onboarding procedures, and company values",
      "documentIds": ["uuid-hr-1", "uuid-hr-2", "uuid-hr-3"]
    }
  ],
  "timeout": 8
}

When the caller asks "What's the PTO policy?", the KB router identifies the "HR Handbook" group as the best match and searches only those documents, improving both speed and relevance.

How Retrieval Works During a Call

Regardless of whether you use a dashboard tool or an inline query tool, the retrieval flow during a live call follows the same steps:

Validation Rules

The platform validates all tools -- including inline query tools -- before a call starts. Invalid tools cause the call to fail with a descriptive error.

Tool Name Rules

Reserved Names

These function names are reserved by the platform and cannot be used for custom tools:

• end_call
• retrieve_from_knowledge_base
• safe_calculator

Document Validation

Timeout Limits

URL Security (Function Tools)

Server URLs for inline function tools cannot point to private or internal IP addresses (localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x). This does not apply to query tools, which have no external URL.

HTTP Methods (Function Tools)

Only these HTTP methods are allowed for inline function tools: GET, POST, PUT, PATCH, DELETE.

Best Practices

1. Write specific tool descriptions -- tell the LLM exactly what kind of questions this tool answers. "Search the knowledge base" is too vague. "Search product documentation for feature details, setup instructions, and troubleshooting steps" is much better.

2. Use a single KB group when possible -- if all your documents cover the same domain, put them in one group. Multi-group routing adds latency and is only valuable when you have clearly distinct document categories.

3. Keep documents focused -- one topic per document produces better retrieval results than a single large document covering everything. A 3-page "Return Policy" document retrieves more accurately than a 50-page "All Company Policies" document.

4. Increase timeout for large document sets -- the default 5-second timeout works for most cases, but if you have many chunked documents or multiple KB groups with routing, consider increasing to 8-10 seconds.

5. Ensure documents are processed before calling -- the validator checks that all documentIds have status completed. If you just uploaded a document, wait for processing to finish before making calls that reference it.

6. Test retrieval quality first -- use the Knowledge Base search API to test queries against your documents before deploying to a live agent.

7. Combine with other tools -- KB tools work alongside HTTP API, Call Transfer, and End Call tools. A common pattern is a KB tool for answering questions plus an End Call tool for wrapping up the conversation.

Related Pages