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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add what they cannot. It does: the traversal is transitive and restricted to calls and imports edges, which tells the agent exactly what relationships are followed. It omits any mention that results are capped or truncated, which would be useful for a walk that can explode on cyclic graphs.

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 with zero filler that front-loads the core relationship definition. Nothing redundant and nothing that could be trimmed without losing meaning.

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 should hint at what comes back and how it is bounded. It explains the traversal but not that results are limited by `limit`, that `expand` changes the return shape, or what happens on cycles in a bidirectional graph, leaving real gaps for a graph-walk tool.

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 db_path, node, limit (default 20) and expand (default false) are all already documented in the schema. The description adds no parameter-level meaning beyond that, 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?

The description gives a precise graph-theoretic definition of the operation: nodes from which the target is transitively reachable, scoped to calls and imports edges. That distinguishes it well from codetopo_descendants (the inverse walk) even though it never names the sibling explicitly. It is clear but relies on the title for the verb.

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 versus codetopo_descendants, codetopo_blast_radius, or codetopo_neighborhood, all of which operate on the same graph. Usage is only inferable from the direction of the relationship, which is weak guidance for a family of twelve sibling tools.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is not obligated to cover safety. It does add semantic value by defining what 'blast radius' concretely returns — dependents, overriders, implementers — but says nothing about cost, ordering, or whether the queried node is included in the result.

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 with zero filler; the core definition comes before any qualifiers. Nothing in it is redundant with the title or 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 read-only traversal over an indexed graph with a fully documented 4-parameter schema, the description covers the concept but not the operational edges an agent needs — traversal direction, whether transitive depth is bounded, and whether the source node appears in results are all left open with no output schema to fall back on.

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%: node, limit (default 20) and expand (full objects vs ids) are all documented in the schema itself. The description adds no parameter-level meaning such as how limit interacts with traversal order. Baseline 3 is appropriate when the schema does all 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?

The description names a specific analytical result ('nodes that break if a node changes') and enumerates the relationship kinds it collects (dependents, overriders, implementers). This is far more specific than a tautology and implicitly differentiates it from the generic graph-walk siblings like codetopo_descendants, though it never names them outright.

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 reach for this tool versus codetopo_descendants, codetopo_ancestors, or codetopo_neighborhood, all of which walk the same graph. No prerequisites (e.g. index must exist) or exclusion conditions are given, so the agent must infer selection from the name alone.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by specifying that traversal follows calls and imports edges, but it omits traversal semantics such as cycle handling, whether the start node is included, 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?

A single front-loaded sentence with no filler. Every word carries information about what is returned and which edges are traversed.

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 schema covers parameters and return-format toggling via expand, and annotations cover safety, so the core is present. However, for a traversal tool sitting among ancestors, blast_radius, neighborhood, and path siblings, the description omits the routing guidance an agent needs and says nothing about cycles or result scope.

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 node, limit, expand, and db_path are already documented in the schema. The description adds no additional parameter meaning, which is the expected baseline 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?

The description gives a specific verb-like result ('nodes transitively reachable from a node') plus the exact edge types traversed ('calls and imports'), so an agent knows this is a downward graph walk. It does not name or contrast with the obvious siblings (codetopo_ancestors, codetopo_blast_radius, codetopo_neighborhood), 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?

There is no when-to-use guidance at all. With siblings like codetopo_ancestors (inverse direction), codetopo_blast_radius, codetopo_neighborhood, and codetopo_path, the agent is given no condition for selecting this tool over those 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the burden is lower. The description adds one genuinely useful behavioral fact, that no database is required, but says nothing about the size/shape of the response or cost of calling it.

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?

Very short and front-loaded: the resource is named first, then the payload contents, then the no-database constraint as a fragment. Nothing is wasted, though the trailing fragment is slightly telegraphic rather than a full clause.

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 must hint at what comes back, and it does so by listing node/edge kinds, tier rules, and query vocabulary. For a zero-param introspection tool this is nearly complete; a sentence on how to use the returned vocabulary would make it fully self-sufficient.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. Schema coverage is 100% and the description correctly implies a call with no 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?

