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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context: results are approximate ('likely names') and include both symbols and files to open. However, it does not disclose pagination, ranking, or how the intent is interpreted.

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

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

The description is one short, front-loaded phrase with no filler or redundancy. It conveys the essence of the tool efficiently, though it is compact enough that some information is sacrificed for brevity.

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 nine parameters, no output schema, and only a read-only annotation, the description is far too sparse to fully guide an agent. It omits parameter semantics, result structure, pagination behavior, and how to shape a good intent query.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's lack of documentation. It only indirectly covers 'intent' via 'plain-language description' and leaves the other eight parameters including kind, repo, limit, cursor, and keywords entirely 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 states the core function: mapping a plain-language description to likely symbols and files to open. This clearly distinguishes it from siblings like find_symbol, which target exact symbol lookups. However, it is phrased as a noun phrase rather than an explicit verb+resource statement, which slightly weakens clarity.

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 'plain-language description' implies this tool should be used when the user describes intent rather than naming an exact symbol. But it does not explicitly explain when to prefer find_by_intent over find_symbol or find_references, nor does it list exclusions or alternatives.

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?

The readOnlyHint annotation already covers safety, and the description adds meaningful behavioral context: it separates exact uses from package-level dependencies and notes that a language server stops at its workspace, implying this tool spans workspaces. It does not disclose pagination, cursor behavior, or result shape, so the additional transparency is moderate.

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

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

The description is very concise and front-loads the core purpose in the first clause. Both sentences earn their place, and there is no filler or repetition, though the elliptical noun-phrase style and lack of a verb make it slightly less polished than the strongest examples.

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 tool with 10 optional parameters, no parameter descriptions, and no output schema, the description is too sparse to allow correct invocation: an agent can guess the tool's purpose but not what to pass for path, repo, stable_key, qualified_name, or response_format. It provides enough context for selection but not enough for reliable execution.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 10 parameters and 0% schema description coverage, the description carries the burden of explaining parameter meaning, but it does not mention path, repo, stable_key, qualified_name, view, cursor, or any other parameter. The only hint is the word 'symbol', which could relate to qualified_name or stable_key, but no explicit mapping is given.

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 clearly identifies the tool as finding consumers of a symbol in other repositories, and the phrase 'exact uses kept apart from package-level dependencies' distinguishes it from dependency-level queries. It lacks an explicit verb and is phrased as a noun fragment, so it does not fully meet the top bar, but the resource and scope are intelligible.

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 when to use this tool: when you need consumers beyond the current repository and want exact uses rather than package-level dependencies. However, it never names alternatives such as find_references or states explicitly when not to use this tool, leaving usage guidance to inference.

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 readOnlyHint annotation, the description discloses type-checked behavior, homonym handling, the meaning of an empty result, ambiguity resolution, and the 'view: files' behavior. This is rich behavioral context that materially changes how an agent interprets 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?

Four sentences, each earning its place: purpose, behavioral distinction, usage shortcut, and a view variant. The most important information is front-loaded, and there is 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?

The description covers the minimal invocation path well and explains key result semantics, but with 15 optional parameters and no output schema it leaves advanced usage undocumented. There is no mention of pagination via cursor/limit, language or repo scoping, or what the default response shape is. It is adequate for basic calls but not fully complete given the parameter surface.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, but it only explains two parameters: the bare 'name' usage and 'view: files'. The remaining 13 parameters—path, repo, limit, cursor, language, direction, confidence, edge_kinds, repository, stable_key, qualified_name, include_derived, response_format—receive no semantic explanation.

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 line, 'Who calls or references a symbol,' states a clear verb and resource. The description goes further by contrasting with grep and explaining type-checked semantics, but it does not explicitly distinguish this from sibling tools like find_symbol or trace_dependencies.

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 gives practical usage context: a bare name suffices, ambiguous names return candidates, and an empty answer means nobody calls it. It does not explicitly state when to prefer an alternative sibling tool, so exclusions are missing.

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?

