Skip to main content
Glama
lyonzin

knowledge-rag

by lyonzin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_knowledge

Find relevant document chunks by topic or keyword using hybrid semantic and BM25 search, with category and folder filters for targeted knowledge-base lookups.

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 — one of: security, ctf, logscale, development, general, redteam, blueteam. Call list_categories() first to see available categories and counts. 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 normalized relevance score (0.0–1.0) to include a result. Results scoring below this threshold are discarded. Default 0.0 returns all results. Use 0.2–0.4 to cut low-relevance noise. snippet_mode: When true (default), truncates content to ~500 characters at a natural break point and adds a content_length field with the original size. Use get_document() to fetch full content when needed. Set to false to return full chunk content. 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.

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?

No annotations are provided, so the description carries the full burden — and it does: 'Read-only. No side effects.' plus truncation behavior (~500 chars, natural break, content_length field), the fact that chunks rather than full documents are returned, and the failure mode for forcing fts5 when the index is not ready. Default behavior byte-for-byte compatibility is also stated for the auto dispatch.

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 with mechanism and safety first, then Args/Returns/Usage sections that make it scannable. Mild bloat in the search_method paragraph (v4.8.2 version note, 'byte-for-byte' compatibility clause) which serves debuggers more than typical callers.

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 hybrid search tool with no annotations and 0% schema coverage, the description supplies everything needed: mechanism, safety, parameter semantics, category prerequisite, return shape, and sibling routing. It even explains returns despite an output schema existing.

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% across 9 parameters, so the description must compensate entirely — and it does, documenting every parameter with ranges, defaults, and concrete guidance (hybrid_alpha 0.0 vs 0.3 vs 1.0 with example use cases; min_score 0.2–0.4 to cut noise; include/exclude_folders path rules including the 32-item cap, no '..', and exclusion precedence).

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?

Opens with a precise mechanism statement: hybrid semantic + BM25 keyword search with cross-encoder reranking. It names the resource being searched (the document/knowledge index) and contrasts implicitly with get_document and search_similar, which appear later as explicit alternatives.

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?

Declares itself the 'primary search tool — use for any topic or keyword lookup' and routes explicitly to search_similar() (when a reference document exists) and get_document() (when the filepath is known). It also instructs the agent to call list_categories() before using the category filter and explains when to force search_method values.

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

Deploy Server

Other Tools