An MCP server that gives AI agents type-resolved Python navigation, backed by ty's language server. Definitions, references and call sites go through real type inference (imports, dependency-injected parameters, dataclass fields), not text grep.
ty is installed with the package, so all you need is
uv (or pipx):
uvx codenav-mcpRegister it with your MCP host. For Claude Code, from the project root:
claude mcp add codenav -- uvx codenav-mcpOr add it to a project .mcp.json (Claude Code) or .cursor/mcp.json (Cursor):
{
"mcpServers": {
"codenav": {
"command": "uvx",
"args": ["codenav-mcp"],
"env": {
"CODENAV_MCP_SOURCE_ROOT": "src"
}
}
}
}In Cursor, also set "CODENAV_MCP_WORKSPACE": "${workspaceFolder}", because
Cursor may start MCP servers with your home directory as the working directory.
Related MCP server: karellen-lsp-mcp
Start with the name-based tools:
Tool | Answers |
| What is this? Header, hover, definition and references in one call |
| What's in this file? (classes, methods, functions) |
| Who actually calls this function? (call hierarchy, not imports) |
| Which classes structurally implement this |
| Workspace symbol search by name (ranked, capped; optional |
| Which directory is being navigated, and why |
Then use the position tools once you have a path:line:col:
Tool | Answers |
| Type and docs at a position |
| Go to definition (resolves through injected parameters) |
| All usages across the workspace |
| ty type-check diagnostics for one file |
name and query are accepted as aliases on the name-based tools
(port_name / name / query on implementations). A missing or wrong
parameter gets a short hint back instead of a validation error. Dotted names
may nest (Outer.Inner.method). implementations also takes file_path to
pick one port when the name exists in several files, and counts inherited
members and dataclass/self.x fields toward a port's required names.
Positions are 1-indexed. column is a UTF-16 character offset (a leading
tab counts as one character).
Python only (.py / .pyi).
ty runsThe project's own .venv/bin/ty (.venv\Scripts\ty.exe on Windows), so
the ty version matches the project's pin and config.
The ty installed alongside codenav-mcp.
ty on PATH.
uvx ty server as a last resort.
Variable | Default | Purpose |
| unset: follows the client's MCP roots when they name a worktree of the same git repository, else | Pins the project root (never overridden). See the |
| whole workspace | Directory scanned for |
| none | Comma-separated directories (e.g. |
Python ≥ 3.11
Installed automatically: mcp,
ty,
mcp-nav-shared
webnav-mcp: the same kind of
navigation for JS/TS/HTML/CSS.
Design notes (Protocol conformance probe, positioning, output formats): docs/agent-tooling.md.
Source: github.com/illescasDaniel/codenav-mcp. From a
checkout: uv sync --group dev, then uv run codenav-mcp.
MIT. See LICENSE.
Who calls this function? Example: callers(name="create_user").
Narrower than references, since it leaves out imports and type-only usages and only lists actual call sites.
name resolves the same way as symbol_info (dotted Class.method accepted;
pass file_path to disambiguate a common name). query is accepted as an
alias for name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| query | No | ||
| file_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does so credibly: it discloses the resolution semantics ('resolves the same way as symbol_info', dotted Class.method accepted), how to disambiguate common names via file_path, and that `query` is an alias for `name`. It does not mention result limits or ordering, but the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The example is front-loaded immediately, followed by a tight scoping statement and then resolution details. Every sentence adds information; the only minor cost is the line-broken formatting that fragments the scoping sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. Combined with the resolution and aliasing guidance, the definition gives an agent enough to invoke the tool correctly; the absence of any note on result size or scope limits is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it documents `name` resolution rules, the `file_path` disambiguation role, and the `query` alias — covering all three parameters meaningfully. It lacks examples of what a dotted path looks like in practice, keeping it short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific question the tool answers ('Who calls this function?') with a concrete example, and explicitly differentiates from the sibling `references` by scoping to actual call sites and excluding imports and type-only usages. An agent can distinguish it from its siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The comparison to `references` gives clear selection context: use this when you want actual call sites rather than all references. It explains the narrower scope well, but does not explicitly state when not to use it or name other alternatives such as `implementations`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Go to the definition of the symbol at a position.
line and column are 1-indexed. column is a UTF-16 character offset
on the line (not a visual/display column): a leading tab counts as one
character.
Resolves through ty's type inference, so this works even when the call
site only has a typed parameter/attribute (e.g. services.some_method()
where services: AppServices is a constructor argument), not just
direct references to a name in scope.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | ||
| column | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does add real behavioral context: it discloses that resolution goes through ty's type inference and works even when the call site only has a typed parameter (the `services.some_method()` example). It does not discuss failure modes or what happens on an unresolved position, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly scoped paragraphs, front-loaded with the core action and immediately followed by the non-obvious offset semantics. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The description covers the action, the tricky parameter conventions, and the type-inference capability that distinguishes this tool's reach — the essentials for calling it correctly on a read-only LSP operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It documents `line` and `column` precisely (1-indexed, UTF-16 offset, tab counts as one character), which is exactly the semantics that matter for a position-based call. `file_path` is left unexplained, though it is self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("go to the definition of the symbol at a position"), which an agent can distinguish from read/list siblings like references or outline. It never explicitly names a sibling to route against, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by "the symbol at a position" — the agent infers it is a code-navigation lookup. But there is no when-to-use vs when-not, and no contrast with adjacent tools such as hover, symbol_info, or references, which is a clear gap for a navigation family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ty's type-check diagnostics (errors/warnings) for a single file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool returns type-check errors/warnings for a single file, which implies a read-only diagnostic operation, but it omits prerequisites, side effects, and whether the file must be saved or indexed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return values need not be explained. However, for a tool with no annotations and an undocumented parameter, the description should do more to state prerequisites and how it relates to sibling tools such as workspace diagnostics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter (file_path) with 0% schema description coverage. The description only says 'for a single file,' which minimally reinforces the parameter's meaning but adds no format, path-resolution, or required-state details to compensate for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Get), resource (type-check diagnostics), and scope (a single file), so an agent can immediately understand the core operation. It does not explicitly name a sibling alternative, but the single-file scope contrasts implicitly with the broader workspace tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this to obtain diagnostics for one file. However, the description gives no explicit when-to-use, when-not-to-use, or alternative tool guidance, and does not mention prerequisites such as whether the file must be open or the language server loaded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get type/documentation info for the symbol at a position.
line and column are 1-indexed. column is a UTF-16 character offset
on the line (not a visual/display column): a leading tab counts as one
character.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | ||
| column | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about the operation's nature (read-only vs mutating), permissions, or output. It only clarifies coordinate semantics, which belongs more to parameter semantics than behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with zero filler, front-loading the tool's purpose before the parameter disambiguation. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described, and the tricky coordinate params are covered. However, with no annotations and no usage context, the description stops short of fully equipping an agent to pick this over its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well for the non-obvious parameters: it states line/column are 1-indexed and that column is a UTF-16 offset where a tab counts as one character. It leaves file_path unexplained, but that param is largely self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (get) and resource (type/documentation info) tied to a symbol at a position, which matches the well-known IDE 'hover' concept. It is clear on its own but does not explicitly differentiate itself from sibling tools like symbol_info or definition, which could plausibly overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use hover versus symbol_info, definition, or references, nor any exclusions. The phrase 'at a position' loosely implies usage, but alternative selection is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find concrete classes that structurally satisfy a Protocol port.
Many hexagonal codebases define ports as Protocols that adapters never
subclass explicitly, so ty's own implementation/typeHierarchy return
nothing for them. This scans classes under SOURCE_ROOT (the whole
workspace by default; see CODENAV_MCP_SOURCE_ROOT) whose method names
cover the protocol's, then verifies each candidate with ty's real type
checker via an in-memory probe file (never written to disk) — so a
result means "assignable", not just "same method names". port_name
must itself resolve to a Protocol class; other classes' subclasses are
better found with references/symbol_info. name and query are
accepted as aliases for port_name. file_path narrows the port lookup
to one file when the name exists in several. Members inherited from
same-workspace base classes, and fields/properties declared by the port,
count when matching names. Directories listed in
CODENAV_MCP_EXTRA_SOURCE_ROOTS (e.g. tests) are scanned too; their
matches (test doubles) are listed under a separate heading.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| query | No | ||
| file_path | No | ||
| port_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses that scanning defaults to the whole workspace, is controlled by SOURCE_ROOT / CODENAV_MCP_SOURCE_ROOT and CODENAV_MCP_EXTRA_SOURCE_ROOTS, that verification uses an in-memory probe file never written to disk, and that test-double matches are reported under a separate heading. That is exactly the side-effect and result-interpretation context annotations would otherwise need to supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The key routing sentence is front-loaded and no sentence is filler — env vars, alias handling, and match semantics all earn their place. It is on the dense side at roughly eight sentences, but the length is justified by the zero-coverage schema and absent annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four undocumented parameters, no annotations, and a real type-checking workflow, the description covers scope, side effects, aliases, and result interpretation ('assignable', not just same method names). Return-value details are rightly omitted since an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: `port_name` must resolve to a Protocol class, `name` and `query` are documented aliases, and `file_path` is explained as narrowing port lookup when the name exists in several files. All four parameters gain meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a precise verb+resource: finding concrete classes that structurally satisfy a `Protocol` port. It explicitly contrasts itself against ty's own `implementation`/`typeHierarchy` and against `references`/`symbol_info`, so an agent can distinguish it from every relevant sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use condition (hexagonal codebases with Protocol ports that adapters never subclass, where `implementation`/`typeHierarchy` return nothing) and names the alternatives for the cases this tool is wrong for (`references`/`symbol_info` for ordinary subclass lookups, and the `file_path` escape hatch for ambiguous names).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What's in this file? Example: outline(file_path="src/app/services.py").
Indented outline (classes, methods, functions, with line numbers) of a Python file, so you can navigate a large file without reading it in full. Follow up with hover/definition/references at a listed line, or symbol_info by name.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the output shape (indented outline with line numbers) and the intended navigation workflow. However, it never states that the operation is read-only, how a missing/non-Python file is handled, or whether very large files are truncated, leaving real behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the core question ('What's in this file?') followed by a usage example, then the definition and next-step guidance. Every sentence carries information, though the rhetorical opening question is slightly less efficient than a direct statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter read tool with an output schema present, the description covers purpose, output form, and follow-up workflow adequately, so return values need not be explained further. Only the error/edge-case behavior is missing, which is a minor gap given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single file_path parameter has 0% schema description coverage, so the description does provide value via the concrete example 'outline(file_path="src/app/services.py")', which implies a workspace-relative path string. It does not explicitly state relative vs absolute path expectations or whether directories are accepted, so the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Indented outline ... of a Python file') and precisely names the returned artifact (classes, methods, functions with line numbers). It also distinguishes itself from siblings by positioning hover/definition/references and symbol_info as follow-ups rather than substitutes, so an agent can tell it apart from those tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for use ('so you can navigate a large file without reading it in full') and routes the agent to concrete alternatives for the next step ('follow up with hover/definition/references at a listed line, or symbol_info by name'). It stops short of an explicit when-not clause (e.g., don't use to search by name across a project), so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all usages of the symbol at a position across the workspace.
line and column are 1-indexed. column is a UTF-16 character offset
on the line (not a visual/display column): a leading tab counts as one
character.
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | ||
| column | Yes | ||
| file_path | Yes | ||
| include_declaration | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It provides useful operational detail about 1-indexed coordinates and UTF-16 column offsets, but it does not state that the tool is read-only, does not explain the effect of include_declaration, and gives no performance or side-effect context. The coordinate notes are helpful but incomplete behavioral coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded, and waste-free. The coordinate details in the second sentence are directly relevant and necessary because the schema has no parameter descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be explained. However, given 0% schema description coverage and no annotations, the description should ideally explain include_declaration and provide at least some usage positioning among siblings. It covers coordinate semantics well but leaves other important context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds important meaning for line and column, including 1-indexing and UTF-16 offsets, but does not explain file_path or include_declaration. The compensation is partial rather than complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Find all usages of the symbol at a position across the workspace.' An agent can understand the core operation. However, it does not explicitly distinguish this tool from siblings such as callers, implementations, or definition, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like callers, implementations, or definition. The description implies the operation but provides no context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the whole workspace for a symbol by name (class, function, method, etc.).
Use this to find a symbol's file/position first, then pass that position
to definition/references/hover for precise, type-resolved navigation.
Returned positions point at the identifier name (not the class/def
keyword) and use the same character-offset column convention as the
other tools. Results include a SymbolKind label and are capped.
name is accepted as an alias for query. Narrow broad queries with
kind (SymbolKind labels, comma-separated: class, function,method,
interface, ...) and path (workspace-relative prefix such as src/,
or a glob such as src/**/*.py). Production code ranks before tests.
Loose fuzzy hits whose names don't contain the query are summarised as a
count when real matches exist; pass fuzzy=true to list them too.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| name | No | ||
| path | No | ||
| fuzzy | No | ||
| query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so richly: results are capped, loose fuzzy hits are collapsed to a count unless `fuzzy=true`, production code ranks before tests, positions point at the identifier name rather than the keyword, and columns use the shared character-offset convention.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and organized purpose-first, then return semantics, then parameter guidance. It is a touch long and dense with several independent facts packed into single sentences, but every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required, and the description covers behavior, parameter meaning, and the sibling workflow well. The minor gap is that with zero required parameters it never states that at least one of `query`/`name` must be supplied, leaving a degenerate no-argument call plausible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it documents every parameter: `name` as an alias for `query`, `kind` accepting comma-separated SymbolKind labels with examples, `path` accepting a workspace-relative prefix or glob (with an example), and `fuzzy` toggling fuzzy-hit listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope ('Search the whole workspace for a symbol by name (class, function, method, etc.)') and explicitly positions itself in a workflow relative to siblings (definition/references/hover). An agent can tell this is the discovery step versus the precise-navigation tools without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use rule ('find a symbol's file/position first, then pass that position to definition/references/hover for precise, type-resolved navigation') and names the alternative tools with the condition that selects them. It also tells the agent how to narrow overly broad searches via `kind` and `path`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is X and where is it used? Example: symbol_info(name="UserService.create_user").
One-call summary for a name: header, hover text, definition, and references grouped by file — the usual first lookup instead of chaining search_symbol → hover → definition → references by hand.
name is a symbol name, or a dotted Class.method to resolve a specific
method when the plain name is ambiguous. Pass file_path (relative to the
workspace root) to disambiguate when several symbols share a name
elsewhere in the workspace; if it's still ambiguous, the candidates are
listed back so you can retry with a narrower name or file_path.
query is accepted as an alias for name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| query | No | ||
| file_path | No | ||
| include_references | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, and it does disclose the ambiguity fallback behavior (candidates are listed back so you can retry). It does not state safety/read-only nature, but for a pure lookup tool that is low risk, and the output schema covers the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a question and a concrete example, then the one-call framing, then parameter notes. Every block earns its place, though the description is slightly longer than needed given the output schema already documents the return payload.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param lookup tool with an output schema and no annotations, the description covers purpose, alternatives, and three of four parameters, including disambiguation behavior. The undocumented include_references flag is the only meaningful omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate; it explains name vs. dotted Class.method, the query alias, and file_path semantics relative to the workspace root. It leaves include_references (default true) entirely undocumented, which is the one remaining gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: a one-call summary for a symbol name returning header, hover text, definition, and references grouped by file. It explicitly names the sibling chain (search_symbol → hover → definition → references) that it replaces, so an agent can distinguish it from those tools without reading any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames itself as 'the usual first lookup instead of chaining' the alternatives, and describes the ambiguity escalation path (retry with a narrower name or file_path). When-to-use and how-to-recover are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which directory is codenav navigating, and why? Use when results look like they come from the wrong checkout/worktree.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the diagnostic scenario the tool serves but never states whether the operation is read-only or mutates state (e.g., switches workspace), nor what permissions are needed. The interrogative phrasing leans read-only but the ambiguity is unresolved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the purpose question is front-loaded and the usage condition follows. The interrogative framing is slightly informal for a tool description but wastes no space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value details need not be in the description. For a zero-parameter, near-certainly read-only diagnostic, purpose plus trigger condition is nearly enough; only the read-only/side-effect question is left open.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to compensate for. Baseline of 4 applies for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys that the tool reports which directory codenav is navigating and the rationale for it, which separates it from the navigation siblings. However, the tool name 'workspace' is generic and the description is phrased as a question rather than a clear verb+resource statement, so an agent has to infer whether this is a getter, a setter, or a config inspector. Purpose is discernible but not crisply stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit triggering condition: 'Use when results look like they come from the wrong checkout/worktree.' This tells the agent exactly when to reach for it over the navigation siblings. It does not name a specific alternative, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1callersdefinitiondiagnosticshoverimplementationsoutlinereferencessearch_symbolsymbol_infoworkspaceScored across 10 tools
symbol_info explicitly overlaps with hover, definition, references, and search_symbol by providing a one-call summary, which could confuse an agent choosing between name-based and position-based lookups. However, the descriptions clearly delineate position-based precise navigation from name-based summary and distinguish callers from references. Overall mostly distinct with only minor intentional layering.
Most tools are lowercase snake_case nouns describing the returned information (workspace, diagnostics, hover, definition, references, outline, callers, implementations). search_symbol and symbol_info deviate slightly with verb_noun or noun_noun phrasing, but the set remains predictable and readable. Minor inconsistency, not chaotic.
Ten tools is well-scoped for a code navigation server, and each tool earns its place by covering a distinct navigation need. No tool appears redundant or extraneous at the count level.
The surface covers core navigation operations: symbol lookup, definition, references, hover, outline, callers, implementations, and file diagnostics. Minor gaps exist, such as no workspace-wide diagnostics, no callees (outgoing call hierarchy), or rename, but these are workaroundable and not central to navigation.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Search @imqueue docs and scaffold typed services & clients from your AI coding agent.
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