There are no meaningful annotations, so the description carries the behavioral burden. It conveys that this is a search/lookup operation with flexible name matching and filters, but it does not disclose pagination behavior, result shape, or index/search limitations.

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 lead with the tool's purpose and then list the narrowing options, with no filler or repetition. Each phrase adds 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?

Given 10 parameters, 0% schema description coverage, no annotations, and no output schema, this short description leaves important call behavior unspecified, including pagination, output formatting, and derived-symbol handling. It is a strong summary but not complete enough for an agent to configure the tool confidently in all cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must add parameter meaning. It does explain the required name parameter's matching flexibility and maps kind, repo, and path_prefix as narrowing filters, but it leaves mode, view, limit, cursor, include_derived, and response_format 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 opens with the core action, finding where a symbol is declared, and specifies the matching modes (name, qualified name, prefix, substring). This clearly distinguishes it from sibling tools like find_references (where used) and get_symbol (retrieve symbol details).

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 states the intended scenario (locate a declaration site) and how to narrow results with kind, repo, and path_prefix. It does not name sibling alternatives or explicitly state when not to use it, but the declaration-focused wording supplies clear context.

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?

The readOnlyHint annotation already establishes safety; the description adds the key behavioral trait that this tool follows a dependency chain and reports reach by repository, package, depth, and relation kind. It does not, however, disclose output shape, pagination behavior, or how confidence and edge kinds are applied—details that would matter for a graph-query 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?

The description is two compact sentences with no filler, and the main idea is front-loaded. The second sentence about grep earns its place by clarifying the tool's transitive nature, even though the phrasing is 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?

Despite its simplicity, the tool has a large optional parameter set, no schema descriptions, and no output schema. The description does not explain which identifier parameter to use, how pagination works, what response_format values are accepted, or what the returned blast radius looks like, making it insufficient for confident 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?

With 0% schema description coverage and 14 parameters, the description must compensate, but it only hints at repository, depth, relation kind, and symbol identity. Parameters such as cursor, max_nodes, confidence, include_derived, stable_key, and response_format receive no guidance, leaving the agent to guess their meaning or required combinations.

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 clearly conveys the tool's purpose even without an explicit verb: it shows what a change to a symbol reaches across repositories, packages, depth, and relation kinds. This distinguishes it from ordinary reference lookup, though it does not explicitly name sibling tools such as trace_dependencies or find_cross_repo_consumers.

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 'Grep does not follow a chain' implies the tool should be used when transitive dependency traversal is needed, rather than simple text search. However, it provides no explicit when-to-use guidance against sibling tools like find_cross_repo_consumers or trace_dependencies, leaving the choice largely to inference.

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?

The description reveals output behavior beyond the readOnlyHint annotation: results are grouped by file and include kind, signature, and range. It also gives a cost-oriented hint. This adds useful context without contradicting annotations.

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

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

The description is two compact sentences. The core meaning is front-loaded, and the second sentence adds practical usage guidance without redundancy.

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 basic use with only required parameters, the description is adequate: it tells the agent what the tool returns and when to use it. However, with no output schema, minimal annotations, and several optional parameters that affect pagination and response format, the description leaves meaningful gaps for an agent trying to fully understand invocation options.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there are 8 parameters, but the description only clarifies the notion of a path and, ambiguously, 'kind' as an output field. Parameters like limit, cursor, view, include_members, and response_format are left completely unexplained, so the description does not compensate for the schema 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?

The description states a specific operation: retrieving declarations under a path, grouped by file, with kind, signature, and range. This clearly goes beyond restating the tool name, though it does not name a sibling or explicitly contrast itself with get_source or get_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?

It gives explicit guidance to use this for a package and hints that reading a single small file directly is cheaper. It does not name the alternative tool or provide a formal when-not-to-use list, but the intended context is clear.

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?

The readOnlyHint annotation already covers the safety profile. The description adds useful behavioral context: it returns source for multiple symbols, excludes line numbers, and spans files/repositories. It does not explain response format or potential limitations, but it does not contradict the annotation and discloses the most relevant behavioral trait.

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

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

