Hybrid semantic + structural search
search_hybrid_contextUse for initial codebase discovery to find features by meaning through read-only semantic and structural search combining vector embeddings and graph analysis, returning files, signatures, and docs.
Instructions
Read-only semantic and structural code search combining vector embeddings with graph analysis. Use this for initial codebase discovery to find features by their meaning (e.g., 'user authentication'). Locates code based on natural language descriptions instead of exact keywords, returning relevant files, signatures, and documentation.
⚠️ PREREQUISITE: This tool requires an active knot-mcp server with vector database (Qdrant) and graph database (Neo4j) initialized.
Behavior & Return: Performs a read-only dual query against vector DB (for semantic similarity) and graph DB (for architectural relationships). Returns Markdown-formatted results with file paths, line numbers, code snippets, and cross-repository dependencies. No side effects.
Usage: Use as your FIRST step when exploring unfamiliar code or discovering architectural patterns. Do NOT use this to find all usages of a specific function—use the 'find_callers' tool for that instead.
Ranking contract: results are kind-aware — function/method/class/struct definitions outrank markdown docs, test files, config properties and build-dependency entities for natural-language queries; callers and helpers appear as context attached to a definition, never as substitutes. The shared entry point of the highest-ranked helpers outranks those helpers a loose paraphrase surfaces.
Relationship summary: each result's 'Called by' / 'Called via dispatch' counts come from the graph edges of that exact entity — the same edges 'find_callers' reports for its fully qualified name; same-named entities elsewhere never contribute. 'Calls' lists callees qualified with their owning type or module, capped at 8 plus '+N more'. Callers in test code count toward the totals but are shown as 'N in tests' unless 'include_tests' is true; a sample in the result's own file reads 'name (same file)'.
Detail: 'detail: "brief"' renders one line per result (kind, file:line, caller/callee counts) to scan many hits cheaply; expand the one you need with 'find_callers' / 'explore_file' or a default 'full' search.
Generic-verb guard: an entity merely named after a generic verb or noun (find/get/create/build/acquire/borrow/current/…) does not win on that name alone; the full name boost is paid only when the entity's container context (FQN) corroborates a second query token.
Recall contract: entity embeds carry identifier tokens and the tokenized call names of the entity's body, so a paraphrase of what a definition does (even one with no doc comment) still surfaces it. Entities whose identifier shares a word with the query enter the candidate pool by token match alone.
Result bound: 'max_results' is 1-100 (default 5) and is enforced — a larger request is clamped to 100 and the reply says so. There is no pagination: when the bound is not enough, narrow the scope with 'kinds' / 'path' / 'repo_name' or refine the query rather than raising the limit.
Parameter guidance: 'query' should be 2-5 words describing functionality. Increase 'max_results' to 10-20 for broad discovery, keep at 5 for focused search. Include 'repo_name' in your first query to avoid cross-repository pollution.
Supports Java, Kotlin, C#, and TypeScript codebases.
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_hybrid_context"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional path filter. A repo-relative directory prefix ('src/api', matched on a path boundary so 'src/api-notes.md' never matches) or a glob ('src/**/*_test.rs'). Use 'list_files' first when you do not know the layout. Omit to search every file. | |
| kinds | No | Optional entity-kind filter. Accepts exact wire-format kinds (`'rust_function'`, `'markdown_section'`, `'kotlin_class'`, …) or aliases: `'definition'` (all functions/methods/types), `'callable'`/`'function'`/`'method'` (all callable kinds), `'class'`/`'type'`/`'struct'` (all type kinds). Comma-separate for multiple values. Omit to search all kinds. | |
| query | Yes | Search query describing what you're looking for (e.g., 'user authentication', 'API error handling') | |
| detail | No | Optional detail level: 'full' (default) renders file, FQN, signature, docs and relationship summaries; 'brief' renders one line per result (kind, file:line, caller/callee counts). Scan with 'brief', then expand the hit you need with find_callers / explore_file or a 'full' search. | |
| repo_name | No | Optional but HIGHLY RECOMMENDED: repository scope. Accepts a single repository name (`'my-repo'`), a comma-separated list (`'repo-a,repo-b'`), or `'all'` (or `'*'`) to query every indexed repository. If you know the repository you are working on, include it in your FIRST query to avoid mixed results from other indexed projects. Omit to search across all repositories. | |
| max_results | No | Maximum number of results to return (default: 5, max: 100). Requests above 100 are clamped to 100 and the reply says so — there is no cursor or pagination; to look past the bound, narrow the search with 'kinds' / 'path' / 'repo_name' or refine the query. | |
| include_tests | No | Optional: set to true to list callers and usages from test code in the samples. By default they are only counted ('N in tests'); the counts always include them. |