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-mcp Show me the file skeleton for src/utils.ts"
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.
Local MCP server that gives Claude Code (CLI and the VS Code extension) a queryable model of your codebase — where things are defined, who calls what, what depends on what, and what was decided in earlier sessions. Without it the agent rediscovers your architecture every session through grep and file-by-file reading; with it, structural questions get structural answers:
Safer changes — before touching a function the agent sees its blast
radius (analyze_impact), every call site (find_callers), every mention
(find_references) and every dependent module (who_imports), instead of
editing whatever grep happened to surface.
Faster orientation — one repo_map call maps the project by import
centrality; find_symbol and semantic_search ("where is auth token
validated") land directly on the right code.
Continuity — save_note / recall_notes carry decisions and gotchas
across sessions, per repository.
Cheaper exploration — as a consequence of the above the agent reads
signatures instead of whole files (file_skeleton, read_symbol), and a
transparent proxy compresses conversation history at the wire level.
usage_stats reports the measured savings.
100% portable: pure JavaScript + WASM grammars. No node-gyp, no native
compilation. npm install works identically on Windows, macOS and Linux.
Understanding & navigation
Tool | What it does |
| Project map: languages, counts, key files by import centrality; |
| Locate a function/class/method/type definition by name, repo-wide |
| Find code/notes by meaning ("where is auth token validated") |
Change safety
Tool | What it does |
| Transitive callers (blast radius) before changing a function |
| Every mention of an identifier — call sites marked |
| Direct dependents of a module (reverse import graph) |
Focused reading
Tool | What it does |
| Imports + all signatures of a file, no bodies (10–50× fewer tokens) |
| Read the full source of one symbol without reading the file |
Memory & operations
Tool | What it does |
| Persistent per-repo notes that survive sessions |
| Force incremental or full re-scan |
| Calls per tool + tokens saved; |
Supported languages: JavaScript, TypeScript, TSX, Python, Go, Rust, Java,
Ruby, C, C++, C#, PHP, GDScript. Files the indexer cannot extract are counted
and reported by repo_map, so partial coverage is always visible.
Related MCP server: PruvaGraph MCP Server
Requires Node.js ≥ 20 and Claude Code. Identical on Windows / macOS / Linux:
git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install # registers in Claude Code (user scope)That's it — the install command runs claude mcp add for you, and the
server works in the CLI and the VS Code extension (they share MCP
configuration). Verify with claude mcp list or /mcp inside Claude Code.
The server indexes the directory it is started in (Claude Code starts MCP
servers in the project directory), or the path given via --root /
CODEGRAPH_ROOT. To limit it to a single project instead of user scope, add
.mcp.json to that project:
{
"mcpServers": {
"codegraph": {
"command": "node",
"args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
}
}
}To remove: node bin/codegraph-mcp.js uninstall.
No CLAUDE.md edits or prompt tweaks are needed: the server ships its usage
guidance ("run analyze_impact before changing a function, find_symbol
instead of grep, file_skeleton before reading a file, …") through the MCP
instructions field, which Claude Code injects into the agent's context
automatically on connect. Install, register, done.
Instructions are advice, and the agent's habit is grep -rn + cat. Measured
over four weeks on a Django repo, codegraph got 8 calls against ~2200 Bash
reads and greps of indexed source. So install also registers a
PreToolUse hook on Read and Bash in ~/.claude/settings.json. It works
from .codegraph/index.json alone (no server round-trip) and denies a call
only when the graph can answer better, telling the agent which tool to use:
Call | Verdict |
| deny → |
| same |
| deny → |
| deny → |
recursive | deny → |
recursive grep for a fragment (5+ chars) of known symbol names | deny → |
small window inside a class, wide sweep, head of file, | pass |
grep for a regex, a string, a name the index does not know, or on one file | pass |
anything outside a repo with | pass |
CODEGRAPH_MIN_LINES changes the threshold. uninstall removes the hook
together with the MCP registration.
The range and definition rules exist because the first version let the
agent's real habit through untouched: grep for class X with -A 25, then
sed -n 256,300p on the line numbers it found — a symbol read by hand, in
two calls, with no hit on the graph. Every allowed pattern is in the evals
so the hook stays quiet where grep is genuinely the right tool.
The decisions are pinned by evals/hook-evals.json:
real-looking Read / Bash calls with the expected verdict, run against
evals/fixture by node evals/run.js (and by npm test).
When the hook blocks or passes something it should not, add the case there.
codegraph-mcp bench measures, on the real index of a repo, what the agent
pays for a whole-file read against what codegraph hands it instead — the
file_skeleton text, then the source of one symbol. Same chars/4 estimate as
usage_stats, so live counters and benchmark are comparable. On a 350-file
Django backend:
All indexed files with symbols: 353 files
whole file 486,699 tokens
file_skeleton 88,264 tokens (-82%)
skeleton + one symbol 159,126 tokens (-67%)
Files above the hook threshold (> 300 lines): 42 files
whole file 285,368 tokens
file_skeleton 41,540 tokens (-85%)
skeleton + one symbol 48,458 tokens (-83%)Per-file rows for the largest files follow; the full result lands in
.codegraph/benchmark.json (--no-write to skip).
The MCP tools above save tokens only when the agent chooses to use them. The proxy layer works the other way — like ContextForge, it sits between Claude Code and the Anthropic API and compresses traffic regardless of agent behavior. Nothing in a conversation is ever "unloaded" by Claude Code itself: a file read, a test log, a command output stays in the history and is re-sent with every request. The proxy is the one place that can shrink it:
History deduplication: when the conversation contains identical tool results (the same file read twice, repeated command output), every occurrence after the first is replaced with a short stub before the request leaves your machine. The first occurrence stays verbatim, so the model loses nothing it could actually use — and the prompt-cache prefix is preserved (only the new tail is ever rewritten, so dedup never causes cache misses on old turns).
Stale-read skeletonization: when a file was read, edited, and read
again, the older full copy in history is replaced by its tree-sitter
signature skeleton (imports + declarations with line ranges); the newest
read always stays verbatim. A read is a Read tool call or a Bash
cat file / sed -n a,bp file — in practice most reads are Bash, and
measured over a month they were three quarters of all tool output. A stale
partial read becomes a one-line stub; non-code files fall back to head+tail
truncation. Transforms are pure functions of the content, so repeated
requests produce identical bytes and the prompt cache re-stabilizes after
a single rewrite.
Stale-output truncation: when the same Bash command ran several times (test reruns, tailing a task log), every output except the latest keeps only its first 15 and last 10 lines.
Prompt grounding: your message is transformed before it reaches the
model — the safe way. The words are never rewritten; instead the proxy
appends a clearly-labeled block of verifiable facts about the identifiers
the message mentions (kind, file:lines, one-line doc from the symbol
graph). The model starts oriented instead of spending tool round-trips
discovering the same facts. Only exact-case matches ground, only the newest
message gets a fresh block, and blocks are memoized so history stays
byte-stable for the prompt cache.
Auth headers pass through untouched (API key or OAuth). Anything the proxy cannot parse is forwarded verbatim. Streaming (SSE) is piped through.
It is on by default after install. The install command sets
ANTHROPIC_BASE_URL=http://127.0.0.1:3210 in ~/.claude/settings.json (CLI
and VS Code extension alike; an existing foreign value is left alone), and
the MCP server keeps the proxy alive: on start and every 30 s it checks the
port and spawns a detached proxy when nothing answers. Whenever Claude Code
runs, its MCP server runs, so the proxy does too. The proxy exits after a day
idle. CODEGRAPH_NO_PROXY=1 disables the supervisor, CODEGRAPH_PROXY_PORT
moves the port, uninstall removes the env entry.
Manual alternatives:
codegraph-mcp wrap # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210 --idle 3600 # run the proxy standalone (--idle: exit after N idle seconds)Cumulative savings are tracked in ~/.codegraph/proxy-stats.json, printed
on proxy start and served at GET /codegraph-proxy/health.
node bin/codegraph-mcp.js index # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj # index another directory
node bin/codegraph-mcp.js bench # whole file vs file_skeleton / read_symbol, in tokens
node bin/codegraph-mcp.js dashboard # HTML report, opens in browser
node bin/codegraph-mcp.js map # interactive architecture map
node bin/codegraph-mcp.js # start stdio MCP server (cwd)The architecture map (.codegraph/map.html) is a layered, C4-style view of
the repo, fully derived from the index:
Overview — subsystem cards (top-level directories) with weighted import edges between them, plus auto-derived starting points (hub, entry point, largest module);
Subsystem — the files of one directory with their import edges and collapsed neighbor subsystems; click a file to trace dependents and dependencies, click again to drill in;
File — its symbols with intra-file call arrows, importers and imports as navigable columns.
Every level narrates purpose, not just structure: descriptions are pulled
from the code's own documentation — module docstrings and header comments for
files and symbols, READMEs / __init__.py / index.* for folders and the
repo itself — and shown on folder cards, in tooltips and in the side panel.
Levels are deep-linkable (#d=src, #f=src/proxy.js), search with /,
Esc goes up a level, drag pans, wheel zooms. Self-contained HTML, offline.
The dashboard (--no-open to just write the file) lands in
.codegraph/dashboard.html: token savings, per-tool usage, indexed languages
and the most-imported files. Static HTML, no server, light/dark aware. The
agent can also generate it on request via usage_stats with dashboard=true.
Files are parsed with tree-sitter WASM grammars (tree-sitter-wasms
package) via web-tree-sitter — no platform-specific binaries.
The extractor walks each AST once, collecting definitions, call edges and imports per language spec (src/languages.js).
The graph persists to .codegraph/index.json inside the target repo;
refreshes are incremental (mtime+size) and throttled, so queries stay fast.
node_modules, build output, vendored and minified files are skipped;
simple root .gitignore patterns are honored.
semantic_search uses a local embedding model (all-MiniLM-L6-v2 via
transformers.js, an optional dependency). On first use it downloads
~25 MB into ~/.codegraph/models and caches symbol vectors per repo in
.codegraph/vectors.bin. Offline or without the dependency it silently
falls back to keyword search — everything else works regardless.
Add .codegraph/ to your project's .gitignore (it's a cache plus your
private notes).
MIT
Transitive callers of a symbol — the blast radius. Run BEFORE changing a signature or behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Symbol name to analyze (exact, case-insensitive) | |
| depth | No | Max caller depth (default 3) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It conveys the operation is analytical/non-mutating and clarifies the traversal is transitive, but says nothing about cost, latency, how the depth cap is honored, or the shape of the result set — gaps that remain unaddressed by either annotations or an output schema.
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 clauses with zero filler: the identity of the result is front-loaded, then the timing advice. Every word earns its place and nothing is repeated from the schema.
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 low-complexity, two-parameter read tool with no destructive behavior, the description covers what the tool produces and when to reach for it. It is slightly thin on what the returned caller list looks like, though with no output schema the omission is minor.
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 100% and both parameters are documented in the schema, so the baseline of 3 applies. The word 'transitive' loosely hints at the meaning of depth, but the description adds no format, default, or range detail beyond what the schema already states.
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?
It names a specific resource and scope — 'transitive callers of a symbol' — and labels the concept ('the blast radius'), which implicitly separates it from siblings like find_references or who_imports that return non-transitive results. An agent can tell what it gets back without opening the 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?
'Run BEFORE changing a signature or behavior' gives a concrete trigger condition that maps to a real workflow moment. It does not, however, name an alternative (e.g. find_references for direct callers) or state when this tool is unnecessary, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
File outline: imports + every signature with line ranges, no bodies. Use before reading a file in full.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Repo-relative file path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the output shape (imports + signatures with line ranges, no bodies), which is valuable since no output schema exists. However, it says nothing about failure modes (missing/unreadable files), large-file behavior, or permissions, leaving real gaps for a no-annotation tool.
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: the output contract is front-loaded, and the usage cue follows. No filler and nothing redundant.
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 low-complexity single-parameter read tool, the description covers what matters most: what the outline contains and when to invoke it. The absence of output schema makes the enumerated return content especially useful; only edge-case behavior is unaddressed.
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?
Single parameter with 100% schema coverage already documented as 'Repo-relative file path.' The description adds nothing about the path parameter, so the baseline 3 is appropriate when the schema does the heavy lifting.
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 resource (file outline) and precisely enumerates its contents: imports plus every signature with line ranges, explicitly excluding bodies. This distinguishes it from symbol-level tools like read_symbol, though it never names a sibling directly, so the differentiation is implicit rather than explicit.
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 clear context: 'Use before reading a file in full,' which establishes this as a cheap reconnaissance step preceding a token-expensive full read. It provides the when without naming alternatives or stating exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every mention of an identifier repo-wide (calls marked [call], plus types, variables, imports), with the enclosing symbol. Word-boundary, case-sensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Identifier to find (exact, case-sensitive) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose matching semantics: word-boundary, case-sensitive, all reference kinds, and that results carry the enclosing symbol. It omits any note on result caps, performance, or the 300-item limit behavior, so it is good but not complete.
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 scope front-loaded and zero filler; the parenthetical efficiently enumerates reference kinds without padding.
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 2-param read tool with no output schema and no annotations, the description covers intent and result content partially but says nothing about the undocumented 'limit' parameter, result truncation, or pagination across a repo-wide search. Usable but leaves an agent guessing on scale-related 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 coverage is 50%. The description reinforces 'name' semantics (word-boundary, case-sensitive matching, which goes slightly beyond the schema's 'exact, case-sensitive'), but the 'limit' parameter is undocumented in both the schema and the description, leaving half the surface unexplained.
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 a specific verb and resource: 'Every mention of an identifier repo-wide', and enumerates the reference kinds included (calls marked [call], types, variables, imports), which implicitly distinguishes it from siblings like who_imports (imports only) and find_symbol (declaration lookup). It stops short of explicitly naming which sibling to use instead, so 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?
Usage is implied by the purpose — an agent can infer this is for finding all usages of an identifier — but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., vs. find_symbol, who_imports, or analyze_impact). Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a definition by name, repo-wide. Returns file:line, signature and container.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind: function|method|class|struct|interface|type|enum|const | |
| name | No | Symbol name (case-insensitive; substring match unless exact=true) | |
| exact | No | Exact name match only (default false) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it partially does so by disclosing the return shape ('file:line, signature and container'), which matters since no output schema exists. It does not state read-only status, permission needs, or behavior on ambiguous matches, leaving real gaps.
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, zero filler, with the core action and scope front-loaded before the return-value note.
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 read-only lookup with no annotations and no output schema, the description covers purpose, scope, and return shape adequately. It falls short only in not distinguishing itself from sibling retrieval tools or explaining the limit parameter.
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 75%, so kind, name, and exact are already documented, and the description adds nothing beyond the looser 'by name, repo-wide' framing. The undocumented 'limit' (bound 1-50, semantics never explained) is left entirely to the schema's numeric bounds.
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'), resource ('a definition'), and scope ('by name, repo-wide'), plus what it returns. It is clearly distinguishable from read_symbol, but it never names or contrasts with the sibling, so differentiation is left to inference.
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 when-to-use guidance, no exclusions, and no alternatives named, despite an obvious sibling set (semantic_search for fuzzy lookup, read_symbol for reading a known symbol, find_references for usages). The agent must guess which lookup tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full source of ONE symbol (function/class/method) without reading the whole file.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Repo-relative file path to disambiguate | |
| name | No | Symbol name (exact, case-insensitive) | |
| index | No | 1-based pick when several matches exist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral load. It discloses the return content (full source) and the read-only nature implied by 'read', but says nothing about behavior when a symbol isn't found, when multiple matches exist beyond the index hint, or handling of binary/generated files.
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 front-loaded sentence that states the core value proposition (one symbol's full source) with the key contrast (no whole-file read). 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?
For a read-only single-symbol extractor with fully documented parameters and no output schema, the definition covers what the tool returns and its efficiency benefit. Minor gaps remain around multi-match resolution and not-found behavior, but nothing critical 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 description coverage is 100%, so each of the three parameters (file, name, index) is already documented in the schema. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
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 (read) and resource (ONE symbol: function/class/method) and clarifies it returns full source without loading the whole file. This is clear, but it doesn't differentiate from the closely related sibling find_symbol or file_skeleton, so an agent could confuse the two.
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 phrase 'without reading the whole file', which suggests using this instead of a full file read. There is no explicit guidance on when to choose this over find_symbol, file_skeleton, or semantic_search, and no stated prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saved project notes: most relevant first with a query, newest first without. Safe to call argless at task start.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | What are you working on / looking for (omit for the latest notes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It covers ordering behavior (relevant vs newest) which is a useful trait, but says nothing about authentication needs, rate limits, whether notes are scoped to a project or user, or what happens with an empty result set. For a read tool with zero structured behavior hints, this is thin.
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 compact sentences with no filler. Ordering rules are front-loaded and the safe-argless note follows. Efficient for a simple two-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 description is short and the tool is simple, but with no annotations, no output schema, and only 50% schema coverage, the description should fill more gaps (permissions, scoping, return contents, limit default). It leaves the agent guessing about how the tool behaves beyond ordering.
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 50%, with `query` described in the schema but `limit` undocumented. The description explains the semantic effect of omitting query (get latest notes), which adds meaning beyond the schema. However, it doesn't explain the limit parameter's behavior or defaults.
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 the resource (saved project notes) and the ordering behavior, distinguishing it from save_note. The verb 'recall' is clear, though the description spends a word on ordering rather than explicitly stating 'retrieve'. Still clear enough that an agent knows what it does.
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 phrase 'Safe to call argless at task start' gives a clear implied usage context for calling without parameters. However, it doesn't explain when the query variant should be used vs alternatives like semantic_search, save_note, or other sibling tools. The guidance is present but narrow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force a re-scan of the repository. Use full=true to rebuild the index from scratch.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Rebuild everything (default: incremental) |
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 reveals the incremental-by-default behavior, which is useful, but for an expensive forced re-scan it says nothing about cost, duration, whether the call blocks, or whether it invalidates existing cached results.
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, zero padding, and the core action is front-loaded ahead of the parameter note. 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?
There is no output schema and no annotations, so the description should ideally cover what the re-scan affects (index state, other tools' results) and rough cost. It covers the action and the full flag but leaves the operational consequences unstated.
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 100%, so the schema already documents 'full' as a boolean meaning 'Rebuild everything (default: incremental).' The description restates this without adding format, default, or interaction details beyond the schema, which is the baseline-3 case.
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 ('re-scan') and resource ('the repository'), making the action clear. It lacks differentiation from siblings, though 'reindex' is fairly distinct in this set (save_note, repo_map, semantic_search) so the risk of confusion is low.
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 implies usage via 'Use full=true to rebuild the index from scratch,' which is a hint about when to choose full mode, but it never states when to call reindex at all versus relying on automatic indexing or other tools. 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.
Project map: languages, symbol counts, key files ranked by import centrality. Call FIRST to orient. html=true also writes an interactive architecture map.
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | Also write .codegraph/map.html (interactive import graph) | |
| limit | No | Max files to show (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It discloses that html=true writes an interactive architecture map and that the tool ranks files by import centrality, which is valuable behavioral context. It doesn't mention side effects of the default mode or rate limits, but the write behavior is covered.
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 sentences, front-loaded with the core output and usage instruction. Very little waste, though the phrasing is compact to the point of being terse.
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 read-only mapping tool with no output schema and full parameter coverage, the description provides enough to invoke correctly and understand the html side effect. It could be improved with a note on typical output size or performance considerations, but it is largely complete.
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 100%, so the schema fully documents both parameters (html and limit). The description adds the html behavior (writes map.html) but doesn't add details for limit beyond what the schema provides. Baseline 3 is appropriate.
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?
Clearly states it produces a project map covering languages, symbol counts, and key files ranked by import centrality. Distinguishes itself from read-oriented siblings, though it could more explicitly differentiate from file_skeleton or find_symbol.
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 says 'Call FIRST to orient,' which gives clear usage priority. However, it doesn't mention when not to use it or name alternatives for deeper analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a short project note (decision, gotcha, convention) that survives across sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags for recall | |
| text | No | The note text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It does disclose one meaningful behavioral trait, cross-session persistence, and frames notes as short. It omits scope (per-project vs global), storage/indexing side effects, deduplication, and whether saving triggers anything downstream, which matters for an unannotated write tool.
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 sentence that front-loads the verb and resource and uses a parenthetical to enumerate the covered note types. There is no filler and nothing to trim.
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 two-parameter tool with full schema coverage and no output schema, the description supplies the essential purpose plus the persistence rationale. It is nearly complete, with the only gap being call scope and any storage-side behavior a caller might need to anticipate.
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 100%, so both 'tags' and 'text' are already documented and the baseline is 3. The description adds only the qualitative sense of 'short' and examples of note content, but nothing about tag format, reuse, or why text is not a required field despite being the payload.
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 pairs a specific verb (save) with a specific resource (short project note) and clarifies the note's content domain with concrete examples (decision, gotcha, convention). The save-vs-recall split against the sibling recall_notes is implied by the verb, but no sibling is named explicitly, which keeps it just 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?
It signals the appropriate content to record and the reason to do so ('survives across sessions'), which implies when to use it. However, it never states when not to save, nor points to recall_notes for retrieval, leaving the usage boundary to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code/notes BY MEANING ("where is auth token validated") when the exact name is unknown. Local embeddings; keyword fallback offline.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Natural-language description of what you are looking for | |
| scope | No | What to search (default code) |
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 the useful behavioral fact that local embeddings are used with keyword fallback when offline, which is real operational context. However it omits whether the operation is read-only, whether results are paginated, or how relevance is ranked.
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 compact sentences with zero waste. The core purpose is front-loaded, and the mechanism/fallback note follows efficiently.
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 3-parameter search tool with no output schema, the description covers purpose, when-to-use, and the meaningful operational detail (local embeddings, offline keyword fallback). It is nearly complete; only ranking or pagination behavior for the limit parameter is unaddressed.
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 67%; the schema documents 'query' and 'scope' but leaves 'limit' without a description. The description itself doesn't add parameter syntax beyond the query example, but the baseline for this coverage level is reasonable and the query example clarifies intended input. It could have documented limit semantics, so not 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 verb+resource ('Find code/notes') with the defining mechanism ('BY MEANING') and an illustrative natural-language example. It implicitly distinguishes itself from siblings like find_symbol, which presumably match exact names – the description explicitly notes this tool handles the case 'when the exact name is unknown'.
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 a clear when-to-use signal: use it when the exact name is unknown, with a concrete example query. It doesn't explicitly name find_symbol as the alternative to use for known names, but the conditional phrasing effectively steers the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Usage counters and estimated tokens saved. dashboard=true also writes an HTML report and returns its path.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard | No | Also write .codegraph/dashboard.html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses a side effect: dashboard=true writes an HTML report and returns its path, which is behavior beyond the schema. However, it says nothing about permissions, cost, whether reads are non-destructive, or the shape of the returned counters.
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 no filler, and the core output is front-loaded followed by the conditional behavior. Slightly under-specified, 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?
For a zero-required-parameter stats tool with no output schema and no annotations, the description is adequate but thin. It does not describe the returned counters/token format, so an agent knows roughly what to expect but not the response structure.
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 100%, so the schema already documents the single parameter. The description adds value beyond the schema by clarifying that dashboard=true not only writes the file but also returns its path, which the schema's terse 'Also write .codegraph/dashboard.html' does not mention.
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 the resource (usage counters and estimated tokens saved), which is distinct from the code-graph siblings, but it lacks a clear action verb and never explicitly frames this as a stats/reporting tool. An agent can infer the purpose but must do some work.
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 statement of when to use this tool versus alternatives, nor any prerequisites or context. The only condition given is the dashboard=true flag behavior, which is a parameter detail rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Files that import a given module — its direct dependents.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Repo-relative path of the module/file |
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. It does add one meaningful trait — the results are 'direct dependents' only, implying no transitive closure — but says nothing about read-only semantics (obvious for a query), result limits, or ordering.
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 with the subject and scope front-loaded and zero filler. It is efficient, though terseness shades into under-specification rather than maximal usefulness.
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 no output schema and no annotations, the description must stand alone; it adequately conveys the return payload (importing files) and the direct-only scope, but omits any guidance on when to prefer it over the related reference/impact tools.
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 100% for the single 'path' parameter, so the schema already defines the repo-relative input. The description adds no format, default, or resolution semantics beyond that, making the baseline 3 correct.
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 resource and result: 'Files that import a given module — its direct dependents.' An agent immediately knows what it gets back. It does not name the closely related siblings (find_references, analyze_impact) to distinguish itself, 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 when-to-use guidance, no prerequisites, and no routing to alternatives such as find_references or analyze_impact, which appear to overlap in this namespace. Usage can only be inferred from the one-line purpose.
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.17.0analyze_impactfile_skeletonfind_referencesfind_symbolread_symbolrecall_notesreindexrepo_mapsave_notesemantic_searchusage_statswho_importsScored across 12 tools
Most tools target clearly different operations: find_symbol (definitions), find_references (all usages), semantic_search (by meaning), who_imports (module dependents), and analyze_impact (transitive callers) are well-differentiated by their descriptions. Minor overlap exists between find_references and who_imports (both touch imports) and between read_symbol and file_skeleton (both read code), but the granularity distinctions keep them separable.
All names use consistent snake_case, and most follow a verb_noun or action-oriented pattern (save_note, find_symbol, read_symbol, find_references, analyze_impact, recall_notes). A few deviate into noun phrases (repo_map, file_skeleton, usage_stats, semantic_search) and one is a bare verb (reindex), but the pattern remains readable and predictable.
12 tools is well-scoped for a code-navigation/graph server, with each tool covering a distinct facet (index, map, locate, read, outline, search, references, impact, stats, notes). No redundancy and no tool feels extraneous.
Coverage spans indexing (reindex), orientation (repo_map, file_skeleton), discovery (find_symbol, semantic_search, find_references, who_imports), impact analysis, and notes persistence (save_note/recall_notes). The main gap is a plain literal/regex text search tool, though the semantic_search keyword fallback partly compensates.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
