Skip to main content
Query a knowledge base to search for relevant chunks by semantic similarity.

​
What this means in practice

When you have organized information into a knowledge base (via import or chunking), use crystal_query_knowledge_base to:
  • Retrieve relevant information by semantic meaning (not just keyword match)
  • Scope queries to a specific knowledge base
  • Filter by agent or channel if the knowledge base supports it
  • Limit results to reduce noise and context overhead

​
Parameters

ParameterTypeRequiredDescription
knowledgeBaseIdstringConditionalThe ID of the knowledge base to query. Either this or knowledgeBaseName is required.
knowledgeBaseNamestringConditionalThe human-readable name of the knowledge base. Either this or knowledgeBaseId is required.
querystringYesThe search query. Automatically embedded and searched against KB chunks.
limitnumberNoMaximum results to return. Default: unspecified. Range: 1–20.
agentIdstringNoOptional agent identifier for scoped queries.
channelstringNoOptional channel identifier for scoped queries.

​
Returns

{
  "chunks": [
    {
      "id": "chunk_abc123",
      "content": "The queried knowledge base chunk content.",
      "metadata": {
        "score": 0.92,
        "source": "import_name",
        "title": "Optional chunk title"
      }
    }
  ],
  "totalCount": 1,
  "query": "user's search query",
  "knowledgeBaseId": "kb_xyz789"
}

​
Examples

Basic query by name: 
{
  "knowledgeBaseName": "Product API Docs",
  "query": "How do I authenticate with the API?"
}
Query by ID with result limit: 
{
  "knowledgeBaseId": "kb_abc123",
  "query": "pricing tiers",
  "limit": 5
}
Scoped query for a specific agent: 
{
  "knowledgeBaseName": "Engineering Handbook",
  "query": "deployment checklist",
  "agentId": "release-agent",
  "limit": 3
}

​
When to use vs alternatives

Use caseTool
Search a specific knowledge base by semantic meaningcrystal_query_knowledge_base
Semantic search across all memories (not KBs)crystal_recall
Exact text match in messagescrystal_search_messages
Get all KBs available to the usercrystal_list_knowledge_bases
Import or create a new knowledge baseUse dashboard or API

​
Error handling

ErrorCauseResolution
Knowledge base not foundThe specified ID or name doesn’t exist or is not accessible.Verify the KB name/ID via crystal_list_knowledge_bases.
query is requiredNo query parameter was provided.Provide a non-empty query string.
knowledgeBaseId or knowledgeBaseName is requiredNeither ID nor name was provided.Provide at least one identifier.
Empty resultsThe query matched no chunks above the similarity threshold.Try a simpler or more general query.

​
Source of truth

  • mcp-server/src/tools/query-knowledge-base.ts — tool definition and HTTP handler
  • convex/crystal/knowledgeBases.ts — backend query logic
  • apps/web/app/(dashboard)/knowledge-bases/ — KB management UI