Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codegraph who calls Invoice.total and which tests cover it?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A code knowledge graph you can query from an agent. Index a repository once, then ask structural questions — who calls this, what breaks if I change it, which tests cover it, what does the architecture look like — through an MCP server or a CLI, instead of grepping and reading whole files.
Supports Python (stdlib ast) and JavaScript / TypeScript (tree-sitter).
Everything lives in one SQLite file under .codegraph/ in the repo you index; there is
no daemon, no embeddings service, and no network access.
Agents burn tokens re-discovering the same facts about a codebase: opening files to find
callers, tracing imports by hand, guessing which tests matter. A graph answers those in a
few hundred tokens with exact path:line locations, and turns a diff into a ranked list
of "these symbols have many callers and no tests — look here first".
Related MCP server: rag-rat
uv pip install git+https://github.com/mooyee0929/codegraph-mcp
# or, from a clone
uv pip install -e ".[dev]"Requires Python 3.11+.
codegraph index # build or refresh .codegraph/graph.db (incremental)
codegraph search "invoice total" # keyword search over names, signatures, docstrings
codegraph query callers_of Invoice.total
codegraph query tests_for pkg.billing.charge
codegraph impact Invoice.rate --depth 3
codegraph review # risk-ranked symbols touched by the working-tree diff
codegraph review --base main --context
codegraph arch # languages, hubs, entry points, orphans, external deps
codegraph dead # callables nothing references
codegraph show charge # print a symbol's source with line numbersEvery command accepts --root <dir> (default: cwd) and --json.
Targets can be a full qname (pkg.billing.Invoice.total), a bare name when it is unique
in the repo (total), a suffix (Invoice.total), or a location (pkg/billing.py:10).
Query patterns: callers_of, callees_of, imports_of, imported_by, tests_for,
subclasses_of, defines, defined_in.
codegraph-mcp --root /path/to/repo # stdio transportClaude Code:
claude mcp add codegraph -- codegraph-mcp --root /path/to/repoor in .mcp.json:
{
"mcpServers": {
"codegraph": { "command": "codegraph-mcp", "args": ["--root", "."] }
}
}Tool | What it answers |
| Build or refresh the graph. Incremental by content hash. |
| Row counts and database location. |
| Full-text search over qname, name, signature, docstring. |
| One symbol with all incoming and outgoing edges. |
| Trace one relationship (see patterns above). |
| Direct + transitive callers, importing modules, covering tests. |
| Risk-ranked symbols overlapping the git diff. |
| Source snippets plus callers and tests for each symbol. |
| Languages, packages, hub functions, entry points, orphans, external imports. |
| Callables with no callers, tests or subclasses. |
A typical review turn: detect_changes_tool → pick the top few by risk →
get_review_context on those qnames → get_impact_radius on anything with high fan-in.
source files ──parse──▶ nodes + edges ──store──▶ SQLite (+FTS5)
│ ▲
python: ast │ │ link
js/ts: tree-sitter │
└──▶ unresolved edges ("helper") ───┘ unique-name resolution,
test-coverage inferenceNodes are modules, classes, functions and methods, keyed by a dotted qname derived
from the file path (pkg/billing.py → pkg.billing, web/routes/index.ts → web.routes).
Edges are defines, imports, calls, inherits and tests. Parsers resolve what
they can from the file's own import table (from pkg import models; models.save() →
pkg.models.save, this.rate() → the enclosing class). Anything else is stored as a
bare name and upgraded by the linker when exactly one definition with that name exists
in the repository. Ambiguous names stay unresolved rather than guessed, and the CLI marks
them.
Risk in review is a small additive score: many callers, no covering tests, high
fan-out, large hunks. It is meant to order your attention, not to judge the change.
Incremental indexing hashes file contents; unchanged files are skipped, deleted files are removed, and the link pass re-runs only when something changed.
No type inference. self.client.send() and obj.method() resolve only when the
method name is unique across the repo and not a common builtin name (get, run,
send, ...). Until then they show as *.send and are flagged unresolved.
Dynamic dispatch, decorators that rewrite functions, getattr, and re-exports are
invisible.
JS default imports bind to the module qname, so def.run() becomes <module>.run.
One repository per database; monorepos work but qnames are rooted at the index root.
uv venv && uv pip install -e ".[dev]"
uv run pytest -q
uv run ruff check . && uv run mypy codegraphThe test-suite indexes a small fixture repository under tests/fixtures/sample_repo
and checks parsing, linking, queries, diff analysis, the CLI and the MCP tool surface.
MIT
Risk-ranked symbols touched by the current diff (working tree vs HEAD, or base..HEAD when base is given).
| Name | Required | Description | Default |
|---|---|---|---|
| base | 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. It does disclose the comparison semantics (working tree vs HEAD vs base..HEAD), which is the key behavioral detail for a diff tool, but it omits whether the operation is read-only, what the risk ranking is based on, and any side effects or auth requirements.
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?
One sentence, front-loaded with the return value and immediately qualified by the two comparison modes. Nothing is wasted and the structure matches the two-case behavior.
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 format need not be explained, and the description covers both invocation modes of the single optional parameter. It is nearly complete for a one-parameter analysis tool, with only the read-only nature and sibling differentiation left implicit.
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 parameter 'base' has 0% schema description coverage, so the description must compensate. It does so adequately by explaining that supplying base switches the comparison range to base..HEAD, giving the parameter clear behavioral meaning beyond its bare name.
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 output (risk-ranked symbols) and the resource (the current diff), which is clear enough for an agent to understand what it returns. It does not, however, differentiate itself from closely related siblings such as get_impact_radius or get_review_context, which also analyze changes/impact.
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 parenthetical 'working tree vs HEAD, or base..HEAD when base is given' implicitly tells the agent which mode applies depending on input, which is useful context. But it never says when to prefer this tool over get_impact_radius or get_review_context, nor any prerequisites, so usage guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Callables with no callers, tests or subclasses. Candidates, not verdicts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | 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 it does disclose one meaningful behavioral trait: results are heuristic candidates with possible false positives, not confirmed dead code. It discloses nothing else — no scope of analysis, no indexing prerequisite, no cost or result-size behavior beyond the implicit limit.
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 terse sentences with no filler, and the identifying clause is front-loaded ahead of the caveat. Every word 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-value detail is legitimately omitted, and the candidate caveat covers the main interpretive risk. What is missing is context for a graph-analysis tool: whether the repo must be indexed first and how far the caller/subclass analysis reaches, which matters given siblings like index_repository_tool and graph_status.
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% and the single 'limit' parameter (default 50) is never mentioned in the description, so the agent gets no explanation of what it caps or whether it is a cap on returned candidates or on traversal. The parameter name is largely self-explanatory, which keeps this above a 1.
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 defines the exact target set — callables lacking callers, tests, or subclasses — which is specific enough that an agent can distinguish it from graph-query siblings like query_graph or get_impact_radius. It stops short of 5 because it is a noun phrase with no verb framing (e.g., 'find/list') and never explicitly contrasts itself with the other analysis 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?
'Candidates, not verdicts' implies how results should be treated (verify before acting), which is useful implied guidance. However, there is no statement of when to reach for this tool versus query_graph, get_impact_radius, or search_nodes, and no prerequisite about the repository needing to be indexed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Languages, top-level packages, hub functions, entry points and external deps.
| Name | Required | Description | Default |
|---|---|---|---|
| top | 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 full behavioral burden, and it discloses none: no indication that it is read-only, that an index/repository scope is required, or what the cost is. Listing output contents is largely redundant with the output schema. Significant behavioral gaps remain for a tool with zero annotation 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?
It is short, but it is a sentence fragment rather than a concise statement, so the brevity reflects under-specification rather than efficiency. There is no front-loaded statement of what the tool actually does.
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 re-explained, but the description still omits the essential context: what repository/scope it operates on and when an agent should pick it over the many sibling graph tools. For a tool in a dense sibling set, this is inadequate.
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 ('top', default 10) with 0% schema description coverage, and the description never mentions it or explains what is being counted/truncated. The description does not compensate for the schema's silence, leaving the parameter's meaning ambiguous.
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 is a bare noun list ('Languages, top-level packages, hub functions, entry points and external deps') with no verb, so it implies the tool summarizes repository architecture but never states it. It does not distinguish itself from siblings like query_graph or get_review_context. The content list is informative enough to be more than a tautology, but purpose is only inferable.
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 when-to-use, when-not-to-use, or alternative guidance at all. An agent cannot tell from the text whether this is the entry point before query_graph or a substitute for graph_status. Usage 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.
Blast radius of changing a symbol: direct and transitive callers, importers, tests.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| target | 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 yet only discloses what is traversed (direct and transitive callers, importers, tests). It does not state that the operation is read-only, whether it requires an indexed graph, or any cost/latency characteristics.
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?
A single compact sentence with no filler and the core concept front-loaded. It is arguably too terse for the amount of undocumented behavior, but as raw structure it is efficient.
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 re-explained, and the tool is simple (one required param). However, the depth parameter's semantics and any usage routing are left entirely to inference, leaving meaningful gaps.
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% for both parameters, and the description adds no parameter meaning. 'Changing a symbol' loosely hints that target is a symbol, but the crucial depth parameter controlling traversal extent is entirely undocumented in schema and description.
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 analysis verb and resource ('blast radius of changing a symbol') and enumerates the result categories (direct and transitive callers, importers, tests). It is distinctly identifiable from siblings like query_graph or find_dead_code, though it never names an alternative directly.
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 only implied by the concept of 'blast radius'; there is no explicit when-to-use, when-not-to-use, or reference to any sibling tool. An agent must infer that this is for pre-change impact assessment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up one symbol by qname, unique bare name, or path:line.
| Name | Required | Description | Default |
|---|---|---|---|
| target | 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 burden. It discloses that lookup is by exact qname, unique bare name, or path:line (a precision constraint), but says nothing about failure behavior for ambiguous bare names or missing symbols, and no output schema explanation is needed. Moderate disclosure only.
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?
One tight sentence, front-loaded with the verb and resource, with the list of accepted forms appended. No waste, though slightly terse given the naming ambiguity of 'target'.
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. For a single-param lookup tool the description covers the main need (accepted identifier formats) but omits error/ambiguity behavior and any sibling differentiation, leaving gaps for correct invocation.
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% and the single parameter is named just 'target'. The description compensates well by enumerating the three accepted identifier formats (qname, unique bare name, path:line), which is essential to using the parameter correctly.
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 (look up) and resource (one symbol), and reveals the accepted identifier forms. It does not name or contrast with siblings like search_nodes or query_graph, so an agent must infer when to prefer this over a search 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?
The accepted input forms imply usage (exact identifiers, not fuzzy search), which hints at when to use this vs search_nodes, but no when-to-use or exclusion guidance is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Source snippets plus callers and tests for the given symbols.
| Name | Required | Description | Default |
|---|---|---|---|
| qnames | Yes | ||
| context_lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It discloses the output contents (source snippets, callers, tests), which is useful, but omits whether the operation is read-only, how large outputs might be, or any other behavioral traits like rate limits or authentication needs.
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 phrase with zero wasted words. It is appropriately sized for a simple retrieval tool, though its brevity trades off against completeness elsewhere.
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?
Although an output schema exists (so return values need not be detailed), the description is incomplete for a 2-parameter tool with 0% schema coverage: it neither explains the qualified-name format for 'qnames' nor the meaning or effect of 'context_lines'. It also lacks any usage context, leaving the agent to guess when this tool is appropriate.
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 is the only source of parameter meaning. It vaguely implies 'qnames' are symbols but gives no format or semantics, and entirely ignores the 'context_lines' parameter (including its default of 2).
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 names the specific artifacts returned (source snippets, callers, tests) and the scope (for given symbols), which lets an agent distinguish it from siblings like get_node or query_graph. However, it does not explicitly contrast itself with any alternative tool, so it stays at 4 rather than 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 guidance on when to use this tool versus alternatives such as get_impact_radius or search_nodes. The phrase 'for the given symbols' implies a review context but does not state prerequisites, exclusions, or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Row counts and where the database lives.
| 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. Read-only/no-side-effect behavior is strongly implied by the nature of a status report, but the description never states it, nor mentions permissions, cost, or whether it triggers indexing. It adds no behavioral context beyond the bare content list.
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?
A single short sentence with no filler, and the most useful information (row counts) is front-loaded. It is a fragment rather than a well-formed statement, which slightly limits clarity, but nothing is wasted.
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?
With zero parameters and an output schema that documents the return values, the description only needs to orient the agent. Saying it reports row counts and database location is sufficient for a simple, no-argument status tool, though a hint about when to use it would round it out.
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, so there is nothing to document and the baseline of 4 applies. The description correctly does not attempt to explain any inputs.
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 names the resource ('the database') and the kind of information returned ('row counts', 'where the database lives'), so an agent can infer this is a status/introspection tool. However, it is a noun fragment with no verb and never states the action ('report'/'retrieve'), and it does not distinguish itself from siblings like get_architecture_overview or index_repository_tool. Purpose is inferable but vague.
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 call this versus alternatives, nor any prerequisites or exclusions. Usage is only implied by the name 'graph_status' (check database state before/after indexing or querying). No explicit context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index or refresh the repository graph. Incremental unless force=true.
| Name | Required | Description | Default |
|---|---|---|---|
| force | 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. It does disclose a real trait beyond the schema: default behavior is incremental, and force=true changes it, plus the tool both creates and refreshes the graph. However it omits cost/duration, whether the operation blocks, and any permission or destructive-rebuild warnings.
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 tight sentences with the core action and the key modifier front-loaded. Every clause earns its place and there is zero 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 described, and the tool is a simple single-parameter operation. Still, with zero annotations and zero schema descriptions, the definition leaves the agent without guidance on when indexing is warranted versus simply reading graph_status.
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 is the only source of meaning for force. "unless force=true" conveys that force triggers non-incremental behavior, which is useful, but it never states plainly what force does (full re-index) or its interaction with existing graph state.
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 pair (index/refresh) and resource (repository graph), which is clearly distinct from siblings like query_graph, graph_status, or detect_changes_tool. It does not explicitly name or contrast with a sibling, but the action itself is unambiguous.
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?
"Incremental unless force=true" implies the default usage pattern and when to flip to a full rebuild, but there is no explicit when-to-use/when-not guidance relative to siblings such as graph_status or detect_changes_tool, and no prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace one relationship. Patterns: callers_of, callees_of, imports_of, imported_by, tests_for, subclasses_of, defines, defined_in.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| pattern | Yes |
| 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 but only says 'Trace one relationship.' The verb 'trace' implies a read operation, but the description does not explicitly state safety, side effects, auth requirements, or rate limits.
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 brief and front-loaded with the core action, followed by a compact pattern list. It avoids wasted words, though the pattern list duplicates the schema enum rather than adding structure or explanation.
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 tool has two required parameters, no annotations, and an output schema. The description fails to explain what 'target' should contain and offers no usage context or behavioral details, leaving significant gaps for an agent to call the tool correctly.
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 for parameter meaning. It repeats the pattern enum values exactly as they appear in the schema and says nothing about the 'target' parameter, adding no semantic value and leaving a required parameter completely undocumented.
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 verb ('Trace') and a resource ('relationship'), and the pattern list clarifies the kinds of relationships available. However, it does not explain what is being traced from or to, leaving the core purpose somewhat vague, and it does not distinguish this tool from siblings like get_impact_radius or search_nodes.
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 description provides no guidance on when to use this tool versus alternatives. It only lists pattern values, which are already in the schema, and does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find functions, classes and modules by name, signature or docstring keyword.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query_text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full behavioral burden, yet it discloses nothing about matching behavior (substring vs regex vs ranking), result ordering, pagination, or read-only nature. Mentioning the three match surfaces helps slightly but leaves the operation's behavior largely opaque.
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?
A single clean sentence with the core purpose front-loaded and no wasted words. Efficient, though its brevity is also the source of the coverage gaps elsewhere.
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, and for a two-parameter search tool the description is minimally serviceable. However, with zero annotation coverage and no param documentation, an agent lacks enough to invoke it confidently (limit semantics, match/order behavior).
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 only partially does. It clarifies what query_text is matched against, but the 'limit' parameter (default 20) is entirely unexplained in both schema and description.
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 'find' and a concrete resource set ('functions, classes and modules'), and enumerates the match surfaces (name, signature, docstring keyword). This distinguishes it from get_node's single-node retrieval, but it never names an alternative sibling explicitly.
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?
No guidance on when to reach for search_nodes versus query_graph, get_node, or get_architecture_overview. The agent must infer usage from the verb alone; no exclusions or alternatives are given.
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.0detect_changes_toolfind_dead_codeget_architecture_overviewget_impact_radiusget_nodeget_review_contextgraph_statusindex_repository_toolquery_graphsearch_nodesScored across 10 tools
Each tool has a fairly distinct purpose: query_graph traces a single relationship while get_impact_radius computes transitive blast radius, and search_nodes vs get_node differ by fuzzy search vs exact lookup. The only mild overlap is get_review_context, which bundles callers and tests that also appear in get_impact_radius, but the added source snippets keep it differentiated.
Most tools follow a clean verb_noun snake_case pattern (query_graph, get_impact_radius, find_dead_code, search_nodes, get_node). Two outliers carry a redundant '_tool' suffix (detect_changes_tool, index_repository_tool) and graph_status is noun-only, which are minor deviations rather than a broken convention.
Ten tools is well-scoped for a code-graph analysis server, covering setup, exploration, and analysis without redundancy. Every tool earns its place across the indexing/query/analysis lifecycle.
The surface covers the full workflow: indexing, status, symbol search/lookup, relationship tracing, impact analysis, diff risk, review context, architecture overview, and dead-code detection. Minor gaps exist (e.g. no explicit index deletion or cross-repo management), but core lifecycles are well covered.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
