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

The description asserts 'Read-only, deterministic, zero side effects', but the annotations declare readOnlyHint=false, which signals the tool may mutate state. This is a direct contradiction between prose and structured metadata and is the most consequential thing an agent needs to resolve before calling.

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

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

Front-loaded with the core semantic, then a when-to-use/when-not-to-use block and an output summary. Dense but each sentence carries routing or behavioral information; the output line earns its place since no output schema exists.

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 graph-analysis tool with no output schema, the description supplies the return shape (callers, subclasses, importers, cochange, summary), usage routing, and semantics. It would be complete were it not for the unresolved read-only claim, which leaves the tool's actual safety profile ambiguous.

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_id, limit, max_hops, and include_cochange are all documented in the schema with defaults and maxima. The description adds only loose framing (hop distance, co-edited files) and no format or syntax detail beyond the schema, 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 gives a precise verb+resource with scope: 'Reverse reachability from a node_id' enumerating callers, subclasses, importers, and co-edited files by hop distance. It is immediately distinguishable from siblings like repo_search and repo_read, which it names 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?

Explicit when-to-use ('before editing a symbol', 'what is the blast radius of changing X') and when-NOT-to-use with named alternatives ('do not use for open-ended search (use repo_search) or to read a symbol's own body (use repo_read)'). This is exactly the routing guidance an agent needs.

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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations by stating it is a read-only check of an in-memory background worker and by specifying the output fields (task_id, status, parsed file progress, error details). This goes beyond what the annotations alone provide, though it does not disclose edge cases like unknown task IDs.

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 well-organized with clear sections for usage, non-usage, follow-up, and output. Every sentence contributes useful information without redundancy, and the most important scoping detail (--async-build) is front-loaded.

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 one-parameter read-only tool with strong annotations, the description is complete: it explains the operation, when to call it, what not to do, what the output contains, and what to use afterward. The absence of an output schema is compensated by listing the expected JSON fields.

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 task_id parameter is already well documented as the ID returned by a previous async build call. The description does not add significant meaning beyond the schema, 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?

The description clearly identifies the tool as a status/progress query for a background index build task under --async-build, with a specific verb and resource. It also distinguishes itself from sibling tools by explicitly mentioning repo_search and repo_map as the post-completion alternatives.

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 provides explicit when-to-use guidance (polling after an async build was started) and when-not-to-use guidance (synchronous builds or when queries already succeed). It also names the correct follow-up tools, making the decision boundary unambiguous.

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 asserts 'Read-only, in-memory diagnostics, zero side effects,' but the annotations declare readOnlyHint=false and openWorldHint=true, directly conflicting with that claim. An agent relying on the prose would misjudge the safety profile of this tool. This is a genuine annotation contradiction rather than ordinary missing context.

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?

Well front-loaded and organized with labeled 'When to use', 'When NOT to use', and 'Output' segments; each sentence is short and purposeful. Slight redundancy in piling 'Read-only, in-memory diagnostics, zero side effects' on top of annotations that already cover mutability, and that stacking is what creates the conflict.

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 parameters and no output schema, the description supplies what an agent needs: what the tool reports, the named metrics, and where the sibling tools handle repo searching. The only real gap is that it does not reconcile its read-only framing with the annotation-declared openWorldHint/readOnlyHint values.

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 per the baseline the schema carries no semantics to explain. The description instead names the metric fields it returns (hits, misses, size, max_size, ttl_s), which is extra useful detail even though it is about output rather than input.

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 — 'Retrieve runtime diagnostic counters for the tool result cache' — and enumerates the counters (hits, misses, size, max_size, ttl_s). It is clearly distinguishable from siblings like repo_map and repo_search, which it explicitly names as not-this.

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 explicit 'When to use' (evaluating cache hit rate, debugging server performance) and 'When NOT to use' (searching repository contents or inspecting code structure) with named alternatives (repo_map, repo_search). Nothing is left 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 asserts 'Read-only, deterministic, zero side effects', but the annotations declare readOnlyHint=false, i.e. the tool is not guaranteed side-effect-free. That is a direct contradiction of structured metadata, so the behavioral claims cannot be trusted as written. Other disclosed traits (matching precedence, secret-file exclusion, ambiguity handling) are genuinely useful but are undercut by the conflict.

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

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

Front-loaded with the core action, then matching semantics, then when/when-not, then output shape. Dense but each block earns its place; the matching-precedence sentence is long but load-bearing for disambiguation behavior.

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, and the description compensates by enumerating the returned fields ({node_id, name, qualname, kind, path, start_line, end_line, lang}). Ambiguity handling, matching precedence and secret-file exclusion are covered, leaving little an agent needs that is missing — apart from the unresolved read-only conflict.

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 kind, name, limit and path_prefix are already documented with types, defaults and bounds. The description adds no per-parameter syntax or format detail beyond the schema, 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?

States a specific verb+resource ('look up a symbol or file's node_id by name') and immediately names the consumers (repo_neighbours, repo_read, repo_path_between, repo_blast_radius), so the agent can place it precisely in the tool graph.

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

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

Explicit 'When to use' (name already known from a traceback/grep/review comment, want node_id with no repo_search round trip) and 'When NOT to use' (open-ended text search → repo_search; repo layout → repo_map). Alternatives and the selecting condition are both spelled out.

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 asserts 'Read-only, deterministic, zero side effects,' but the annotations declare readOnlyHint=false. This directly contradicts the structured safety signal an agent relies on, so the behavioral disclosure is untrustworthy rather than merely incomplete.

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

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

Front-loaded with purpose, then usage, then output, in a logical order with no filler. It is somewhat dense and the staleness caveat is long, but every sentence carries actionable content.

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 present, the description supplies the return shape ('markdown summary of languages, hub files, and entry points') plus a staleness caveat about changed working trees. That is exactly the context needed to call and interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no inputs are required.

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 ('Retrieve a high-level structural map of the repository') and enumerates the content (languages, hub files, entry points). It is clearly distinguishable from siblings like repo_search and repo_neighbours, which it explicitly names.

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

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

Explicit when-to-use ('call this first at session start... before detailed queries'), explicit when-not-to-use with named alternatives ('do not use to search code (use repo_search) or inspect call graphs (use repo_neighbours)'). Routing is unambiguous.

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 asserts 'Read-only, deterministic traversal, no side effects', but the annotations declare readOnlyHint=false. This is a direct conflict on the tool's mutation profile, so the description cannot be trusted as behavioral disclosure. It also fails to reconcile the openWorldHint=true annotation with the claim of a fully deterministic, side-effect-free traversal.

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 and behavior are front-loaded, and the labeled When to use / When NOT to use / Output sections are easy to scan with no filler. Slightly over-specified for its length, and one sentence carries the erroneous read-only claim, but overall it is tight and well ordered.

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

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

With no output schema, the description compensates by specifying the return format ('- <EDGE_TYPE> <in|out>: <name> (<path:line>) [<node_id>]') and the edge direction convention (CALLS in vs CALLS out). Combined with the routing guidance and parameter coverage, an agent has everything needed to call and interpret this 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%: hops, limit, and node_id each carry their own defaults, bounds, and format examples in the schema. The description only adds the provenance hint for node_id (comes from repo_search citations) and does not clarify hops/limit interaction with the traversal, so baseline 3 is appropriate.

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

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

The description names a specific verb (traverse) and resource (code graph relationships from a node_id) and enumerates the edge kinds covered (callers, callees, base classes, definitions). It is immediately distinguishable from repo_search (text search) and repo_map (overview), which are 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?

It gives explicit 'When to use' and 'When NOT to use' sections, names the concrete trigger (a node_id obtained from repo_search citations), and routes the agent to the correct alternatives (repo_search for text search, repo_map for overview). Nothing about tool selection is left 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 asserts 'Read-only, deterministic traversal, no side effects,' but the annotations declare readOnlyHint=false, which tells an agent the opposite. These two signals directly conflict and an agent cannot tell whether invoking this tool may mutate state. The conflict is flaggable under the contradiction rule even though other behavioral details (bounded traversal, min-confidence reporting) are otherwise informative.

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

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

Front-loaded with the operation, then clearly delimited 'When to use', 'When NOT to use', and 'Output' segments. Dense but every sentence carries information an agent needs; 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, the description correctly supplies the return shape (JSON array of ordered {node_id, path, start_line, end_line, via_edge, confidence} objects), plus traversal bounds and default edge types. An agent has everything needed to call and interpret results — the only defect is the safety-signal conflict noted above.

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% — every parameter, default, and the CO_CHANGE caveat is documented in the schema itself. The description only restates the CO_CHANGE rule already present in the edge_types field, adding no new syntax or format guidance. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource+scope: find a bounded bidirectional path between two node_ids over named edge types, reporting minimum confidence per path. It distinguishes itself from siblings by explicitly naming repo_neighbours and repo_search as the wrong tools for adjacent tasks.

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

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

Explicit 'When to use' with a concrete example (HTTP handler to database write) and an explicit 'When NOT to use' that routes to the correct alternatives (repo_neighbours for one hop, repo_search for open-ended search). Nothing is left 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 asserts 'Read-only, deterministic, zero side effects', but the annotations declare readOnlyHint=false, i.e. the tool may modify its environment. That is a same-axis conflict between the prose and the structured hints, so an agent gets contradictory safety signals. The description does add genuinely useful context (indexed chunks have passed secret-path exclusion and redaction, absolute/'..' paths are refused), but the direct contradiction caps this dimension.

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

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

Front-loaded with the core action and scope, then cleanly segmented into when-to-use, when-not-to-use, and output. Slightly dense in the opening clause about HTTP/no-shared-filesystem, but every sentence carries information an agent needs.

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 supplies the return shape ('[cite: path:start-end]' header plus bounded text), the error conditions (refused paths), and the workflow placement relative to repo_search/repo_neighbours. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so path/context/start_line/end_line are already documented with defaults and the 500-line cap. The description adds only the path-provenance rule (must match a [cite: path:start-end] header) and the refusal behavior, which is baseline-level value over an already complete 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?

States a specific verb+resource (read a widened window of source text around a citation) and immediately scopes it ('from the indexed chunks rather than the filesystem'). It explicitly distinguishes itself from sibling tools repo_search and repo_neighbours, so an agent can route correctly without opening any 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?

Provides explicit 'When to use' (after repo_search or repo_neighbours to expand a [cite: path:start-end]) and 'When NOT to use' (never-indexed path, absolute or '..' path), plus the named fallbacks repo_search and repo_find_symbol. Both the positive and negative conditions are spelled out, not 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?

The description asserts 'Read-only, no side effects' while the annotations declare readOnlyHint=false. That is a direct conflict about whether the tool mutates state, which is exactly the kind of trait an agent relies on annotations for. The genuinely useful detail (secret files such as .env are excluded) is undercut by the contradiction.

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

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

Front-loads the mechanism, then uses labelled 'When to use' / 'When NOT to use' / 'Output' blocks so the routing information is scannable. It is dense but every sentence carries distinct information; slightly over-packed for its length.

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?

Even without an output schema, the description specifies the return shape (markdown citation blocks `[cite: path:start-end]` bounded by budget_tokens) and the retrieval pipeline, so an agent knows what it will get back. The unresolved read-only/readOnlyHint conflict is the only material 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 description coverage is 100%, so k, hops, query, and budget_tokens are already fully documented with defaults and ranges; baseline 3 applies. The description only echoes budget_tokens as the output bound and adds no syntax or format 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?

States a specific verb (search), resource (repository code), and the retrieval mechanism (BM25 lexical ranking expanded with graph neighbours), which is distinctive enough to separate it from every sibling. It also names the exact query types it serves (open-ended queries, locating implementations, error strings).

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 explicit 'When to use' and 'When NOT to use' sections, and routes the agent to the correct sibling in each exclusion case (repo_neighbours when you have a symbol node_id; repo_map for broad layout). Nothing is left to inference.

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