Names a specific resource, 'the schema this server speaks', and enumerates its contents (node and edge kinds, tier rules, query vocabulary), which distinguishes it from the sibling query tools like codetopo_index or codetopo_path. The verb is only implicit ('describe' lives in the name/title), and it never explicitly contrasts itself against siblings, 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?

'Needs no database' implies this can be called before any index exists, which is a usable contextual cue. However, it never states when an agent should reach for this versus codetopo_index or codetopo_stats, nor any exclusions, so usage is only implied.

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=true and destructiveHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral fact: these are diagnostics *recorded when the index was built*, i.e. a point-in-time snapshot rather than a live recomputation, and they are returned raw as data mirroring CLI output. It stops short of saying what happens on an index with no diagnostics or how findings are ordered.

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

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

One sentence, front-loaded with the key noun and its provenance. The trailing 'and the rest' is slightly vague filler, but the enumeration before it 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?

With no output schema, the description bears the burden of describing the return value; 'as data, exactly as the CLI prints them' hints at shape and formatting but doesn't say whether results are a list, grouped by severity, or empty when clean. Adequate for an agent to decide to call it, thin for one that must interpret the output.

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

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

The single parameter db_path has 100% schema description coverage, so the schema carries the semantics and baseline 3 applies. The description contributes nothing about the path value, though with one self-explanatory required parameter there is little to add.

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 precisely: diagnostics recorded at index build time, with concrete examples of what they contain (dependency cycles, multi-definitions, unresolved calls). The scope is clear enough to separate it from data-returning siblings like codetopo_stats, though it never explicitly contrasts itself with codetopo_verify, which also sounds diagnostic.

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 an agent should call this rather than codetopo_verify, codetopo_stats, or codetopo_diff, and no preconditions such as requiring an already-built index. The agent must infer usage from the name and the word 'diagnostics' alone.

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 establish read-only, non-destructive, closed-world behavior. The description adds genuinely new context by defining the output surface (structural deltas plus blast-radius movement) and the cardinality constraint on sources, which the schema does not enforce. It doesn't say anything about cost on large indexes, which would have pushed this to a 5.

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 first front-loads what is compared and what comes back, the second delivers the only hard input constraint. No filler, nothing repeated from the title.

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 carries return-value duty and does summarize the result shape (node/edge deltas plus blast-radius movement). What's missing is scale/cost expectation and how snapshot inputs relate to codetopo_snapshot, but nothing needed to invoke it correctly is absent.

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 baseline is 3. The description earns above baseline by stating the mutual-exclusivity rule ('exactly one before source and one after source'), which the flat four-property schema does not encode as a oneOf — this is real added semantics beyond the parameter descriptions.

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?

Specific verb+resource: compares two indexes or snapshot files and enumerates what it returns (added/removed/changed nodes and edges, blast-radius movement). It's clearly distinct from siblings like codetopo_snapshot (which produces snapshots) or codetopo_blast_radius (single-symbol analysis), though it doesn't name those siblings explicitly.

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

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

Gives an important input rule — exactly one before source and one after source — which implies the tool is for comparing two states of the same codebase. But it never states when to prefer this over codetopo_blast_radius or when a diff is not appropriate (e.g. unrelated codebases), so usage context is only implied.

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 cover the read-only, non-destructive profile, and the description adds real context beyond that: containment edges are excluded from the returned edge set, edges are grouped and counted, and unknown ids produce an error rather than an empty result. No mention of result size or depth limits, which is the only remaining gap.

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 dense sentence with the return shape front-loaded and the error behavior appended last. No filler, though the compressed enumeration of fields takes a moment to parse.

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 only two well-documented parameters, the description does the heavy lifting by spelling out what the response contains and how edges are organized. It only lacks guidance on result volume and on where valid node ids come from.

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% with both parameters documented, so the schema carries parameter meaning. The description does not clarify id format or how to obtain a node id (e.g., from codetopo_search_symbols), leaving it at the baseline.

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?

