LayerMap is a read-only MCP server that gives coding agents a compiler-resolved map of a codebase for tracing callers/callees, finding declarations/references, and assessing change impact.
Explore a directory, file, or declaration to see modules, imports, declarations, callers/callees up to 8 levels, and routes/handlers/jobs/commands.
Search for declarations by name, path, or documentation with filters and paging.
Find every usage of a declaration, including calls, reads/writes, imports/exports, and non-call references.
Check uncommitted changes or changes since a base commit for affected entry points, related/shared tests, removed env/config names still used elsewhere, new module dependencies/cycles, duplicate new code, declarations left without callers, manual review items, and test coverage gaps.
Work across TypeScript, JavaScript, Go, Python, and Java; the server is local, read-only, and does not run or modify code.
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., "@LayerMap what calls createUser in src/api/users.ts, traced up to entry points?"
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.
English · 中文
LayerMap tells your coding agent what calls a function and what changing it affects, up to the HTTP routes, in one call. With at most 15 requests, agents found 97.9% of affected endpoints with LayerMap vs 58.8% without; with no limit, Claude Code cost 33% less in the 0.1.5 re-run (benchmark).
Resolved by each language's compiler or type checker, not guessed from names by tree-sitter: calls through interfaces, base classes, templates and decorators link as the compiler links them, for TypeScript, JavaScript, Go, Python and Java.
A layered map of your codebase for coding agents. LayerMap gives Claude Code, Codex, CodeBuddy Code, Pi, DeepSeek Harness and other MCP clients read-only tools that answer, in one call, what an agent otherwise works out with dozens of searches:
What calls this, and what does changing it affect? Callers traced up to 8 levels, to the HTTP routes, handlers, jobs and commands they start from.
What does it call? Callees down to 8 levels.
What is here? Modules, each file's declarations, and every usage of a symbol.
What did my edit affect? The routes, jobs and commands the uncommitted changes reach, and the existing tests related to them.
It maps TypeScript, JavaScript, Go, Python and Java with each language's own compiler, so calls
through interfaces, base classes, templates and decorators resolve as the compiler resolves them,
including the ones text search misses. In WeChat mini-programs, it also links each page's and
component's template (.wxml) to the methods it binds and the components it shows, and each event a
component emits to the handlers the pages bind to it, so callers reach the pages.
In Miniflux, one call on Storage.MarkFeedAsRead finds all four
ways a request reaches it, each with its route:
DECLARATION internal/storage/entry.go: Storage.MarkFeedAsRead m656-680 exported
← called by internal/api/feed.go: handler.markFeedAsRead m140-155 @149
← called by internal/fever/handler.go: handler.handleWriteFeeds m492-519 @508
← called by internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338 @1311
← called by internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30 @24
[1] internal/api/feed.go: handler.markFeedAsRead m140-155
← used as value by internal/api/api.go: Serve f25-84 @61 "PUT /v1/feeds/{feedID}/mark-all-as-read"
[1] internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338
← used as value by internal/googlereader/handler.go: Serve f44-64 @62 "POST /reader/api/0/mark-all-as-read"
[1] internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30
← used as value by internal/ui/ui.go: Serve f18-180 @77 "POST /feed/{feedID}/mark-all-as-read"
… (the Fever API, then on down to main.go: main)m and f mark methods and functions with their lines; @ is the line of the call, and the quoted
route is what it is registered under: the HTTP method and the full path, with the /v1 prefix its
subrouter adds. In Java, Python and TypeScript the route shows on the handler itself, as in
@GetMapping("/{id}") route "GET /api/tasks/{id}".
Related MCP server: codegraph-mcp
Impact questions ("which HTTP endpoints does changing this affect?") on public Go, Python and Java projects, graded blind against truth sets cross-checked with each language's own toolchain:
With LayerMap | Without | |
Endpoints found, at most 15 requests ( | 97.9% | 58.8% |
Used unprompted by Claude Code / Codex (plugin installed, two rounds) | 12 of 12 / 12 of 12 | — |
Endpoints found, no request limit (Claude Code / Codex, 0.1.5) | 100% / 100% | 99.0% / 100% |
Claude Code cost, no request limit (0.1.5 re-run; first round −32%) | −33% | |
Codex input tokens, no request limit (current defaults) | +14% | |
Time, no request limit (Claude Code / Codex) | +25% / +20% | |
Failing tests the change check lists (Go / Python, functions made to fail) | 100% / 94–98% | — |
Ripple tasks: runs leaving other features' tests passing (Codex / Claude Code, 4 tasks × 6 runs with, × 3 without) | 23 of 24 / 11 of 24 | 3 of 12 / 4 of 12 |
Everyday tasks, no impact analysis needed: done right / time (Claude Code and Codex, 8 tasks × 2 runs) | 32 of 32 / +12–31% | 32 of 32 |
With a tight budget, the map finds far more of the affected code, at about 24% more tokens. With no limit, both agents find nearly everything either way. Claude Code costs a third less with the map. Codex's current defaults already search lean, so the map no longer saves it tokens; at reasoning effort max, in the first round, it saved 55%. Agents with the map explore more widely, which takes longer. On requests whose obvious change breaks another feature, the change check helped Codex keep to the requested feature. Claude Code saw which tests of other features it had changed but often kept the broader change on purpose, so it showed no clear difference. On small local tasks the map changed nothing but cost about a fifth more time and money. These are small samples on tasks written by LayerMap's authors. The report has the setup, the published tasks and the limitations.
Other tools give agents part of this. LayerMap combines compiler accuracy with whole-chain traces in one local map:
Tree-sitter code graphs (codegraph, GitNexus, …) | Language servers and IDEs (Claude Code's LSP tool, Serena, JetBrains) | Embedding search (Claude Context, Augment) | LayerMap | |
How calls are linked | Matched by names, imports and framework rules, often with confidence scores | The compiler's own resolution | Not linked; similar code is retrieved | Resolved by each language's compiler or type checker |
Callers traced to routes and handlers | In several tools, at varying depth | One level per request (JetBrains: 5 by default) | — | Up to 8 levels in one call |
Kept as a map | Yes, with file watching | No, answered live by a running server | An index of code chunks | Yes, brought up to date on every call |
Runs on your machine | Yes; some send anonymous telemetry | Yes | Usually with cloud embeddings | Yes, and sends nothing |
Another tool fits better if you need:
more languages, since tree-sitter graphs cover 30 or more;
renaming and refactoring, from language servers;
search by meaning, from embedding search;
search across many repositories, with Sourcegraph.
Claude Code
/plugin marketplace add coffeecoproject/layermap
/plugin install layermap@layermapCodex
codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermapCodeBuddy Code
codebuddy plugin marketplace add coffeecoproject/layermap
codebuddy plugin install layermap@layermapPi
pi install npm:layermapDeepSeek Harness
npx layermap setup dshThis adds LayerMap to every dsh profile. Each session maps the project dsh was started in, and
npx layermap remove dsh undoes it.
In every agent, start a new session in a Git repository and ask as usual. LayerMap tells the agent
when the map helps. A session started in a folder holding several repositories, or one that moves
to another repository, works too: each map tool call maps the repository its path names. The first
time a session starts a version of LayerMap, npm installs that pinned layermap package into
LayerMap's cache; later sessions start it from there, even offline.
Claude Code asks once before each map tool runs in a project. Choose "don't ask again", or run
npx layermap allow claude to allow the plugin's read-only tools everywhere.
After an edit. When the agent changes code, project_check_changes lists what the change
affects: the routes, jobs and commands that reach the changed functions, what the map cannot see,
and the existing tests related to the change. When the changed code serves several areas (packages
or modules), it names each one with its tests, and it names the existing tests the diff rewrote, so
a change meant for one feature does not quietly change the others. Environment variables and
configuration keys are linked by name only, which no compiler sees, so when the diff removes one
from a file, the check names the files that still read or set the old name. In the same way, when
the change reaches a route's handler or renames a route, it names the code and templates that
request that path: a frontend's fetch, a generated API client, a redirect or a link. When the change adds
an import between two modules of the project overview, it names it, and says when the two now
depend on each other; whether that direction suits the project's layers is for the agent to judge. When a
declaration the change adds reads almost the same as code the project already has, it names both, so
the agent can use the existing code instead of a copy. When the change takes away the last call to a
declaration, as when new code replaces old, it names that declaration, so the agent can delete what
the change left behind. It never writes or runs tests. In Claude Code and
CodeBuddy Code the plugin asks the agent once, before it finishes, to run this check for each repository it edited code in
and has not checked since, whether through its edit tools or shell commands, which count for the code files they name
(changes another session makes in the same work tree do not count); the Pi extension does the same after the agent's own
edits. Set LAYERMAP_STOP_CHECK=0 to turn that
off. Codex and DeepSeek Harness are told to run it.
Without plugins: run npx layermap setup claude or npx layermap setup codex. Setup does three
things:
registers the server;
lets its read-only tools run without a prompt;
adds one marked sentence to the agent's instructions file.
Setup is for one machine; for a whole team, have each member install the plugin. npx layermap remove … undoes it. For any other MCP client, run npx -y layermap mcp as a stdio server in the
repository.
Requirements:
Node.js 22.22 or later.
macOS or Linux (x64 or arm64); Windows (x64 or arm64) is experimental.
A Git repository.
For Java projects, a JDK 21 or later.
The first call in a repository builds its map: seconds for a small project, a few minutes for a large one. Later calls re-analyze only what changed, so the map always matches the working tree.
Maps stay in your user cache (~/Library/Caches/layermap, ~/.cache/layermap or
LAYERMAP_CACHE), never in the repository. LayerMap runs entirely on your machine and sends
nothing anywhere (privacy,
security).
Tool | Use |
| A directory, a file, or a declaration's callers and callees ( |
| Find declarations by words in their names, paths or documentation. |
| Every usage of a declaration, compiled from current source. |
| What the uncommitted changes (or those since |
The same from the command line:
npx layermap explore src/api/users.ts --name createUser --direction INCOMING --depth 8
npx layermap search "invoice total"
npx layermap refs src/billing/tax.ts calculateTax
npx layermap check --base main
npx layermap check test/billing.test.ts # also: what of the change this test does not runHow long does the first map take? On a recent Mac:
Miniflux (400 Go files): about 3 s.
Polar's server (1,900 Python files): about a minute.
Conductor (1,500 Java and 1,300 TypeScript files): under two minutes.
What can't it see? Calls the compiler cannot resolve statically: dependency injection, unknown framework routing, reflection and computed names. The tools say where a trace stops, and a missing relationship does not prove absence.
Windows? Experimental. LayerMap's tests pass on Windows, but it has not yet been tried with Claude Code or Codex on a real Windows machine, so please test it on your own projects first and report what breaks. The Claude Code plugin's hooks need Git for Windows (they run in Git Bash); without it the map tools still work, and the session-start note and end-of-task check do not run.
Claude Code in print mode (claude -p)? Print mode, as of Claude Code 2.1, does not start the
servers that installed plugins bring, so the map tools are missing there while the plugin's hooks
still run. Pass the server yourself:
claude -p "..." --mcp-config '{"mcpServers":{"layermap":{"command":"npx","args":["-y","layermap","mcp"]}}}'How do I remove it?
Claude Code: /plugin uninstall layermap@layermap.
Codex: codex plugin remove layermap@layermap.
CodeBuddy Code: codebuddy plugin uninstall layermap@layermap.
Pi: pi remove npm:layermap.
Then delete the cache directory.
You need pnpm, Go 1.24 and a JDK 21+. A missing toolchain leaves its language unanalyzed.
Run pnpm install. On the first install pnpm asks which dependencies may run build scripts; allow
esbuild only, since the SQLite package ships prebuilt binaries:
pnpm approve-builds esbuild '!@photostructure/sqlite'Then run pnpm test, pnpm typecheck or pnpm lint.
pnpm package builds the npm package.
Use this once the edits are done, before reporting the work done: it lists what the uncommitted changes affect, from the changed functions up to the HTTP routes, jobs and commands that reach them, plus the existing tests related to them. Compares the working tree with a commit (HEAD by default, so uncommitted and untracked changes), finds the declarations the diff changed, removed or renamed, and follows their callers up to 8 levels. It reports, conclusion first: AFFECTED ENTRY POINTS reached through resolved calls, each route with its HTTP methods and full path and the chain to the change; POSSIBLY AFFECTED ones reached only through a call on an interface or base member; REQUESTED BY, the code and templates outside the tests that request the path of a route whose handler the change reaches or a route it removed, found by text; EXISTING TESTS CHANGED, the tests that existed before the diff and whose code it changed or removed; SHARED BY, when tests reach the changed code through more than one area (package or module), so a change meant for one feature may change others; NAMES STILL USED ELSEWHERE, environment variables and configuration keys the diff removed from a file that other files still read or set, found by text; NEW MODULE DEPENDENCIES, imports between the modules of the project overview that the base did not have, and those that make two modules depend on each other, for you to judge against the project's layers; EXISTING CODE LIKE THE NEW CODE, declarations the diff adds whose code reads almost the same as code the project already has; LEFT WITHOUT CALLERS, declarations whose last callers outside the tests the diff removed or changed, and that nothing extends, implements, overrides or wires with a decorator; CHECK BY HAND for what a static map cannot follow (changed configuration, templates, migrations or dependency files, changed route registrations, declarations with no callers, calls by name on receivers of unknown type); and RELATED TESTS, the existing test files that call the changed code, import a changed file or sit beside it; given tests, NOT REACHED BY THE GIVEN TESTS, the changed declarations none of them calls or requests through a route, with the entry points above them. It does not run or write tests: run the related ones if the change needs verifying; a failing or rewritten test of a feature the request is not about means the change leaked, so restore the test and narrow the change; a new dependency that runs against the layers or closes a cycle means moving what both modules need down rather than importing upward; new code like existing code means using the existing code, or removing the old if the new replaces it; code left without callers means deleting it, with the tests that only test it, when the change replaced it; call it once when the edits are done; and confirm the entry points in source, since an empty list does not prove a change safe.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Commit, branch or tag to compare the working tree with (HEAD, so the uncommitted changes, by default; main for a whole branch). | HEAD |
| path | No | A file or directory in the repository to check, when the session works in more than one; the check covers that repository's whole working tree. | |
| tests | No | Test files that should cover the change, such as the ones you wrote for it, as paths are given to the other tools: the report then adds NOT REACHED BY THE GIVEN TESTS, the changed declarations none of them calls or requests through a route, with the entry points above them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnly/idempotent/non-destructive; the description adds substantial context beyond that: it never runs or writes tests, defaults to HEAD and includes untracked files, follows callers only 8 levels, uses text matching for REQUESTED BY and NAMES STILL USED ELSEWHERE, and explicitly lists what static analysis cannot follow (config, templates, migrations, unknown receiver types). This is exactly the kind of limitation disclosure an agent 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?
It is front-loaded with the trigger and the report sections are capitalized, giving it a navigable structure. But it is one very long, comma-chained sentence with visible repetition ('NOT REACHED BY THE GIVEN TESTS' defined twice, 'call it once when the edits are done' echoing the opening), which harms scannability.
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, so the description carries the burden of explaining return values — and it does, defining every report section and how findings should be acted on (restore leaked tests, move shared dependencies, delete uncalled code). Nothing an agent needs to interpret the result is 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 100%, so all three parameters are already documented in the schema. The description restates the same semantics (HEAD default, path scoping, tests adding NOT REACHED BY THE GIVEN TESTS) without adding syntax or format detail, so the baseline of 3 applies.
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: it lists what uncommitted changes affect, tracing changed declarations up to entry points and related tests. The enumerated report sections (AFFECTED ENTRY POINTS, POSSIBLY AFFECTED, REQUESTED BY, etc.) make it unmistakable against siblings like project_find_references or project_search_map, which locate code rather than assess change 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?
Gives an explicit trigger ('once the edits are done, before reporting the work done') and reinforces it with 'call it once when the edits are done', plus a caution that an empty list does not prove a change safe. It does not name or exclude sibling tools, so the alternative-selection dimension is left implicit, keeping it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this instead of grep to answer what calls a function or method, what changing it affects (callers traced up to entry points such as HTTP routes, handlers, jobs and commands), what it calls, and what a directory or file contains: one call returns the callers or callees up to 8 levels deep, with file paths and line numbers, for TypeScript, JavaScript, Go, Python and Java. Read the static project map, zooming from the whole project to one declaration. path "." or a directory lists modules, module imports, external packages and its files: with exported declarations when the listing is small, as file names and line counts by directory when larger, and as modules only when very large. Start here to see what exists before searching or reading. A file path lists its declarations and members, imports, importers and top-level statements. A file path with name (or Container.member), optionally narrowed by its start line, or with a line alone, shows that declaration's calls, callers (including uses as a value), writes, heritage, decorators and members, aggregated per related declaration with @line sites; closures and locals are folded into their named container. depth also expands the related declarations hop by hop: up to 8 in one direction, which traces callers up to entry points (INCOMING) or callees down (OUTGOING), and up to 3 for BOTH. To find what a change affects, select the declaration with direction INCOMING and a depth up to 8, continue from any NOT EXPANDED declarations the view names, then confirm the entry points in source. Test files and standard-library call targets are hidden and counted by default; includeTests and includeUnresolved show them. Views use kinds f function, c class, m method, p property, v variable, t type, i interface, e enum; numbers are 1-based source lines. In a declaration view, @n marks where a relationship occurs and +n counts further sites, which project_find_references lists; a quoted path after the sites is the route the call or value is registered under there: its HTTP methods when the registration names them, then its path joined with the prefixes of the routers it is registered on, as far as the same function or file sets them (a prefix added where a router is mounted or passed in is not included); route "…" after a decorator is the full route the decorator maps, its class's path joined with its own. Static relationships are grouped by the declaration that owns them. Callers are direct calls, uses as a value (stored, passed, returned or selected, then usually invoked through that value) and calls through an interface, type or base member that a declaration implements (dispatched from); dispatches to lists the members that implement an interface, type or base member, which a call through it may reach; trace stops names calls whose target is a function value, a member without a mapped implementation or a computed key, which only source reading can follow; possible callers by name are calls elsewhere, in the same language, of a member with a method's name on a receiver of unknown type (an untyped value, or one an unloaded package produced); they may or may not reach that method. Read source at the printed line ranges. The map is static: trace stops, possible callers by name, framework wiring and unresolved targets need source reading, and a missing relationship does not prove absence. When a page reports more entries, continue with offset and otherwise unchanged arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| line | No | Start line of a same-named declaration; without name, the declaration containing this line. | |
| name | No | Declaration name or Container.member in the file, as printed by the map. | |
| path | No | "." or a directory for an overview, or a file for its declarations. | . |
| depth | No | Relationship hops for a declaration: up to 8 for INCOMING or OUTGOING (for example callers up to entry points), up to 3 for BOTH. | |
| offset | No | ||
| direction | No | BOTH | |
| includeTests | No | ||
| includeUnresolved | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: static-only limitations ('trace stops, possible callers by name, framework wiring and unresolved targets need source reading, and a missing relationship does not prove absence'), default hiding of tests/stdlib with includeTests/includeUnresolved opt-ins, and offset-based pagination.
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?
Purpose is front-loaded, but the body is a dense wall of semicolon-joined clauses covering return formatting, route resolution, and edge cases in one breath. Nearly all content is substantive, yet the volume and run-on structure make it hard to scan and over-invests in low-frequency detail.
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 a complex read tool, the description carries the full burden and does so: it documents result shape (file paths, line numbers, kinds f/c/m/p/v/t/i/e, @n site markers, +n counts), aggregation rules, and pagination. Nothing essential for correct invocation is 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 coverage is only 50%, but the description compensates thoroughly, explaining direction semantics (INCOMING traces callers to entry points, OUTGOING callees), depth limits per direction (8 vs 3 for BOTH), path/name/line resolution, and offset continuation ('continue with offset and otherwise unchanged arguments').
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 opening states a specific verb and resource: 'Use this instead of grep to answer what calls a function or method, what changing it affects... what it calls, and what a directory or file contains.' It names one sibling (project_find_references) but leaves project_search_map and project_check_changes unaddressed, and the core purpose is somewhat buried under the dense enumeration that follows.
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?
Explicit routing: 'Use this instead of grep', 'Start here to see what exists before searching or reading', plus a concrete impact-analysis workflow ('select the declaration with direction INCOMING and a depth up to 8, continue from any NOT EXPANDED declarations'). It states both when to use it and how to continue the analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to list every place a declaration is used (calls, imports, re-exports, reads and writes), compiled from current source: more complete than searching for its name. Compute usages of a mapped declaration from current source, including aliases, re-exports and non-call references. Select it with symbol {path,name,line?} as printed by project_explore_map or project_search_map (line is its start line when names repeat), or with an entityRef or locator {path,start,kind}. Broader and more expensive than the cached callers in project_explore_map; file or unsupported declarations may lack a reference target. path and kinds filter usage locations before paging. objects contains compact declarations; targetRef and reference ownerRef identify them. Read a reference at its line range. A file that several compiler contexts read (such as packages of one workspace) lists its references once per context, each with that context's configPath. Continue with nextCursor and unchanged conditions, including after an empty partial page. Filtered exhaustion and missing results do not prove absence.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Filter usage locations; compiler inputs and declarations may lie elsewhere in the project. | . |
| kinds | No | ||
| cursor | No | ||
| symbol | No | Declaration as printed by the map: file path, name or Container.member, and start line when names repeat. | |
| locator | No | Declaration location: path and UTF-16 start offset; include kind to distinguish declarations at the same offset. | |
| entityRef | No | ||
| maxResults | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations it discloses real behavioral traits: results are compiled from current source, a file read by several compiler contexts lists references once per context with that context's configPath, pagination continues via nextCursor even after an empty partial page, and 'filtered exhaustion and missing results do not prove absence.' That is substantial context the annotations cannot convey.
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?
Purpose is front-loaded and every sentence earns its place, but the content is packed into a single dense paragraph mixing usage, selectors, paging, and output notes. Bullets or a short structure would make it easier to scan for a 7-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?
For a complex tool with no output schema and 43% schema coverage, the description covers the critical ground: output shape (objects contains declarations, targetRef/ownerRef identify them), reading a reference at its line range, per-context duplication, and paging. A couple of edge behaviors (e.g., maxResults limits, error modes) are 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?
Schema coverage is only 43%, so the description must carry weight, and it does: it explains that path and kinds filter usage locations before paging, defines the symbol {path,name,line?} and locator {path,start,kind} selector shapes, and connects cursor to nextCursor. maxResults is only implied through paging language, leaving one minor 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 precise verb and resource ('list every place a declaration is used' enumerating calls, imports, re-exports, reads and writes) and explicitly separates itself from name-search and from the cached callers in project_explore_map. An agent can distinguish it from both 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?
Gives explicit when-to-use ('Use this to list every place a declaration is used') and names the alternatives: preferring search-by-name is discouraged because this is 'more complete', and project_explore_map is called out as the cheaper cached option. It also states the selector entry points (symbol, entityRef, locator) and the caveat that file/unsupported declarations may lack a reference target.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to find where a function, method, class or type is declared, by name or by words in its name, path or documentation, before exploring its callers with project_explore_map. Find declarations and files whose names, paths or source documentation match query terms. ANY (default) matches any term, ALL requires every term, LITERAL matches the exact text. Results are ranked by relevance and grouped by file with the declaration name, kind, 1-based line range and matched fields (kinds f function, c class, m method, p property, v variable, t type, i interface, e enum; numbers are 1-based source lines). Zoom into a result with project_explore_map({path,name}) or read its line range in the file. This is not a full-text search and does not prove absence; search the source text itself for exact text. Continue with offset and unchanged conditions.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| kinds | No | ||
| query | Yes | ||
| offset | No | ||
| matchMode | No | ANY matches one or more query terms; ALL requires every term; LITERAL matches the complete text literally. | ANY |
| maxResults | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: results are relevance-ranked and grouped by file, include name/kind/1-based line range/matched fields, and the important caveat that absence is not proven. It also discloses the kind-code legend (f, c, m, p, v, t, i, e).
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-loads purpose and the sibling relationship, then layers matching rules, return shape, and caveats. It is a single dense paragraph where most sentences earn their place, though the kind-code enumeration makes it heavier than strictly necessary.
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, the description compensates by describing the return shape (grouped by file, declaration name, kind, 1-based line range, matched fields) and pagination via offset. For a read-only search tool, an agent has everything needed to call and interpret it.
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 only 17%, so the description carries the burden and does so well: it explains matchMode (ANY default, ALL, LITERAL), the term-matching semantics of query, the meaning of kinds via letter codes, and offset-based pagination. maxResults and path semantics are left unstated, 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 verb and resource ('find where a function, method, class or type is declared') plus the matching dimensions (name, path, documentation). It explicitly distinguishes itself from the sibling project_explore_map by positioning that tool as the follow-up for callers.
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 explicit when-to-use ('before exploring its callers with project_explore_map'), when-not ('This is not a full-text search and does not prove absence; search the source text itself for exact text'), and continuation guidance ('Continue with offset'). Alternatives and exclusions are both named.
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.31project_check_changes2 fields changedInput schema / properties / pathAdded value: +{
+ "description": "A file or directory in the repository to check, when the session works in more than one; the check covers that repository's whole working tree.",
+ "type": "string"
+}Input schema / properties / testsAdded value: +{
+ "description": "Test files that should cover the change, such as the ones you wrote for it, as paths are given to the other tools: the report then adds NOT REACHED BY THE GIVEN TESTS, the changed declarations none of them calls or requests through a route, with the entry points above them.",
+ "items": {
+ "maxLength": 1000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 200,
+ "type": "array"
+}v0.1.17project_check_changesv0.1.0project_explore_mapproject_find_referencesproject_search_mapScored across 4 tools
The four tools have mostly distinct roles: search declarations, explore the call map, list exact references, and run a change-impact report. The main overlap is between project_explore_map's cached caller view and project_find_references' broader usage listing, though the descriptions explicitly contrast them.
All tools use a consistent snake_case project_verb_noun pattern: project_search_map, project_explore_map, project_find_references, project_check_changes. The convention is predictable and readable throughout.
Four tools is well scoped for a static code-map server. Each tool covers a distinct step in the workflow: discovering declarations, exploring relationships, enumerating references, and checking change impact.
The surface covers search, declaration/file exploration, caller/callee tracing, reference lookup, and change-impact analysis, which is core coverage for the domain. Minor gaps remain: there is no dedicated source-reading tool and explicitly no full-text search, though the descriptions tell the agent to read source at reported line ranges.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
