Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), while the description discloses substantial behavior beyond that: depth caps (8 INCOMING/OUTGOING, 3 BOTH), test files and stdlib targets hidden and counted by default, pagination via offset, and a precise static-analysis limitation model (traces stop, possible callers by name, framework wiring and unresolved targets need source reading, absence is not proof). This is exactly the extra context the annotations cannot supply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and starting guidance are front-loaded, but the body is one very long, dense paragraph mixing invocation syntax, output formats, analysis workflow and caveats, with repetition ('before searching or reading' recurs). For a tool this complex some length is warranted, yet several clauses could be split or trimmed without loss.

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 8 parameters, no output schema and no required fields, the description carries the return-shape burden itself and does so: it describes file paths and line numbers, per-declaration aggregation with @line sites, and how listing detail degrades from exported declarations to file names/line counts to modules-only. Edge cases, defaults and continuation are all covered.

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?

Despite only 50% schema description coverage, the description supplies meaning for effectively every parameter: path '.'/directory/file semantics, name as Container.member, line as the containing-or-disambiguating declaration, depth directional caps, direction INCOMING/OUTGOING/BOTH, includeTests/includeUnresolved, and offset used with otherwise unchanged arguments. It materially exceeds the schema text.

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 gives a precise set of verbs and resources: it returns callers, callees, impact, directory/module contents and per-declaration detail, with language coverage and line/file output named. The scope (static project map, zooming from project to a single declaration) is unmistakable. What it does not do is name or differentiate itself from the sibling tools it overlaps with (project_find_references, project_search_map), so the agent must infer the boundary itself.

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?

Strong when-to-use guidance: 'Use this before grep or reading files', 'Start here to see what exists before searching or reading', plus a concrete impact-analysis workflow (INCOMING + depth up to 8, continue from NOT EXPANDED declarations, confirm entry points in source). The gap is that the alternatives named (grep) are external, not the actual sibling MCP tools whose overlap with this one is the real routing risk.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: results are relevance-ranked, grouped by file, expose declaration name/kind/1-based line range/matched fields, and continuation is via offset with unchanged conditions. The only gap is that no output schema exists to cross-check the described result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: purpose, then matching modes, then result shape, then next-step, then limitation. Mild redundancy in restating the ANY/ALL/LITERAL modes that the schema already defines verbatim, and the run of sentences is long, but every sentence carries usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters and no output schema, the description does the heavy lifting by describing ranked, file-grouped results with declaration metadata and by warning about the absence-proof limitation. It is largely complete, falling short only on the semantics of 'kinds' and 'maxResults'.

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 only 17% (matchMode alone), so the description must carry the rest. It does explain matchMode semantics and offset-based continuation, and implies the query matches name/path/documentation, but 'kinds', 'maxResults' (default 20, max 200) and the 'path' scope default remain undocumented. Partial compensation, not full.

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') and the search surface (name, path, documentation). It explicitly contrasts itself with project_explore_map (callers) and with full-text search, so an agent can pick it correctly 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?

Gives the ordering rule ('before exploring its callers with project_explore_map'), the follow-up step ('Zoom into a result with project_explore_map({path,name})'), and an explicit when-not ('This is not a full-text search and does not prove absence; search the source text itself for exact text'). 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.