Specific verb and resource: fetch one node in full, enumerating the returned fields (kind, location, tier, defines, refs) and its incident edges grouped by kind and direction. 'One node' implicitly contrasts with graph-wide siblings like codetopo_neighborhood, but no sibling is named outright.

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 'one node in full' framing and the error-on-unknown-id note. It never says when to prefer this over codetopo_neighborhood, codetopo_ancestors, or codetopo_search_symbols, which is the main ambiguity for an agent choosing among graph tools.

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 read-only annotations, the description discloses a key behavioral contract: missing repo_path returns measured: false with a reason instead of inventing numbers. That fallback behavior and data-provenance constraint are exactly the kind of operational detail an agent needs before invoking it.

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 dense sentences front-load the metrics and then state the local-history fallback behavior. There is no filler, and the parenthetical definitions earn their place by clarifying the measurements.

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 measurement tool with full schema coverage, the description covers the core concepts and the important missing-repo_path fallback. It does not fully describe the measured output structure, but with no output schema this is a minor remaining gap rather than a blocking one.

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 all four parameters, including the repo_path omission behavior and min_support default. The description reinforces repo_path semantics but adds little parameter-level detail beyond the schema.

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 resource and analysis: hotspots and change coupling computed over a local working tree's git history. It is clear enough to separate this from general metrics or diff tools, but it does not explicitly name sibling tools or contrast itself with 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?

It gives a clear usage condition: history is local-only and omitting repo_path produces an unmeasured report rather than fabricated numbers. It does not describe when an agent should prefer another sibling tool, so it stops short of full alternative guidance.

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 this is a non-readOnly, non-destructive, closed-world write operation. The description adds essentially no behavioral context beyond that: it doesn't say whether an existing database is overwritten, whether indexing is incremental or full, how long it takes, or what permissions are needed.

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 with no wasted words. It is appropriately terse, though it leaves out information a mutation tool of this kind would benefit from.

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 that creates/writes a database, the description omits the operational context an agent needs: ordering relative to the query tools, overwrite/incremental behavior, and error or rate-limit expectations. Annotations cover safety and the schema covers parameters, but the usage and lifecycle picture remains incomplete.

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 all three parameters are documented in the schema itself. The description adds no syntax, format, or default details beyond what the schema already provides, so the baseline 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 (Index) and resource (repository) plus the target artifact (codetopo graph database), which is clear and distinct from the query-oriented siblings. It does not explicitly name any sibling or scope condition, but the purpose is unambiguous.

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

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

There is no guidance on when to run this versus the other codetopo_* tools, no prerequisites (e.g., must it run before queries), and no indication of alternatives. The only context is implied by the name.

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 cover the read-only, closed-world safety profile, and the description adds genuinely useful context on top: every metric's method is reported in the result, and no thresholds or verdicts are applied. That tells the agent the output is self-documenting raw measurement, which is not derivable from 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?

Two dense sentences, front-loaded with the scope and metric inventory, closing with the behavioral caveat. No filler and nothing that doesn't earn 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?

With no output schema, the description does the necessary work of listing what comes back and at what grain (per type and per package), plus the note that methods are embedded in results. It does not mention result volume or how types/packages are identified, which a caller interpreting the payload might want.

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 required parameter with 100% schema description coverage, so the schema fully carries parameter meaning and no extra description text is needed. The description correctly avoids restating db_path.

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 measurement domain ('coupling and cohesion measurements for every type and package') and enumerates the actual metrics (CBO, RFC, LCOM, TCC, ATFD, WMC, Ca, Ce, instability). An agent can tell this apart from codetopo_rank or codetopo_stats by the metric vocabulary, though no sibling is named explicitly.

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

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

'Measurements only - no thresholds, no verdicts' implicitly signals that this is the raw-metric tool rather than a scoring/ranking one, but the description never says when to reach for it versus codetopo_rank or codetopo_stats. Usage is inferable, not stated.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that by disclosing edge-type filtering (contains/defines excluded) and bidirectional traversal, but says nothing about result size, depth limits, or traversal cost.

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 tight sentence with no filler, and the scoping qualifier is front-loaded. The only flaw is that it reads as a sentence fragment rather than a complete clause, which slightly impairs immediate comprehension.

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?