The description is two short sentences with the core purpose front-loaded and the usage rationale following. There is minor redundancy of 'one call' appearing twice, but otherwise every phrase earns its place and there is 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?

With no output schema, no parameter descriptions in the schema, and only a terse description, the definition omits key invocation details. The agent cannot infer how to structure the symbol objects (path, repository, stable_key, qualified_name), what context_lines does, or what response_format values are accepted. This is incomplete for a tool with three parameters and zero schema-level documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only implies that 'symbols' is the main input by saying 'several symbols' and gives a hint about cross-repository support. context_lines and response_format are completely unexplained, leaving the agent without enough information to set them correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool returns the code of several symbols in one call, making the core purpose clear. It also distinguishes itself from per-range reads by noting cross-file and cross-repository support, which helps differentiate it from the sibling get_symbol. It lacks an explicit verb like 'retrieves', but the meaning is still unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit usage preference: prefer this tool over reading each range when you need multiple symbols, citing benefits like no line numbers and one call across files/repositories. It does not name particular alternative tools or state exclusions, but the guidance is clear enough for an agent to make a reasonable choice.

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 provide readOnlyHint=true, so the safety profile is covered. The description adds useful context about the returned symbol data and the two lookup modes, but it does not disclose behavior for ambiguous matches, missing symbols, or precedence when multiple parameters are provided. Given the read-only annotation, this is acceptable but not thorough.

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

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

The description is a single dense sentence with no filler, front-loading the returned data before the lookup modes. Every phrase adds relevant information and the length is appropriate for the tool's complexity.

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, five optional parameters, and eleven sibling tools, the description is thin on operational context. It does not explain response_format, valid parameter combinations, ambiguity/error behavior, or how get_symbol relates to find_symbol and get_source, so an agent receives insufficient guidance for reliable 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 0%, so the description carries the burden of explaining parameters. It does map stable_key to one lookup mode and repository, path, qualified_name to another, adding meaning beyond bare schema names. However, response_format is left unexplained, and with no required parameters the agent cannot be certain which parameter combinations are valid or whether the modes are mutually exclusive.

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 identifies a specific action ('get'), a specific resource ('one symbol'), and the returned metadata (package, signature, visibility, line range). It also distinguishes the lookup style from search-oriented siblings by mentioning exact retrieval via stable key or repository/path/qualified name, though it does not explicitly contrast it with a sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given about when to use get_symbol instead of siblings such as find_symbol, find_references, or get_source. The description implies an exact-lookup use case but does not state exclusions, prerequisites, or scenarios where another tool would be more appropriate.

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?

The readOnlyHint annotation already signals a safe read operation, and the description adds meaning beyond that: it discloses the kind of status information returned (counts, provenance, moved flag) and ties it to staleness checking. No contradiction with annotations was found.

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 carry all the essential content: what the tool reports and when to call it. The wording is front-loaded and contains no filler or redundant restating of the tool name.

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-parameter read-only status tool, the description covers what it returns and when to use it. Since no output schema exists, the explicit enumeration of counts, provenance, and repository-moved status partially compensates, though terms like 'published generation' and 'provenance' are left somewhat underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, so the parameter burden is minimal. With no parameters to document, the baseline of 4 applies; the description appropriately says nothing about parameters because there are none to explain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource—the published generation—and specifies three concrete data categories it exposes: counts, provenance, and repository-moved status. It is clearly distinct from retrieval/indexing siblings like find_symbol or index_project, though it lacks a direct verb like 'reports' or 'returns'.

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?

Provides an explicit trigger: 'Call it when an answer looks stale.' This gives clear context for when to use the tool. It does not spell out when not to use it or name specific alternatives, but the sibling list makes the status-versus-search distinction apparent.

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 destructiveHint annotation, the description clarifies exactly what is affected—the graph is rebuilt—and explicitly states that source projects are never written to. It also adds the cost implication of a rebuild, which is valuable behavioral context and does not contradict the annotations.

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

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

