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.

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). A trailing parameter list of types addresses one overload: 'Foo.bar(int, int)' resolves 'Foo.bar' through the tiers above and keeps only the overloads whose declared parameter types match (simple type names; generic arguments compared only when written; 'name: Type' accepted); when none matches, the response lists the declared overloads. Overloads sharing an FQN are labelled by their parameter list in the target list and '### Target:' headers. 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, Dispatched calls) with exact file paths and line numbers. When every reference and target belongs to one repository, the 'Found N reference(s)' line names it once as (repo: name); otherwise each caller entry and each resolved target states its repository, 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. 'Dispatched calls' lists callers bound to an override or to a supertype method of the target (dynamic dispatch), each under the method it is statically bound to, so an interface method called only through its implementation is never reported as unused. 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 is one line: name, kind, file_path:line_number and, when it is not empty, its signature. When multiple targets exist, each group shows the target's location and signature. References made from test code (test files, Rust #[cfg(test)]) are included in every count but listed only with include_tests=true; each group then ends with '+N in tests'. A file's <module> row (its import) is folded into the other rows of that file.

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, the VCL edges (uses backend/probe/acl, includes, imports vmod, declared-unused) and HTTP routes (ROUTES_TO: the endpoint serving a handler) — plus Overridden by / Overrides / Dispatched calls, and 'HTTP callers (heuristic: client call → endpoint)': the HTTP client calls (OpenFeign, MicroProfile REST Client, Spring @HttpExchange, RestTemplate, WebClient, RestClient; test code excluded) of any indexed repository linked to the target endpoint or handler by HTTP_CALLS — matched by verb, path, service name and context path, never linked when several endpoints match equally well.

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 catalogue of the HTTP endpoints the indexed repositories serve, each with the handler method it routes to. Answers 'which endpoints does this service expose?' and 'which handler serves GET /api/owners/42?'.

Coverage: Java and Kotlin handlers annotated for JAX-RS (class/method @Path + @GET/@POST/@PUT/@DELETE/@PATCH/@HEAD/@OPTIONS) or Spring MVC (class @RequestMapping + @GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping or @RequestMapping(method = ...)). Paths join the class-level and method-level paths, resolve string constants declared in the same file, and drop path-variable patterns ('{id: [0-9]+}' → '{id}'); a part that cannot be resolved is shown as ''. Paths are relative to the application: the context path (server.servlet.context-path, @ApplicationPath) is not applied to the listed paths. 'ANY' marks a @RequestMapping without 'method'. Declarative HTTP clients (@FeignClient, @RegisterRestClient, @HttpExchange interfaces) are not endpoints: their methods, like RestTemplate / WebClient / RestClient call sites, are 'http_client_call' entities, linked to the endpoints they hit.

Usage: Use this for API-surface questions; then run 'find_callers' on the handler FQN for its callers, or on an endpoint name ('GET /api/owners/{id}') for the handler it routes to. Every endpoint is also an 'http_endpoint' entity reachable from 'search_hybrid_context' and 'explore_file', and a handler's 'find_callers' lists the endpoints routing to it under 'HTTP routes' and the client calls hitting them under 'HTTP callers (heuristic)'.

Behaviour & Return: Read-only query with no side effects. Returns a Markdown table with columns: Method, Path, Handler, Location, Repository, ordered by (repository, path, method). At most 1000 rows; the reply states when more matched. When nothing matches, returns 'No HTTP endpoints matched.'.

Parameter guidance: 'method' is optional and case-insensitive ('GET'); 'ANY' endpoints match every method. 'path' is optional and matches segment by segment as a prefix ('/api/owners' matches '/api/owners/{id}' but not '/api/ownership'); an endpoint's '{variable}' segment matches any concrete segment, so a concrete URL path finds its endpoint. 'repo_name' scopes the catalogue.

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.