No output schema exists, so the description needn't explain return values, and annotations carry the safety profile. For a traversal tool with three fully documented parameters, though, it is terse: it omits any sense of graph size, result limits, or how the neighborhood relates to the ancestor/descendant 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%, so node, depth, and db_path are already documented, including the depth default of 1. The description's 'within a few hops' and 'at the center' loosely restate the schema semantics without adding format or constraints, so the baseline 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?

The description identifies the resource ('the subgraph within a few hops of a node') and its bidirectional scope, which is specific enough to separate it from single-direction traversal. However, it is a noun fragment with no verb, and it never names the siblings (descendants/ancestors) it overlaps with, so differentiation is only implied by the 'contains/defines excluded' clause.

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 explicit when-to-use statement or named alternative. The parenthetical exclusion of contains/defines edges weakly hints that containment traversal belongs to codetopo_descendants/codetopo_ancestors, but the agent must infer that routing on its own.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description needn't restate that. It does add genuine behavioral facts beyond annotations: the result is the *shortest* path, edges are *typed*, and a no-path case yields an explanatory reason rather than an empty result. It says nothing about path representation, node-vs-edge output, or cost limits.

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

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

One sentence, front-loaded with the core operation and closed with the failure clause. Nothing is padding and nothing important is buried.

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 query with fully documented params this is thin but workable. The notable gap is that no output schema exists, so the description should describe what a returned path looks like (ordered nodes? typed edges?) — 'or the reason there is none' hints at an error string but leaves the success shape undefined.

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% — every parameter (db_path, from, to) has its own description — so the schema carries the parameter burden and the baseline is 3. The description's only added semantic is that paths are 'typed', which does not clarify the id format or what 'from'/'to' resolve against.

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?

Specific verb+resource: computes the shortest typed path between two named nodes, and additionally signals failure semantics ('or the reason there is none'). It is distinguishable from graph siblings like codetopo_neighborhood or codetopo_descendants by its pairwise from-to framing, though it never names those siblings.

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 explicit when-to-use, when-not-to-use, or alternative routing. The only implicit hint is that the tool is worth calling even when connectivity is doubtful, since it reports why no path exists. An agent still has to infer this tool's place among twelve graph siblings.

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 establish readOnly=true and destructive=false, so safety needs no restating. The description adds genuine context beyond them: the result states the method used for each count, and the output is explicitly framed as a measurement ranking rather than a quality score, which guards against misreading. It stops short of describing ordering, tie handling, or response 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?

Two compact sentences, front-loaded with the ranked metrics and followed by the important clarification about what the counts mean. Every clause carries information; the only mild weakness is the terse, fragment-like phrasing of the first sentence.

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, three-parameter ranking tool with no output schema, the description covers what is ranked, that counts are method-annotated in results, and that the output is not a quality judgment. Ordering, pagination behavior, and empty-result handling remain unstated but are minor for this shape of tool.

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 all three parameters already carry descriptions including the default metric (blast_radius) and default limit of 20. The description restates the same four metric names but adds no syntax, format, or interaction detail beyond the schema, so baseline 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?

The description gives a specific verb and resource ('top symbols by fan-in, fan-out, blast-radius size, or cyclomatic complexity') and names the exact metrics that are ranked. It distinguishes itself implicitly from metric-reporting siblings via 'A ranking of measurements, never a score of code quality', though it never names codetopo_metrics or codetopo_blast_radius directly.

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

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

Usage is only implied: the reader infers this is for finding the top-N symbols under a chosen metric. There is no explicit guidance about when to prefer this over codetopo_blast_radius (which appears to measure the same thing for a single symbol) or codetopo_metrics (a related aggregation). No exclusions or prerequisites are stated.

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=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral detail: matching is case-insensitive and substring-based on the label, which tells the agent a fuzzy query will match many symbols. It doesn't discuss result ordering or how limit truncates output.

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

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