Three short sentences, each carrying essential information: purpose, approval, batching/cost, and source safety. The key constraints are front-loaded and there is 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?

The description covers the critical workflow, safety boundary, and rebuild cost, and an output schema exists to describe return values. However, with five undocumented parameters and ambiguity about how to supply a single project versus multiple projects, the agent still has to fill significant gaps before calling the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for explaining the parameters. It only indirectly covers projects via 'pass every project in one call' and confirmed via 'explicit user approval'; name, path, languages, and the relationship between the top-level fields and the projects array are left 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 states a specific action: register projects and rebuild the graph, which clearly distinguishes this from the read-only find/get/list siblings. It does not explicitly name an alternative or contrast itself with sibling tools, so it stops just short of the top score.

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 gives concrete operational guidance: only run after explicit user approval, and pass every project in one call because a rebuild costs the whole corpus. It does not explicitly say when not to use the tool or which sibling to prefer in other situations.

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?

The readOnlyHint annotation already signals safe read-only behavior, so the description does not need to restate that. It does add useful context about the output's scope—repositories covered by the published graph and their indexed commits. However, it does not mention pagination behavior, ordering, or whether results are stable snapshots, which would be valuable for a cursor-based list.

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

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

The description is a single compact sentence with no filler. It front-loads the core subject and includes only the essential distinguishing detail—the associated commit—without redundant phrasing.

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?

While the tool is simple and read-only, the description omits parameter semantics, pagination behavior, and any connection to the broader published-graph state. There is no output schema to compensate, so an agent lacks enough detail to confidently construct a correct paginated call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the parameters limit and cursor have no schema-level documentation. The description adds nothing about their meaning or interaction, leaving the agent to guess that cursor is for pagination. This is a significant gap in a tool whose only two parameters are entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact resource—repositories covered by the published graph—and adds the meaningful detail that each entry includes the commit it was indexed at. The tool name supplies the verb 'list,' so the overall purpose is clear. It differentiates from sibling tools like find_symbol or trace_dependencies by its repository-level scope, even though it does not explicitly compare itself to them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, how pagination works, or what context would make it the right choice. The description only says what the tool returns, leaving the agent to infer when to call it. This is a clear gap given the tool has siblings and two pagination parameters.

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?

The readOnlyHint annotation already covers safety, and the description adds some behavioral context: traversal is outward, depth-bounded, and can return a route to a named symbol. It does not disclose cycle handling, response shape, performance characteristics, or failure modes, so the disclosure remains minimal but not contradictory.

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

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

The description is short and front-loaded with the core behavior, but the grammar is awkward and incomplete ('Pass to for the route...'), which hurts readability. Each sentence contributes something, but the overall structure is fragmented rather than cleanly specifying behavior, parameters, and alternatives.

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 tool with 17 parameters, no output schema, and no parameter descriptions, the description covers only the basic notion of outward traversal and a single routing parameter. An agent would struggle to know what `edge_kinds`, `stable_key`, `view`, `cursor`, or `response_format` control, and what the tool returns. The definition is far from 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 description coverage is 0%, and the tool has 17 parameters. The description meaningfully explains only `depth` and `to`; the remaining 15 parameters such as `edge_kinds`, `max_nodes`, `stable_key`, `confidence`, and `response_format` receive no guidance. This is far too little semantic support for an API of this size.

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 communicates that the tool traces what a symbol reaches outward, bounded by depth, which identifies it as a transitive dependency tracer. It also explains that passing `to` yields the route to one named symbol. However, it does not explicitly distinguish itself from sibling tools like find_references or get_blast_radius, and the phrasing is elliptical.

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 line 'Grep does not follow a chain' gives a hint that this tool should be used when transitive or multi-hop dependency chains are needed, rather than simple text search. But it does not mention when to prefer or avoid sibling tools such as find_references or get_blast_radius, leaving most usage decisions implicit.

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