Skip to main content
Glama
raultov

knot

by raultov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Hybrid

Hybrid semantic + structural search

search_hybrid_context
Read-onlyIdempotent

Find code by meaning, not just keywords. Combines semantic embeddings with graph relationships to surface relevant files, signatures, and cross-repo dependencies from natural language queries.

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.

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathNoOptional 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.
kindsNoOptional 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.
queryYesSearch query describing what you're looking for (e.g., 'user authentication', 'API error handling')
repo_nameNoOptional 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_resultsNoMaximum 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.9.6
    • addedInput schema / properties / kinds
      Added value: +{
+  "description": "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.",
+  "maxLength": 255,
+  "minLength": 1,
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum number of results to return (default: 5)"New value: +"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."
    • changedInput schema / properties / max_results / maximum
      Previous value: -20New value: +100
    • addedInput schema / properties / path
      Added value: +{
+  "description": "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.",
+  "maxLength": 500,
+  "minLength": 1,
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Changed2 schema fields changedv1.9.4
    • changedInput schema / properties / max_results / type
      Previous value: -"integer"New value: +[
+  "integer",
+  "null"
+]
    • changedInput schema / properties / repo_name / type
      Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
  3. Changed1 schema field changedv1.8.1
    • changedInput schema / properties / repo_name / description
      Previous value: -"Optional but HIGHLY RECOMMENDED: repository name to filter results to a specific codebase (e.g., 'my-java-repo'). If you know the repository you are working on, include this in your FIRST query to avoid mixed results from other indexed projects. Omit only to search across all repositories."New value: +"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."
  4. Addedv1.4.0
  5. Removedv1.3.8
  6. Added
  7. Removedv1.3.2
  8. Addedv1.2.8
  9. Removedv1.2.7
  10. Addedv0.8.4
  11. Removedv1.0.0
  12. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, but the description adds substantial context: no side effects, clamping behavior on max_results, absence of pagination, ranking kind-awareness, recall contract, and the prerequisite server/database setup. This goes far beyond what annotations convey and is consistent with them.

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

Conciseness3/5

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

The description is comprehensive but quite lengthy, with many distinct sections (prerequisite, behavior, usage, ranking contract, recall contract, result bound, parameter guidance, supported languages). While each section earns its place for a complex tool, the overall length dilutes focus. It is well-structured with headers and emoji but could be tightened without losing critical information.

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 hybrid search tool with no output schema, the description covers prerequisites, return format, ranking, recall, result bounds, parameter tuning, and language support. The agent has everything needed to invoke it correctly and interpret results, including explicit exclusions (no pagination, clamp behavior).

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

Parameters4/5

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

Schema coverage is 100% so baseline is 3, but the description adds practical guidance beyond the schema: recommends 2-5 word queries, suggests max_results ranges for broad vs focused discovery, and explains path boundary matching and glob usage. This meaningfully supplements the schema.

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 clearly states it is a read-only semantic and structural code search combining vector embeddings with graph analysis, and explicitly contrasts itself with find_callers for usage-of-a-function. The verb+resource+method is specific and unambiguous.

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?

Explicitly tells the agent to use this as the first step for unfamiliar code or architectural discovery, and gives a concrete 'do NOT use' with the alternative tool (find_callers). Also includes parameter guidance (query length, max_results values, repo_name) and a ranking contract that governs result interpretation.

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