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
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| category | No | ||
| min_score | No | ||
| max_results | No | ||
| hybrid_alpha | No | ||
| snippet_mode | No | ||
| search_method | No | auto | |
| exclude_folders | No | ||
| include_folders | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |