Skip to main content
Glama

search_knowledge

Search a local knowledge base using hybrid semantic and keyword retrieval with reranking; filter by category or folder and return ranked document chunks for your query.

Instructions

Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking.

Read-only. No side effects.

Args: query: Search query text (1–3 keywords recommended; phrase queries also work) max_results: Maximum number of results (default: 5, capped by search.max_results). category: Optional category filter. Accepts the categories the server is configured with (category_mappings values and keyword_routes keys) plus general; an empty string, like omitting it, searches every category, and any other value returns an error that lists the valid ones. Call list_categories() first to see which categories hold documents and how many. hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only (best for conceptual or natural-language queries). min_score: Minimum score (0.0–1.0) a result needs to be returned; default 0.0 returns all results. Scores are min-max normalized per query over its candidates: the best scores 1.0 and the weakest 0.0, while a single candidate or candidates that all tie score 1.0. On the hybrid path (results labeled hybrid, semantic or keyword) the candidates are the returned results, so any min_score above 0 drops at least the weakest one unless all tie; fts5 results are BM25 scores normalized over up to max(3 * max_results, 20) hits, so even the weakest returned one can score well above 0.0. It is not an absolute relevance bar. snippet_mode: When true (default), truncates content to ~500 characters from the start of the matching chunk, at a natural break point, and adds a content_length field with the full size. Use get_document() to fetch full content when needed. Set to false to return the full content, which can include adjacent chunks; match_offset, when present, is where the match starts. search_method: Dispatch selector (v4.8.2+). One of "auto" (router picks FTS5 fast-path for lexical queries when enabled, hybrid otherwise), "hybrid" (force hybrid path — kill switch for suspected router misclassification), or "fts5" (force FTS5 fast-path — debug/testing; errors out when the feature is disabled or the index is not ready). Default "auto" preserves pre-v4.8.2 behavior byte-for-byte when the fast-path is disabled in config. include_folders: Optional list of directories relative to documents_dir, recursively included before candidate selection (e.g. ["manuals/product-a", "runbooks"]). Omit for all folders. exclude_folders: Optional recursive directory exclusions, applied before candidate selection. Exclusions override inclusions. Paths use / or , have exact component boundaries, and cannot be absolute, contain '..', or resolve outside documents_dir. Maximum 32 each.

Returns: JSON string with results including content chunks, source filepath, relevance score, and search method used. Returns chunks, not full document content.

Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when you already have a reference document and want more like it. Prefer get_document() when you already know the exact filepath and need the full content.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_knowledge"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes
categoryNo
min_scoreNo
max_resultsNo
hybrid_alphaNo
snippet_modeNo
search_methodNoauto
exclude_foldersNo
include_foldersNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv4.11.1
    • addedInput schema / properties / category / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / properties / category / type
      Removed value: -"string"
    • addedInput schema / properties / exclude_folders
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Exclude Folders"
      +}
    • addedInput schema / properties / include_folders
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Include Folders"
      +}
  2. Changed1 schema field changedv4.8.3
    • addedInput schema / properties / search_method
      Added value: +{
      +  "default": "auto",
      +  "title": "Search Method",
      +  "type": "string"
      +}
  3. Changed2 schema fields changedv4.3.1
    • addedInput schema / properties / min_score
      Added value: +{
      +  "default": 0,
      +  "title": "Min Score",
      +  "type": "number"
      +}
    • addedInput schema / properties / snippet_mode
      Added value: +{
      +  "default": true,
      +  "title": "Snippet Mode",
      +  "type": "boolean"
      +}
  4. First observedv3.0.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does: it declares "Read-only. No side effects," discloses that invalid category values return an error listing valid ones, that fts5 search_method errors when the feature is disabled or the index is not ready, and that folder paths cannot be absolute, contain '..', or escape documents_dir (max 32 each). It further warns that min_score is a per-query min-max normalized value, not an absolute relevance bar — a genuinely non-obvious behavioral caveat that prevents misuse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: the one-line summary precedes Args/Returns/Usage sections, so an agent gets the gist immediately. The min_score entry is a dense paragraph about normalization edge cases that could be tightened, but the detail is defensible because the scoring behavior is counterintuitive and misreading it would cause silently dropped results.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with zero schema coverage, the description covers every parameter, states the return shape (chunks with filepath, score, and search method — not full documents), and points to get_document for full content. An output schema exists, but the description's brief Returns note adds the important caveat that results are chunks rather than complete documents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate entirely, and it documents all 9 parameters with meaning beyond the schema's bare types and defaults. It supplies concrete semantics for hybrid_alpha's endpoints (0.0 keyword-only for CVE IDs/tool names, 1.0 semantic-only for conceptual queries), the enumerated valid values for search_method with their side conditions, the default and cap behavior of max_results, and the exact include/exclude precedence rule.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific implementation-level statement of what the tool does: hybrid search combining semantic + BM25 keyword retrieval with cross-encoder reranking. It names the resource (knowledge documents) and the retrieval strategy, which no sibling tool shares — search_similar is reference-driven and get_document is path-driven, so an agent can distinguish them immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules are given: "Primary search tool — use for any topic or keyword lookup," with named alternatives and the exact conditions that select them (search_similar when you have a reference document, get_document when you know the filepath). It also prescribes a preparatory call ("Call list_categories() first") and explains when to raise hybrid_alpha toward keyword-only or semantic-only based on query type.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.