One sentence, fully front-loaded: behavior first, then the workflow position. Nothing is redundant with the title, and every clause 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?

For a simple read-only search with a fully documented 3-parameter schema, the description covers what the tool does and where it sits in the workflow. With no output schema, return shape (what a matched symbol looks like beyond its label) is left implicit, which is a minor gap.

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 baseline is 3. The description nonetheless sharpens the meaning of `query` beyond the schema's generic "Name fragment to search for" by specifying case-insensitivity and that matching is against the label field.

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 symbols by name") and immediately nails the matching semantics (case-insensitive substring of the label). It also positions itself against the exact-id queries, so an agent can distinguish it from codetopo_get_symbol 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?

The phrase "the discovery step before the exact-id queries" gives a clear role in the workflow and implies the alternative (get_symbol by id). It stops short of naming that sibling explicitly or stating when not to use this tool, so it's clear context rather than full routing.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope context ('whole graph') and the audit-head binding, but does not describe output format, snapshot destination, or any resource cost. Adds some value beyond annotations, but not rich behavioral detail.

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

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

One sentence, front-loaded with the core action and scope, with no wasted words. The audit-head qualifier adds context without bloating the definition.

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 single-parameter, read-only export tool with annotations covering safety, the description is adequate but leaves notable gaps: it does not explain what a 'portable snapshot' contains, where it is written, or what the audit head binding implies for the caller. With no output schema, some return/side-effect expectation would help.

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% and the single db_path parameter is already documented in the schema. The description adds no additional parameter meaning, so the baseline score 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 (Export) and resource (whole graph as a portable snapshot), which is clear and distinguishable from the query-oriented siblings. It stops short of explicitly differentiating itself from sibling tools like codetopo_stats or codetopo_verify, so it is not 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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives to consider. An agent must infer from the verb alone that this is the tool for exporting a snapshot.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds something the annotations do not: the shape of the result (node and edge totals plus per-kind breakdowns), which matters especially since there is no output schema. It omits any cost/latency hint for large indexes, keeping it below 5.

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 fragment that names the resource and the payload with no filler; every clause carries information. It is appropriately minimal for a one-parameter read-only 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 simple read-only tool with one fully documented parameter and clear annotations, the description gives enough to call it correctly and to anticipate the return content despite the absence of an output schema. The main missing piece is context about when an index exists or how expensive the stats call is.

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

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

There is a single parameter (db_path) and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax, format, or defaulting detail beyond the schema, which is the expected baseline of 3 for high-coverage schemas.

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 (an index) and a specific output (node and edge totals with per-kind breakdowns), so an agent can immediately tell this is the counting/summary tool. It does not explicitly contrast itself with siblings like codetopo_index or codetopo_describe_schema, so it stops 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 stated prerequisite (e.g. that an index must already be built), and no mention of alternatives among the dozen sibling codetopo tools. Usage is only inferable from the noun 'index' and the word 'totals'.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the chain is 'tamper-evident', implying a hash/chain integrity check, but says nothing about what a failed verification means, whether it raises or returns, or whether it is expensive to run.

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

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

A single short sentence with the object of verification front-loaded and no filler. It is appropriately sized for the operation, though one clause more of substance would not have hurt.

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 one fully documented parameter and clear read-only annotations, the tool is simple enough that the definition is nearly sufficient. The gap is the return contract: no output schema exists, so the description should at least indicate that verification yields a pass/fail or chain-status result, which it does not.

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 db_path parameter, and the description adds no additional semantics (e.g. whether the path is to an index root or a database file). Baseline 3 applies when the schema already carries the parameter meaning.

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 (verify) and a specific resource (the tamper-evident audit chain of an index), so the agent knows this is an integrity check rather than an indexing or traversal operation. It does not, however, distinguish itself from any named sibling or reference the index it operates on in terms of a sibling relationship.

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 (e.g. must the index be built first?), and no mention of alternatives such as codetopo_stats or codetopo_snapshot. The agent must infer the trigger condition for verification entirely from the tool name.

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