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

With no annotations the description carries the full burden, and it delivers unusually rich context: per-mode latency, server-side arg validation, the uniform `{ protocol_version, capabilities, _meta, results }` envelope, the `role` discriminator values, and that scope filters only apply in pr-impact mode. The main gap is that it doesn't flag the state-changing side of auto_update/async_update (index refresh) or any permission requirements.

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

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

Dense and front-loaded: value proposition first, then modes, then response contract, then the filter-scope caveat. It is long, but every sentence carries information an agent needs; only the timing figures are marginally expendable.

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 17-parameter, three-mode tool with no output schema, the description compensates by documenting the response envelope, item structure, and role vocabulary. Combined with 100% schema coverage, an agent has what it needs to select a mode and call it 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 100% (baseline 3), and the description adds cross-parameter semantics the schema can't express well: which mode each argument belongs to and the fact that include/exclude/exclude_tests are ignored outside pr-impact. It doesn't add format examples beyond what the schema already supplies inline.

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

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

The opening states a concrete verb+resource ('Multi-source bundle') and immediately frames it against the exact sibling tools it replaces (show → callers → callees → similar). The three modes are named and each is scoped to a distinct use case, so an agent can distinguish it from find_symbol, callers, callees, and similar without opening a schema.

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

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

It explicitly says 'Prefer over chaining find_symbol/show/callers/callees when you need cross-section context on one symbol or a PR,' giving both the alternative and the selecting condition. Mode-specific guidance (symbol = one symbol, pr-impact = a git base ref, project = ranked symbols) further routes the agent to the correct mode.

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?

No annotations provided, so the description carries the full burden. It discloses latency (~4ms indexed, fallback to live-scan), decorator/annotation surfacing behavior for 6 languages (with concrete examples), that Rust #[derive] is intentionally filtered, and diff scoping semantics. Solid behavioral disclosure, though it doesn't cover auth, rate limits, or error modes.

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 core purpose well, but is quite long and includes a verbose Phase-number changelog block (14.2 + 14.2.2 + 14.2.1) that reads like release notes rather than tool-selection guidance. The decorator detail is useful but the enumeration could be tightened significantly.

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 14-param, no-output-schema tool, the description covers fallback behavior, result format hints ('resolved outgoing edges as records'), workspace shape-changing behavior is in schema, and diff scoping. Complete enough to call correctly; could say more about output record shape since there's no output schema.

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 the schema already documents all 14 parameters thoroughly. The description reiterates 'since/since_branched/changed_only (mutually exclusive)' which is also in the schema. Baseline 3 is correct 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: 'Direct callees of a function via the persistent call-graph FST'. This clearly distinguishes it from siblings like 'callers' (inverse direction) and 'Read+manual scanning'. The parenthetical about fallback behavior adds specificity.

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 clear context: 'Prefer over Read+manual scanning when you want to know what a function calls without reading the whole body'. This gives an explicit alternative and the condition selecting this tool. No explicit when-not-to-use, but strong positive 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?

No annotations, so the description carries the burden and does well: it discloses the fast-path timing (~4ms indexed), live-scan fallback, parse-time edge resolution, and the decorator rightmost-identifier convention including the `serde` vs `rename` edge case and filtered `#[derive(...)]`. It omits any mention of index side effects (auto_update bootstrap writes an index) and auth/permission requirements.

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 the grep comparison are front-loaded, but the middle devolves into a long run-on sentence enumerating five near-identical framework examples that restate the same rightmost-identifier rule. Dense and useful, but the example list is repetitive rather than earning each 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?

For a 14-param read tool with no annotations and no output schema, coverage is strong: diff-scoping exclusivity, decorator semantics, and workspace shape are all addressed. The remaining gap is return-format behavior beyond the workspace note, which the missing output schema leaves to inference.

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 the baseline is 3, but the description adds real semantic value the schema lacks: the rightmost-identifier convention that determines what `symbol` matches, the decorator/attribute edge sources, and how that convention makes `callers get` mix decorator handlers with `.get()` calls.

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?

Opens with a specific verb+resource: 'Direct callers of a function via the persistent call-graph FST'. It explicitly distinguishes itself from grep and names siblings (paths, tests_for) so an agent can route correctly without opening schemas.

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 'Prefer over grep for `who calls Foo?`' with the reason (grep hits doc comments/string literals), plus guidance to narrow with include/exclude and to pair with paths for multi-hop chains. When-to-use and alternatives are both 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?

