search_knowledge_base

Tool

search_knowledge_base

Capability: read Rate limit: 1000 / hr per token

Parameters

Mode trade-offs

• semantic: vector cosine similarity. Best for fuzzy queries where the answer paraphrases the source (for example, "explain the consent flow" versus source text "user consent at /authorize").
• keyword: Postgres full-text search over the chunk text. Best for exact strings, proper nouns, function names, API names, and error codes that semantic search smooths over.
• hybrid (default): a weighted blend of 70% semantic and 30% keyword rank. Catches both kinds of intent without making the agent choose.

Example call (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_knowledge_base",
    "arguments": {
      "query": "How do I scope a token to multiple folders?",
      "limit": 5,
      "mode": "hybrid"
    }
  }
}

Example response

The text content includes a formatted list of hits with titles and similarity scores. The structuredContent (when the client requests it) has the same data programmatically.

1. (0.84) Tokens, capabilities, and scope
   "...A token carries a folder scope, whole library or a specific
    list of folders..."

2. (0.81) MCP vs REST
   "...Scope rules: multi-folder scope tokens require every target
    folder to be in scope..."

3. (0.79) Add v1 folders endpoints
   "...is_unscoped boolean, explicit 'whole library' flag..."

Scope behavior

The search is scoped by the token's folder list. Whole-library tokens see every in-KB chunk. Scoped tokens see only chunks belonging to items in the token's folders.

KB-only is always implicit for search. Items flagged as not-in-KB are never indexed in the chunks table, regardless of the token's kb_only flag.

Errors

Related

• get_item: fetch the full content for a hit
• REST /api/v1/items: paginated item list (no chunk-level search yet; use MCP for that)