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.

Read-only reverse dependency lookup. Use this to find all code that references, calls, extends, or implements a specific entity. Answers 'who uses this code?' by querying the graph database. Differs from search tools by providing exact dependency tracking.

Usage: Use for impact analysis before refactoring or to detect dead code. Do NOT use this for semantic feature discovery—use 'search_hybrid_context' instead.

Matching is precedence-based: exact FQN (containing '.' or '::') → FQN suffix (Type.member) → exact name → signature prefix (accept(List) → name prefix (queries under 4 characters) → fuzzy substring (queries of 4+ characters). The first tier that matches wins, so an exact name never returns fuzzy noise. Queries shorter than 4 characters resolve by anchored name prefix instead of substring, avoiding substring noise on short strings. Pass a qualified name (Namespace.Type.Member) to disambiguate homonyms. Responses state which tier matched and flag fuzzy results explicitly.

Behaviour & Return: Read-only graph traversal with no side effects. Returns Markdown grouped by relationship type (Calls, Extends, Implements, References, Overridden by, Overrides) with exact file paths and line numbers. Each caller entry and each resolved target states its repository as (repo: name), so rows are attributable when multiple repositories are in scope. For JVM code (Java/Kotlin/Groovy) and C#, 'Overridden by' lists method implementations/overrides in subtypes and 'Overrides' lists the supertype methods a method implements/overrides. When the query resolves to more than one entity with that name (homonyms, e.g., 'find_nearest_entity_by_line' in orphans.rs vs rust.rs), results are grouped by target entity showing which specific target each caller references — even when only one of the homonyms has callers. Each caller entry includes: name, kind, file_path:line_number, and signature. When multiple targets exist, each group shows the target's location and signature.

Entity-kind scope: target resolution is code-only by default — documentation, configuration, build-system and Kubernetes/Helm metadata (markdown_section, config_property, build_dependency, cargo_package, project_identity, k8s_*, helm_*, …) can never be presented as resolved targets. When the filter removed matches, the response says so ('Non-code matches hidden — N entities …'), never silently. Pass kinds='all' (or '*') to disable the filter, or a comma-separated allow-list of exact kinds/aliases ('callable', 'config', 'docs', 'rust_function', 'build_dependency', …) to scope resolution explicitly. The response's resolution.kind_filter field states which scope applied ('code_default', 'any', 'explicit').

Relationship coverage: the buckets cover every edge type the pipeline produces — Calls, Extends, Implements, References, Macro calls (MACRO_CALLS), DOM references (JS → HTML id), CSS class usage (JS → CSS class), script/stylesheet imports, and the VCL edges (uses backend/probe/acl, includes, imports vmod, declared-unused) — plus Overridden by / Overrides.

Truncation & completeness: the queried name is first resolved to concrete targets (capped at 25 by default). When more targets match than fit the cap, the response states 'Truncated — N targets matched; showing the first M by FQN' and 'Counts below are partial — they cover only the M of N targets shown', so bucket counts are never mistaken for the complete impact set. Raise 'max_targets' (up to 500) to retrieve more targets when the notice reports truncation.

Parameter guidance: 'entity_name' supports exact names or signature fragments (e.g., 'handleRequest' or 'handle(Request'). Include 'repo_name' to filter results to the specific codebase being analyzed.

Supports Java, Kotlin, C#, Rust, and TypeScript codebases.

Read-only file anatomy inspection. Use this to list all classes, methods, and properties within a specific source file without reading its entire contents. Provides a structural bird's-eye view of a file, showing entity signatures and docstrings to quickly grasp a module's layout.

Usage: Use AFTER identifying an interesting file via 'search_hybrid_context' to understand its available methods, or before modifying a file. Do NOT use this for searching across multiple files.

Behaviour & Return: Read-only operation. Returns a Markdown-formatted outline of the file's entities, grouped by type (Classes, Methods, Interfaces, Constants, etc.), including line numbers for direct editor navigation. Attribute-usage markup references (html_class, html_id) are summarized in a separate section by default to avoid inflating code lists; set include_markup to true to list them in full. No side effects.

Path handling: file_path should be a repo-relative path (e.g. 'src/services/user.ts'). Absolute paths under your local checkout are also accepted; the tool strips the known local root automatically. The returned file_path is normalized to the same repo-relative form regardless of how it was queried. If the query is ambiguous across multiple repositories, the answer includes an 'ambiguous_path_candidates' list — retry with a longer path or pass repo_name.

Parameter guidance: 'file_path' must be a relative or absolute path to a valid source file. Include 'repo_name' if the file path might be ambiguous across multiple indexed repositories. Set 'include_markup' to true to expand attribute-usage markup tokens.

Supports Java, Kotlin, C#, and TypeScript codebases.

Read-only listing of the files an indexed repository carries, with entity counts and deterministic order. Answers 'list every file under src/hooks' or 'which files live in src/api/**' without prior path knowledge.

Usage: Use this BEFORE 'search_hybrid_context' when you do not know the codebase layout; then pass the same prefix to the search's optional 'path' parameter to scope results to those files. Do NOT use this to enumerate entities — use 'explore_file' on a file from this listing for its anatomy.

Behaviour & Return: Read-only query with no side effects. Returns a Markdown table with columns: REPOSITORY, FILE, ENTITIES, ordered by (repository, path). When output exceeds 2000 files, the table displays the first 2000 matches alongside a truncation notice stating the exact total when known, or an explicit lower bound when the scan stopped early. When nothing matches the prefix, returns 'No indexed files matched the given path'.

Parameter guidance: 'path' is optional. PREFERRED: a repo-relative directory prefix (e.g. 'src/api') matched on a path boundary, or a glob ('src/**/*_test.rs'). Prefixes and globs page all indexed files in pages with per-page boundary filtering without dropping candidates. Absolute paths under the local checkout are accepted and normalized like 'explore_file'. Omit to list every indexed file (capped; the reply notes truncation).

Parameter guidance: 'repo_name' scopes the listing. Accepts a single repository name or a comma-separated list; include it when several indexed repositories may share path shapes.

Supports all languages indexed by knot.

Read-only cross-repository dependency graph lookup. Shows which repositories depend on each other via build system declarations (Maven, Gradle, Cargo, npm, NuGet). Answers 'which repos does this repo depend on?' and 'which repos depend on this repo?'.

Usage: Use BEFORE cross-repo analysis to discover which other indexed repos are available for call tracing. Use reverse mode for impact analysis before making breaking changes in shared libraries.

Behaviour & Return: Read-only graph traversal with no side effects. Returns a JSON array of repository names. Empty results mean no DEPENDS_ON relationships exist for that repo. Empty lookups are explained in the response text with a three-way classification: declares-but-resolves-without-edge (stale graph, re-index hint), declares-but-nothing-resolves (not indexed), or nothing declared; the reverse direction names consumers that declare the repo without an edge yet.

Parameter guidance: 'repo_name' is required and must match the name used during indexing. 'max_depth' defaults to 3 (1 = direct only) and applies to both directions — in reverse mode it follows dependents transitively. 'reverse' toggles between forward and reverse dependency lookup.

Supports all build systems indexed by knot: Maven, Gradle, Cargo, npm, NuGet (.csproj + Central Package Management via Directory.Packages.props). C# repos that previously reported build_system: "none" now report "nuget" on re-index; knot-indexer --clean is recommended for immediate effect.

Read-only listing of all indexed repositories with optional name filtering. Shows repository metadata including entity count, file count, build system, and primary language. Answers 'what codebases have I indexed?' and 'which repositories match this name?'.

Usage: Use this tool FIRST to discover available codebases before searching or exploring. Once you know the repository name, switch to 'search_hybrid_context' for semantic search, 'find_callers' for reverse dependency lookup, 'explore_file' for file anatomy, or 'list_repo_dependencies' for cross-repo dependency graphs. Do NOT use this tool to search for code entities — use 'search_hybrid_context' instead.

Behaviour & Return: Read-only query with no side effects. Returns a Markdown table with columns: REPO, BUILD SYSTEM, LANGUAGE, FILES, ENTITIES. When no repositories match the filter, returns 'No repositories found.'

Parameter guidance: 'filter' is optional. When provided, only repositories whose name contains the filter string are returned (case-insensitive substring match). Omit to list all indexed repositories.

Supports all languages and build systems indexed by knot.