No annotations are provided, so the description carries the burden. It does disclose the return payload (protocol version + capability matrix), which is the key behavioral fact and implies a side-effect-free read. It does not mention auth requirements, caching, or whether negotiation is idempotent, leaving some gaps.

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 the verb first and zero wasted words. Ideal structure for a trivial no-arg endpoint.

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 tool with no output schema, the description names what is returned but not the shape of the capability matrix. Adequate to call the tool, but an agent cannot anticipate the response structure.

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, which is the baseline-4 case. There is nothing to document and the description correctly implies a no-argument call.

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 verb ('Return') and resource ('vex protocol version + capability matrix'), making the tool's function unambiguous. It does not explicitly name a sibling to differentiate from, but the sibling set is entirely code-analysis tools, so confusion is unlikely.

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?

'for client capability negotiation' implies the context of use, which is a reasonable cue. However, there is no explicit when/when-not guidance or named alternative, so the agent must infer the trigger condition.

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?

With no annotations, the description carries the burden and does well: it discloses cost (~4ms), that no body extraction or ranking happens, and that it prevents downstream errors. It omits that auto_update (default true) can bootstrap or mutate the index as a side effect, which is a meaningful behavioral gap for a tool framed as a cheap probe.

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 sentences, zero waste, with the core capability front-loaded before the routing guidance. Every clause 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?

For a 7-parameter tool with no annotations and no output schema, the description covers purpose, cost, and routing well; workspace-mode result shape and index-refresh behavior live in the schema. The one unaddressed item is the index-mutation side effect implied by auto_update, which an agent might want called out.

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 every parameter (including the deprecated names alias, workspace shape branching, and stale-check flags) is already documented in the schema. The description adds no parameter-level detail beyond what is structured, 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?

States a specific verb (confirm existence) and resource (symbol names in the index), and explicitly contrasts itself with ranked search and body extraction. An agent can distinguish it from show/usages/callers/search 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?

Explicit when-to-use ('before show / usages / callers when working from an unverified list') and the reason ('skip the symbols that don't exist instead of letting downstream tools error'). Names the alternatives and the condition that selects this one.

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?

With no annotations, the description carries the full burden and does well: it discloses the output shape (structured symbol records, iterable directly) and the change taxonomy, which goes beyond the schema. It does not discuss ordering, whether results are paged/truncated relative to `limit`, or read-only guarantees, which are minor omissions for a diff 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?

Two sentences, both front-loaded: the first defines the operation and its output, the second routes the agent away from `git diff`. No filler or restated boilerplate.

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 correctly steps in to describe the return value as symbol records grouped by change type. It is sufficient to call the tool correctly; only minor gaps remain (ordering, how `limit` truncation is signaled).

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 every parameter (base, limit, exclude/include precedence, project_root, exclude_tests) is fully documented in the schema itself. The description adds no parameter-level 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?

States a specific verb and resource ('symbol-level diff between a git revision and the working tree') plus the exact output categories (added/removed/moved/body-changed symbols). It distinguishes itself from the closest non-MCP alternative, `git diff`, and from line-hunk tools generally.

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?

Explicitly names the alternative ('git diff' + manual scanning) and the scenario that selects this tool ('PR review'), and explains why: structured symbol records vs. unified-diff text. Nothing is left to inference about when to reach for it.

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?

With no annotations, the description carries the burden well: it discloses the hard prerequisite ('Requires `vex index --semantic`'), the filtering behavior of min_body_lines, and the mutual exclusivity of the three diff-scoping flags. It stops short of describing the return shape (pair list) or how many pairs come back by default.

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 dense, front-loaded sentences: purpose, usage, then prerequisites and scoping flags. Every clause carries information, though the final scoping sentence packs several flags together and reads a bit like a spec dump.

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 16-parameter, zero-required, annotation-free tool with no output schema, the description covers the prerequisite, the filtering model, and the diff-scoping exclusivity — the things an agent most needs. The missing piece is what a result actually looks like (pair structure/ordering), which nothing else supplies.

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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot express — the mutual exclusivity of `since`/`since_branched`/`changed_only` and the fact that `no_stale_check` is redundant under `auto_update`. It restates threshold/min_body_lines meaning rather than extending it.

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?

Opens with a specific verb+resource+scope: 'Repo-wide near-duplicate scan: pairs of symbols whose embeddings exceed threshold.' That clearly separates it from symbol-lookup siblings, though it never names the closest siblings (find_similar, similar) and only alludes to them as 'manual similar-walks.'

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 concrete use cases ('refactor planning', 'dedup') and a comparison condition ('Prefer over manual similar-walks — duplicates evaluates all pairs once with min_body_lines filtering'). No explicit when-not guidance and no direct routing to find_similar/similar for the single-symbol case.

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?

With no annotations, the description carries the full burden and does well: it discloses that the tool is indexless (never builds), consumes only the existing index, and that min_ndcg drives a non-zero exit — i.e. it can fail. It omits behavioral traits like runtime cost or idempotency, so it is strong but not exhaustive.

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, all substantive: action, indexless precondition, CI intent, and the MCP json default lead in order of importance. Slightly dense with parentheticals, but nothing is pure 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?

For a four-param, no-output-schema tool with no annotations, the description covers action, deliverables, dependency ordering, failure semantics, and a default divergence between MCP and CLI. There is no output schema, but the return shape (per-query and aggregated metrics as EvalReport JSON) is named.

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 MCP-vs-CLI default for `json`. The description's parameter remarks largely restate schema content, 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 and resource ("Run the ranking-quality harness against a golden query set") and enumerates the exact outputs (nDCG@10, recall@10, MRR). This clearly separates it from sibling tools like `index`, `tests_for`, or `check`.

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

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

Gives explicit context ("Intended as a CI regression guard") and a prerequisite ("run `index` first if missing"). It lacks an explicit when-not-to-use or a direct comparison against a sibling such as `check`, so it falls just short of a 5.

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?

No annotations are provided, so the description carries the burden; it discloses the underlying HNSW vector index, the ~7-15ms latency, and that the index is built by `vex index --semantic`. It does not describe return shape or result ranking, and staleness/update behavior is left largely to the schema.

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 sentences, front-loaded with the core purpose, then mechanism, then routing guidance. Dense but every sentence earns its place with no 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 an 8-parameter tool with no annotations and no output schema, the description covers purpose, routing, and index/latency behavior well. It omits return-value expectations and ranking behavior, but the routing and index context make it largely callable as-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?

Schema description coverage is 100%, so all eight parameters are already documented, including the 'not an identifier' caveat on `query`. The description adds no parameter-level detail beyond what the schema 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 and resource ('Semantic-only search by natural-language description') with a concrete example mapping. It explicitly distinguishes itself from `search` and `find_symbol`, so an agent can identify the tool 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?

Gives an explicit decision rule: prefer this over search when no concrete identifier is known, prefer search when a partial name exists, and use find_symbol for identifiers. Both the when and the when-not with named alternatives are present.

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?

With no annotations, the description carries the full burden and does disclose real behavior: prefix fallback on exact match, index-based resolution, ~4ms latency, and constant-time probing vs. grep's byte scan. It omits that it is a read-only operation and any mention of index staleness/bootstrapping, but the core behavioral profile is well communicated.

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 tight sentences, front-loaded with the core verb+resource and mechanism, then routing guidance. Every sentence earns its place with no 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 a 9-parameter tool with no output schema, the description covers the primary use case and alternatives well; the remaining parameters (include/exclude globs, auto_update, async_update, no_stale_check) are fully covered by the 100% schema. Return values needn't be explained since none are promised.

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 9 parameters in detail. The description only reinforces the canonical `symbol` semantics ('exact name with prefix fallback') beyond that, so the 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?

States a specific verb (resolve) and resource (a symbol by exact name) plus scope and mechanism (FST inverted index, ~4ms). It explicitly distinguishes itself from two siblings, search and grep, so an agent can choose without opening the schema.

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

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

Gives explicit when-to-prefer conditions: over search 'when the symbol name is known and you want exactly that record back, not a fused-rank list', and over grep for definition-style lookup. It names the alternatives and the conditions that select them.

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?

No annotations are provided, so the description carries the full burden, and it delivers: no index required, full-scan cost, and that results are raw line matches without symbol context. It does not cover return shape or result-limit behavior beyond the schema, but the core behavioral profile is disclosed.

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 sentences, front-loaded with what the tool is, then usage, then the alternative-routing rationale. Every sentence earns its place with 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?

For a 9-parameter, no-output-schema tool, the description conveys the search model and its relationship to index-backed siblings, which is what an agent needs to choose correctly. It leaves return-shape details implicit, but the schema covers parameter nuance thoroughly.

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

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

Schema description coverage is 100%, so all 9 parameters (including nuanced ones like text, exclude_tests, workspace) are documented in the schema itself. The description adds no parameter-level meaning, 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 (search) and resource (file contents) and adds the distinguishing mechanism (regex, ripgrep-equivalent, no index needed). An agent can tell it apart from index-backed siblings like search and find_symbol without opening a schema.

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

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

Explicitly names the when (string literals, comments, config values, non-symbol text) and the when-not, routing identifier lookups to search/find_symbol/usages. It even justifies the routing with the performance contrast (index-backed ~4ms vs full-scan).

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?

With no annotations, the description carries the full burden and does so well: it distinguishes indexed FST (~ms) vs walker (`git log`, ~seconds) modes, discloses that indexed mode finds deleted symbols while the walker cannot, warns that omitting `limit` is unbounded, notes `exact_presence` latency, and explains `no_index` for regression checking. Missing only auth/permission context, which is minor here.

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 scope and then performance/mode tradeoffs; most sentences earn their place. Slight redundancy – the unbounded-latency warning appears both in the description prose and in the `limit`/`depth` schema descriptions – keeps it from a 5.

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 and no annotations, with 13 parameters, so the description must carry a lot, and it does: modes, latency, correctness differences, and history/version provenance. It stops short of describing the returned entry shape (versions, spans, convex-hull representation), which would help given the absent output schema.

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 the baseline is 3, but the description adds real value beyond the schema: the default-unbounded behavior of `limit`, the per-file latency of `exact_presence`, and the cross-parameter note that `diff` and `exact_presence` are mutually exclusive. It reinforces rather than repeats structured data.

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: 'Every historical version of a symbol reachable from a chosen tip.' It is clearly distinguishable from siblings like `find_symbol`, `diff`, or `callers`, and the extra sentence about deleted symbols sharpens exactly what makes this tool unique. An agent can route to it without opening the schema.

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

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

Gives three concrete use cases (inspect body/signature change over time, find when a bug was introduced, recover a deleted symbol's last definition) and conditions for latency-sensitive flags. It does not name a sibling alternative to prefer, e.g. when `diff` or `find_symbol` would be the better call, so it stops short of a 5.

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?

With no annotations, the description carries the full burden and does so well: it discloses the exact verdict rule (unsafe if strict_refs>0 OR callers>0, uncertain on text-only hits, safe only on all-zero) and the semantics of each channel. It is silent on read-only nature, auth/permissions, and rate limits, keeping it from a full 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?

Front-loaded with the core purpose, then the verdict rule, then the results shape — a logical progression. It is dense and slightly long with heavy parenthetical/backtick notation, but nearly every clause 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?

There is no output schema, so the description compensates by spelling out the return shape { symbol, verdict, verdict_explanation, channels{...} } and each channel block's fields. Combined with the fully-covered input schema, an agent has everything required to call and interpret it.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters; baseline is 3. The description references concepts (transitive_callers channel, prose-file text hits) that map to params like `depth` and `exclude_docs`, but 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+resource ("Delete-safety blast-radius report") and precisely scopes it as composing four named reference channels into a single verdict. An agent can distinguish it from siblings like `usages`, `grep`, and `callers` because the description explicitly names those as the channels it subsumes.

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?

"Use this BEFORE proposing to delete or rename a symbol" gives an explicit trigger, and it routes the agent away from the manual usages → grep → callers dance. This is a clear when-to-use with the alternatives named.

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?

No annotations are provided, so the description carries the full burden, and it does disclose meaningful behavior: it walks indexed inheritance edges, covers generic-parameterised bases, catches indirect inheritance, and has three mutually exclusive scoping switches. It omits return-shape and error/staleness edge cases, but the core behavioral profile is well conveyed.

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 tight sentences with zero waste, front-loading the core purpose before the grep comparison and the diff-scoping note. Every clause 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?

For a 13-parameter tool with no output schema and no annotations, the description leaves gaps: it never indicates what a result looks like (type names, paths, locations) and does not address the `subtypes` sibling. Parameter coverage is complete via the schema, so it is merely adequate rather than thorough.

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 baseline is 3. The description only reinforces the mutual exclusivity of `since`/`since_branched`/`changed_only`, which the schema already states for each parameter, adding no meaning beyond structured fields.

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

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

States a precise verb+resource ('Find every concrete type that extends a base class / implements a trait / interface') and names the scope it walks (indexed inheritance edges). It clearly separates itself from grep, but does not distinguish itself from the sibling tool `subtypes`, which appears to cover similar ground.

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

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

Gives an explicit when-to-prefer rule ('Prefer over grep for `find all subclasses of Foo`') with concrete reasons grep fails, and explains the three mutually exclusive diff-scoping modes. It stops short of addressing when to choose this over the sibling `subtypes`, leaving one routing question unresolved.

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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the build starts 'from scratch' (implying replacement of any prior index), it is a once-per-project operation, and semantic mode is slower. It stops short of explicitly stating that an existing index is overwritten or that the operation is expensive/irreversible, which would raise 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?

Three short sentences, each earning its place: the action, the run-once/use-update rule, and the semantic prerequisite. Front-loaded and free of 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?

For a five-parameter tool with no output schema and no annotations, the description covers the essential action, lifecycle guidance, and the key semantic prerequisite. Minor gaps remain around workspace-mode fan-out and what happens to pre-existing index data, but structured fields cover the parameter detail.

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 every parameter (gpu, device, semantic, workspace, project_root) is already documented in detail. The description only reiterates the semantic flag and its downstream effect; it adds no syntax or constraints 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?

States a specific verb and resource ('Build or rebuild the vex index from scratch') and explicitly distinguishes itself from the sibling `update` tool by contrasting full build vs incremental refresh. An agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use guidance ('Run once per project; use update afterward for incremental refreshes') and names the condition that selects the alternative. It also states the prerequisite for dependent tools (semantic=true required for find_similar / similar / duplicates).

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?

With no annotations, the description carries the full burden and does so: it states the v9 index prerequisite, the stale/frozen behavior after `vex update`, the empty-result contract with `empty_reason` and hints for old or `--no-clusters` indexes, and the critical caveat that cluster ids are stable only within one full-index generation and must not be persisted. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core definition and mode split, then prerequisites and caveats. Dense and information-rich with little waste, though a few sentences (id stability, empty_reason) are packed into long clauses that could be split for faster scanning.

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 13-parameter, no-annotation, no-output-schema tool, the description covers purpose, both operating modes, prerequisites, failure/empty behavior, and stability caveats. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters (baseline 3). The description still adds value by clarifying `limit`'s dual meaning (clusters vs matching symbols), the omit-`symbol`-to-list semantics, and the shape change in `workspace` mode, going beyond the schema text.

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

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

States a specific verb+resource ('De-facto modules: clusters of symbols that call/reference each other') and even names the algorithm (deterministic Leiden-CPM over call + ref + hierarchy edges). An agent can distinguish this from directory-listing or symbol-lookup siblings without opening the schema.

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

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

Gives explicit routing: 'Use for `what are the modules` / `which module is X in` instead of reading directory listings.' It also splits behavior by the `symbol` argument (omit to list clusters, provide to get one cluster's members), so the agent knows exactly which mode to pick.

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?

With no annotations present, the description carries the full burden and does disclose useful behavior: results come from a cached tree-sitter parse and return roughly 50 structured records versus thousands of source lines. It does not mention language support limits or what happens on unparseable/binary files, leaving a small 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?

Two sentences, front-loaded with the core purpose before the comparison clause. The size/format payoff ('~50 lines vs thousands') justifies its length and nothing is wasted.

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 and no annotations, but the description compensates by naming the returned fields (kind + line range) and approximate volume, which is enough for an agent to use the result. It stops short of covering supported languages or failure modes.

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 `path`, `file` (deprecated alias), and `project_root`. The description adds no parameter-level detail beyond the schema, which is the baseline 3 case when structured fields do 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 and resource ('List every symbol ... in a single source file') plus the return shape ('kind + line range') and the mechanism ('cached tree-sitter parse'). It explicitly distinguishes itself from the sibling-like Read tool, so an agent can route without opening the schema.

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

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

Gives an explicit when-to-use rule ('Prefer over Read when you only need the file's structure') and contrasts it with the full byte stream alternative. The routing condition is concrete rather than 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?

With no annotations, the description carries the burden and does disclose a meaningful behavioral prerequisite: it requires a v4 index built with call graph, and it notes that paths walks the edges itself in a single response rather than requiring repeated calls. It does not explicitly state read-only safety or describe the return shape, but the prerequisites and execution model are covered.

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 sentences, front-loaded with the core action, then the sibling comparison, then the prerequisite. Every sentence earns its place with 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?

For a read-only traversal tool with no output schema, the description covers purpose, the sibling alternative, and the index prerequisite well. It could briefly state what the response contains (the enumerated chains), but the essential call-time information is present.

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 every one of the 11 parameters is already documented in the schema (including the auto_update/staleness and exclude_tests nuances). The description only restates the max_hops default of 6, adding no semantics 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?

States a specific verb (enumerate) and resource (every caller chain from `from` to `to`) with scope qualifiers (multi-hop, max 6 by default). An agent can immediately distinguish this from siblings like callers, callees, and reachable.

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?

Explicitly names the alternative ('Prefer over repeated `callers` calls') and the condition that selects it (when you need to know how a function gets reached from a known entry point), plus a prerequisite (v4 index with call graph). It stops short of stating when NOT to use it, e.g. relative to reachable or impact.

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?

With no annotations, the description carries the full burden and does well: it discloses metavar semantics, back-reference equality, composition rules, the cached tree-sitter parse with a skeleton prefilter (~10-50ms), and mutual exclusivity of diff-scoping flags. It does not describe the response shape beyond the optional `_meta.why` trace, leaving return-format behavior unspecified.

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

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

Dense but front-loaded: core concept first, then metavars, composition, sibling comparison, and scoping flags. Every sentence carries information, though the metavar/composition sentences are run-on and could be tightened.

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 an 11-parameter tool with no annotations and no output schema, the description covers the operationally critical details: pattern language, performance model, scoping exclusions, and the debug flag. It stops short of describing result structure, but the `why` trace and schema docs fill most of the remaining 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 the baseline is 3, but the description adds real meaning beyond the schema: metavar grammar ($NAME, $_, $$$, $$$NAME), composition operators with AND/OR capture semantics, and the interaction rules for the diff-scoping parameters.

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?

Opens with a specific verb+resource: 'Structural AST pattern matching: match code by shape, not text.' It immediately contrasts with grep and ast-grep, so an agent can distinguish it from the sibling grep tool without opening either 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?

Explicitly names the alternatives and the conditions selecting this tool: 'Prefer over grep / ast-grep for cross-language structural queries — grep cannot match nested syntax, and ast-grep needs per-language scripts.' It also documents mutually exclusive diff-scoping parameters (since / since_branched / changed_only).

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?

With no annotations, the description carries the full burden, and it discloses a real prerequisite: 'Requires a v4 index with call graph', which is not derivable from the schema. It does not, however, cover the workspace-mode shape change, staleness/auto-update semantics, or truncation-by-limit behavior, all of which live only in schema property text.

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 sentences, front-loaded with the definition and scope, then the routing rule, then the prerequisite. No filler and every sentence 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?

For an 11-parameter tool with no output schema and no annotations, the description covers the core semantics and one hard prerequisite. The remaining behavior (workspace result shape, limit truncation, stale-index handling) is fully documented in the schema, so coverage is adequate though not rich.

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 11 parameters (including the workspace shape change and exclude_tests path-only caveat). The description adds only the notion of transitive closure, which is really purpose rather than parameter meaning, 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 and resource ('Every symbol that transitively calls `target`') and immediately frames the scope as the 'full upstream blast radius', which is unambiguous. It explicitly differentiates itself from the sibling `callers` tool, so an agent can select correctly without opening either schema.

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

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

Gives explicit routing guidance: 'Prefer over repeated `callers` walks when assessing the impact of changing a function'. This names the alternative, the scenario that selects it, and the reason (closure in one call). 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?

With no annotations, the description carries the full burden and does well: it discloses return shape (ranked symbol records with kind, signature, line ranges) and performance (~4ms FST, ~7-15ms with semantic). It omits notable side-effect behavior such as the default auto_update bootstrapping/refreshing the index and the workspace-mode result-shape change, which live only in the schema.

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 core capability, then routes to alternatives, then summarizes params. Dense and mostly waste-free, though the trailing 'Supports ...' list leans toward enumeration rather than insight.

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 26-parameter tool with no output schema, the description covers purpose, routing, latency, and return record shape well. Gaps remain around the workspace-mode shape change and auto_update side effects, but the structured schema compensates.

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 schema descriptions are unusually thorough, so the baseline is 3. The description restates filter/kind/context_path/no_bm25/no_stale_check in condensed form, giving a light mental model, but adds little beyond what the schema already documents.

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 ('Hybrid structural + semantic code search across the indexed codebase') and quantifies the mechanism (FST + BM25 + semantic fused into one ranked list). It also distinguishes itself from grep and find_symbol by name, so an agent can route without opening another 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?

Explicitly says to prefer this over grep for symbol/identifier lookup and explains why (grep full-scans and returns line matches vs ranked symbol records). It names the alternatives (grep for regex, find_symbol for exact-only resolution) and the condition that selects each.

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?

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses the ~4ms-per-symbol cost model, the 10-100x token advantage, the truncation modes with their mutual-exclusivity rules, and the deprecated-flag behavior surfaced in the schema. It never explicitly states the operation is read-only and non-mutating, which an agent would still want confirmed.

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 value proposition (extract symbol body, fast, cheaper than Read) before listing the optional knobs. It is dense and mostly waste-free, though the long final sentence stacking several flags reads as a run-on and could be broken up.

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 17-parameter tool with no output schema and no annotations, the description covers usage, cost model, staleness handling, and mode semantics well. It stops short of describing the return shape or what happens when a requested symbol name is not found, which are the remaining gaps an agent would care about.

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 a baseline of 3 is warranted, but the description adds real meaning on top: it groups and explains the Phase 13.3 truncation modes (signature_only, head, no_body, collapsed), notes that collapsed is a v1.9 NO-OP, and characterizes filter, kind, context_path, and no_stale_check in prose the schema only states tersely.

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 concrete verb and resource — 'Extract the full source body of one or more symbols by name (function, class, struct, etc.)' — with a mechanism (cached symbol byte-offsets) that makes the operation unambiguous. It sharply separates itself from Read, but does not differentiate against the other listed siblings such as find_symbol, outline, or search, so it falls short of the top mark.

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

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

Gives an explicit when-to-use rule: 'Prefer over Read when you need a specific definition.' It also explains the batching rationale (a single array call replaces several Read calls). It offers no when-not-to-use conditions or routing toward find_symbol/outline siblings, so it is clear context without exclusions.

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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the lookup mechanism (HNSW), expected latency (~7-15ms), the hard prerequisite (semantic index), and the mutual-exclusivity constraint among since/since_branched/changed_only. It does not describe failure modes when the seed symbol is missing or what staleness handling looks like by default beyond the no_stale_check note.

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

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

Dense but front-loaded: purpose, differentiation, use cases, prerequisite, then constraints. Nearly every clause carries information, though the trailing diff-scoping enumeration partly duplicates the schema descriptions.

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 17-parameter tool with no annotations and no output schema, the description supplies the operationally critical context (mechanism, latency, prerequisite, flag interactions) an agent needs before calling. Output shape is left unaddressed, but no output schema exists to defer to, 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 the baseline is 3; every parameter is already documented, including the deprecation of `name` and the mutual exclusivity of the diff-scoping flags. The description mostly restates those constraints rather than adding syntax or interaction 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+resource ('nearest neighbours of an EXISTING symbol by its stored embedding') and explicitly distinguishes itself from find_similar, which handles free-text queries. The distinction is actionable without opening either 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?

Names the alternative (find_similar), the condition that selects this tool ('when you have a function in hand'), concrete use cases (dedup, refactor planning, parallel implementations), and the enabling prerequisite ('Requires `vex index --semantic`').

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a passive inspection by listing only statistics, but never states it is side-effect-free, does not say what happens when no index exists (error vs empty stats), and mentions no permissions or cost. Adequate but thin for an unannotated 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?

Two tight sentences with zero waste; the statistics list comes first and the usage guidance second. Front-loaded and appropriately sized for the tool's simplicity.

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, enumerating the returned statistics is exactly the right compensation, and it covers the 1-param schema adequately. The only gap is undefined behavior when the index is absent, which an agent would likely want to know for a pre-flight check 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?

Only one parameter (project_root) and schema coverage is 100%, so the schema already documents its meaning and default. The description adds nothing about path resolution or the working-directory default, making this the baseline 3.

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 ('Report index statistics') and enumerates the exact contents (symbol count, byte size, embedding presence, last-update timestamp), so an agent knows precisely what comes back. It does not explicitly contrast itself with the similarly-named 'index'/'update' siblings, but the described payload is distinctive enough.

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 a clear use condition: 'confirm an index exists and is fresh before running search-shaped tools.' This is genuine routing guidance. It stops short of naming alternatives or stating when not to use it (e.g., after running index/update).

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?

With no annotations, the description carries the full burden and does so well: it discloses the v8+ index requirement, the absence of a live-walk fallback, and the failure mode (empty result plus a re-index hint) if the hierarchy section is missing. It does not describe the return shape, but the failure-mode and precondition disclosure is genuinely valuable context beyond structured fields.

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 sentences, front-loaded with the core purpose, then preconditions, then diff scoping. Every clause earns its place with no redundancy or padding.

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 14-parameter tool with no annotations and no output schema, the description covers purpose, the critical index precondition, the failure mode, and diff scoping. It leaves the return format undocumented (no output schema exists), which is the main remaining 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 every parameter is already fully documented in the schema; the baseline is 3. The description reinforces the mutual exclusivity of `since`/`since_branched`/`changed_only` and the transitive nature of `depth`, but adds little that the schema descriptions do not already state.

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

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

States a specific verb and resource ('Find every TRANSITIVE subtype of a base class / interface') and immediately scopes it ('full descendant tree via extends/implements edges'), explicitly distinguishing it from the sibling `implementations` for direct-only queries. An agent can route between the two without opening either 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?

Names the alternative explicitly ('use `implementations` for direct-only') and states the precondition for use (requires a v8+ index with hierarchy edges). It also notes when the diff-scoping params apply. 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?

No annotations are provided, so the description must carry the behavioral load — and it does substantial work: it explains that rows are stamped with a `framework` label for runner selection, that the walk is transitive with a bounded hop count, and that the CLI surface predates the MCP surface. It doesn't cover return format or what stale-index behavior looks like at the result level, but the framework-label disclosure is valuable behavioral context beyond the schema.

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 purpose, then mechanism, then the grep contrast, then a version-history note. The version sentence is somewhat meta and could be trimmed, but it's a single trailing sentence and doesn't obscure the main payload.

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 12 parameters with full schema coverage but no output schema, the description correctly focuses on what the tool returns conceptually (test rows with framework labels) and the transitive mechanism. It leaves return-format details to the agent's expectations, which is acceptable when no output schema exists, though a note on result shape would have strengthened it.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters thoroughly, including the deprecated `symbol` alias, `test_pattern` replace-not-append semantics, and the `async_update`/`_meta.vex.dev/stale` contract. The description adds meaning by explaining WHY the framework label exists (so agents can pick a runner without path parsing), which goes beyond structured data, but it doesn't re-explain the parameters themselves — the schema does that.

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 (find) and resource (test functions that transitively cover a target symbol) with the exact mechanism (backward call-graph walk). Distinguishes itself from the sibling `callers`/`callees` by being test-path-filtered and from `grep` by reason. An agent can immediately tell what it 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?

Explicitly names the alternative (`grep test.*Foo`) and the reason it's wrong (misses transitive helpers, false positives), giving a clear when-to-use-this-not-that rule. This is the strongest kind of routing 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?

With no annotations, the description carries the full burden and does well: it discloses the mtime-based incremental mechanism, relative cost, and implicit invocation by other tools. It does not say what happens when no index exists (error vs fallback to full build) or whether the index file is mutated in place, which are the remaining behavioral gaps for a mutating refresh 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?

Three tight sentences: purpose first, then the routing decision, then the implicit-call caveat. Every sentence earns its place with zero padding.

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 mutating refresh tool with no output schema and fully documented parameters, the description covers mechanism, cost, and sibling routing. The main omission is the failure/fallback path when no prior index exists, which an agent would want before invoking it on an unindexed project.

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 five parameters (gpu, device, semantic, workspace, project_root) in detail. The description adds no parameter-level meaning beyond that, 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 and resource ('Incremental index refresh') plus the exact mechanism (re-parses only files whose mtime changed). It explicitly contrasts itself with the sibling `index`, so an agent can distinguish the two without opening a schema.

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

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

Explicit when-to-use rule: 'Prefer over `index` when an index already exists', backed by a concrete cost comparison (<1s vs full rebuild). It also warns that most sibling tools call this implicitly via auto_update=true, which is exactly the routing context an agent needs.

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