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

With no annotations, the description carries the full burden. It discloses that output follows the 'ce.arch-report schema' and enumerates report contents, and 'Advisory' implies a read-only, non-mutating operation. However it does not state permissions, cost, or whether the operation is purely a read, leaving meaningful behavioral 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?

It is a single dense sentence, but it is front-loaded with the resource ('The architecture of the tree') and cleanly partitioned by a colon and parallel list items. Nearly every clause names a distinct report section, so little 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?

There is no output schema, so the description must convey return content, and it does list the report sections. But for a tool with no annotations it omits usage routing and explicit read-only/permission behavior, leaving it adequate rather than complete.

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

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

Schema description coverage is 100%, so the schema already documents both `path` and `impact`. The description adds only a small amount of meaning by framing `impact` as 'the files a change to `impact` reaches', which clarifies its effect in the report but does not add syntax or format detail. 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 names a specific resource (the tree's architecture) and enumerates the exact report sections it produces: directory layers, cycle arcs, file clusters, per-directory fan-in/fan-out/instability, and impact reachability. This is far more concrete than a tautology. It does not, however, explicitly distinguish itself from plausible siblings like `structure`, `graph_sites`, or `trend`.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternatives are named despite ~20 siblings. The only hint is the trailing word 'Advisory', which implies a non-mutating analysis but does not say when an agent should prefer this over the other analysis tools.

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

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

With no annotations present the description carries the full burden, and it does disclose one meaningful trait: this surface is non-mutating and never writes a baseline. Beyond that it says nothing about permissions, what the 'ratchet' or 'axes' output means, or failure behavior, so the disclosure is 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?

It is a single dense sentence with no padding, and the report-only caveat is placed at the end as a qualifier. It is efficient, though the jargon makes it less immediately readable than it could be.

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

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

With no output schema and no annotations, a report-generating tool of this apparent complexity should explain what it returns and what the score/ratchet/axes concepts mean. The description leaves the agent guessing at the result shape and the semantics of its own domain terms.

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 all three parameters (days, path, floor) are documented in the schema, including absence semantics — so the baseline is 3. The description adds no parameter-level meaning beyond 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?

The description leans on internal jargon ('ADR-006 baseline judgment', 'ratchet and axes') and never states a plain verb+resource an agent can act on. It never distinguishes itself from close siblings such as trend, scan or update_check, several of which plausibly also report baseline-ish status. An agent can't confidently tell what 'check' actually computes from the text alone.

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

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

There is a partial exclusion — 'report only — this surface never writes a baseline' implies when not to reach for a writing surface — but no positive guidance on when to choose this over trend, scan or architecture. No prerequisites or trigger conditions are given.

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, yet it says nothing about side effects, permissions, cost, or read-only nature. The only behavioral hint is the qualifier 'Verified' (implying a filtered/suppressed set) and the T1/T2 scope, which is 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?

It is short, but it is an under-specified noun fragment rather than a front-loaded statement of purpose; there is no leading verb to orient the agent. Brevity here comes from omission, not from efficient structuring.

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 3-parameter tool with no annotations and no output schema, the description leaves out what the tool returns, what 'T1/T2' means in practice, and how the referenced 'ce.dedup-report' schema should be interpreted. An agent cannot confidently invoke this from the description alone.

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% (path, min_tokens, min_distinct all documented), so baseline 3 applies. The description adds no parameter meaning beyond the schema — notably it does not connect 'Verified' to the min_distinct diversity floor or min_tokens threshold.

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 an artifact ('Verified T1/T2 clone blocks') and a schema ('ce.dedup-report'), so the duplication-detection domain is identifiable, but there is no verb and no statement of what the tool actually does (find? report? verify?). Sibling differentiation is absent despite close siblings like 'clone', 'docdup' and 'similar_units'.

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

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

No when-to-use, when-not-to-use, or alternative routing is given. With 'clone', 'docdup', 'similar_units' and 'check' in the sibling list, the agent has no basis for choosing this tool over those. Not misleading, but zero 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 are provided, so the description carries the full behavioral burden. It discloses that analysis runs over a git window and references a report schema, but says nothing about read-only nature, permissions, performance cost, or what the report contains beyond a schema name.

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 compact sentence with the analytical scope front-loaded. The parenthetical schema reference is slightly cryptic but overall the definition is tight 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?

With no annotations, no output schema, and a terse description, the definition is under-specified for a tool that produces an analytical report. An agent cannot tell what the report returns, whether the call is safe or expensive, or how the two analyses interrelate.

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 both parameters ('days', 'path') are already documented in the schema. The description adds no format, default, or boundary detail beyond naming the git window, so the baseline of 3 applies.

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

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

The description names two specific analyses ('append-vs-rewrite', 'co-change') and the domain ('git window'), which is more than a tautology and gives an agent a rough sense of the resource. However, it never frames the resource plainly (a churn report) and does not distinguish itself from likely-related siblings such as 'trend', leaving the purpose only implied.

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

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

There is no when-to-use, when-not-to-use, or alternative guidance. With 22 sibling tools and neighbors like 'trend' and 'scan', the description offers nothing to help an agent choose this tool over 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?

With no annotations, the description carries the full burden. It discloses output-side context (ce.clone-report / ce.clone-units schemas) and that the unit universe is cached, which is useful. It says nothing about whether a judgment is persisted, permissions required, or side effects, leaving significant behavioral 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 short, front-loaded sentence with no filler, which is good. But the density comes at the cost of clarity (unexplained 'T3', bare schema identifiers), so it is terse rather than effectively concise.

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 and no annotations, so the description should explain return semantics and safety profile. It instead references two schema names (ce.clone-report, ce.clone-units) without explaining what a judgment contains or whether anything is written, leaving an agent under-informed for a two-mode tool.

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

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

Schema description coverage is 100%, so both `path` and `units` are already documented in the schema. The description's mention of `units` largely repeats the schema text, adding little semantic value beyond the mode-flip it already states. 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 names a resource and action ('near-miss clone judgment'), so an agent can infer it evaluates clone candidates. However, 'T3' is undefined jargon and there is no differentiation from siblings like check_duplication, similar_units, or merge_suggestions, so the purpose stays vague.

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 explains the `units` mode ('lists the cached unit universe instead') which is a small usage hint, but gives no guidance on when to choose this tool over the many sibling analysis tools (check_duplication, similar_units). Tool-selection guidance is essentially absent.

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 discloses that output is 'advisory ... never a verdict' and references the ce.deadcode-report schema, which usefully frames the result as non-definitive, but it does not state read-only safety, side effects, or analysis scope.

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

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

A single sentence, so it is compact, but the dense jargon and the trailing 'never a verdict' clause make it less front-loaded and less immediately parseable than it could be.

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 annotations and no output schema, the description should carry more weight. It gives a bare conceptual hint about the return (liveness verdicts plus advisory) but leaves the agent without a clear sense of what the report contains or when to prefer this tool over related analysis siblings.

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% and the single path parameter is fully documented in the schema as 'subpath (default: project root).' The description adds no parameter meaning beyond 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?

Describes output as 'liveness verdicts over the reference graph' and 'advisory of declarations no other file spells,' which conveys dead-code analysis. However, it uses noun phrases rather than a clear verb and the parenthetical 'never a verdict' muddies the action, so it falls short of a crisp, sibling-differentiating purpose statement.

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

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

No explicit when-to-use or when-not-to-use guidance. Alternatives like scan, check, or structure are not mentioned, leaving the agent to infer that this is the dead-code option from the name alone.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: not whether this is a read-only analysis, not whether it mutates state, not cost or scope behavior. The only signal is the 'ce.docdup-report schema' hint, which weakly implies the shape of the result but not the operation's side effects.

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 compact sentence with no filler or redundancy. However, its brevity comes from under-specification rather than disciplined editing, which caps it below 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?

For a zero-annotation, no-output-schema tool, the description is too thin: an agent cannot tell whether it analyzes docs, code comments, or markdown, what duplication criteria apply, or how to interpret results. Naming the report schema partially compensates but is not enough.

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

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

Single optional 'path' parameter with 100% schema description coverage ('subpath (default: project root)'), so the schema already does the work. The description adds no meaning about path semantics (relative vs absolute, file vs directory scope), 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 phrase 'documentation-duplication judgment' identifies the resource (documentation duplication) but uses a vague nominalization ('judgment') rather than a clear verb like detect/report/compare. It gives no differentiation from close siblings such as check_duplication, clone, similar_units, or scan. The parenthetical schema name hints that output is a report, but the core purpose remains inferred.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer — significant given check_duplication and similar_units sit adjacent. No prerequisites, no inputs assumed, no workflow context.

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

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

No annotations are provided, so the description carries the full burden. It does disclose one valuable trait — 'The daemon is asked without being started' — implying a non-invasive probe, which is real behavioral information. However, it never states that the tool is read-only, whether the report reflects cached versus live state, or what happens when components are unreachable, leaving significant gaps 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?

The body is a single dense sentence that front-loads the subject ('This machine's state') before enumerating report contents, with no filler. The inline schema-name parenthetical slightly interrupts the flow, and the jargon load is heavy, but 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?

With no output schema, the description must convey what comes back, and enumerating the reported components is a reasonable attempt. But the terms are internal jargon (tier of every guard class, degraded-run counter) that do not tell an agent how to interpret the values, so it is adequate rather than complete for an unannotated diagnostic 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?

One optional parameter with 100% schema description coverage ('subpath (default: project root)'), so the schema already does the work and the baseline is 3. The description adds nothing about the path argument, its scope, or what happens if it points outside the project.

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 verb is implied rather than stated, but the resource is highly specific: a diagnostic report of this machine's state, enumerated as ce-core handshake, guard-class tiers, index freshness, daemon, and degraded-run counter. That enumeration lets an agent distinguish it from siblings like check, update_check, and flow, which are not described but clearly belong to different concerns.

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

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

There is no statement of when to run this versus alternatives such as check, update_check, or scan. The narrow behavioral note about the daemon is a caveat, not usage guidance, so the agent must infer the trigger condition entirely.

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 behavioral burden and does disclose the critical traits: deterministic, dry-run by construction, reaches the plan and nothing else, no mutation side effects. It stops short of noting auth requirements or rate/perf characteristics.

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

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

A single sentence, front-loaded with the key noun phrase 'deterministic erase PLAN'. Every clause (dry-run, reaches nothing else, human applies) earns its place, though the em-dash density is slightly heavy.

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 annotations or output schema exist, so the description must orient the agent, and it succeeds in conveying that the return is a plan that must be applied manually. It could say more about what the plan contains, leaving a small 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% and the single optional 'path' param is documented in the schema, so a baseline of 3 applies. The description adds nothing about the path parameter's meaning or default beyond what the schema already states.

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

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

Names a specific artifact ('the deterministic erase PLAN', 'ce.erase-plan schema') and explicitly scopes it as plan-only versus applying. An agent can tell it does not perform the destructive erasure itself. However, it never names a sibling (e.g. erase_log) to differentiate against, keeping it short of a 5.

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

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

Gives clear context: reach for this to obtain the plan, while applying is a manual step at CLI/GUI. This tells the agent when its output is the deliverable, though it names no alternative tool and offers no explicit 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 a good job: it declares the read-only guarantee, identifies the backing file, the schema of the report, and discloses a partial-failure behavior (unparseable lines are named by number). It omits pagination or output-shape details, but the core behavioral profile is well 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?

Two sentences, front-loaded with the resource identity and followed by the scope/read-only caveats. Dense but no filler; the parenthetical schema name is the only slightly heavy element.

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 single-parameter read tool with no output schema and no annotations, the description is nearly self-sufficient: it explains the source file, the schema name, the record provenance, and the malformed-line handling. An agent could call this correctly without further context.

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

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

There is one parameter with 100% schema coverage, so the schema already documents `path` as a subpath defaulting to the project root. The description adds no further param 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?

The description names a specific resource (the applied-erase audit trail at .ce/erase-log.ndjson) and what it contains (records appended by `ce erase --apply` or the GUI, plus unparseable lines). The read-only framing distinguishes it from the sibling `erase`, which implies the opposite operation. It is clear without explicitly stating the verb 'read'.

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 'Read-only — nothing here can apply or append' line implicitly tells the agent to use this for inspection rather than mutation, and contrasts with the `erase` sibling. However, there is no explicit when-to-use guidance, no statement of when NOT to use it, and no named alternative for inspecting erase history.

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 names the emitted schema (ce.flow-report), states the tool is report-only, and discloses a real semantic trait — each finding is labeled judged or advisory, with unused parameters always advisory. It omits auth/permission requirements and execution cost, which are minor for a read-only analyzer.

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

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

A single dense, semicolon-chained sentence that is front-loaded with the core purpose but heavy with internal jargon ('judged by the core over flow/1', 'ce.flow-report schema') that costs reading effort. Information-dense and mostly earning its place, but readability suffers.

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 steps in by naming the report schema and the fields findings are placed by (path, unit, kind, lines, variable) plus the judged/advisory flag. Together with 100%-covered parameters, an agent has enough to call it correctly, though not enough to know exact output shape.

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 two parameters (kind, path) are already documented and the baseline is 3. The description references placement by 'kind' and 'path' but adds no syntax, accepted values, or default semantics 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: detects dead code inside functions, then enumerates the exact classes (unreachable statements, dead stores, unused locals and parameters). The 'inside functions' scope implicitly separates it from the sibling deadcode tool, though the sibling is never named.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives. 'Report-only' hints that it does not mutate, but the agent is left to infer when to pick flow over deadcode, scan, or structure on its own.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'resolution-free' as a trait but says nothing about read-only behavior, side effects, return format, pagination, or performance characteristics, leaving the agent with little operational 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?

The description is a single short sentence, so it is not verbose. However, the cryptic parenthetical CLI reference does not fully earn its place for an AI agent and leaves the core purpose unclear.

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 and no annotations, so the description should explain what 'reference sites' means and what the tool returns. It fails to do so, offering only an internal shorthand that does not help an external agent invoke the tool correctly.

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

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

Schema description coverage is 100%, with the only parameter ('path') already documented as a subpath defaulting to project root. The description adds no additional parameter meaning, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives only a noun phrase ('Reference sites') and an internal CLI reference ('the ce graph --sites rows'), without a clear verb or output description. It does not distinguish this tool from siblings like similar_units, clone, or structure, leaving the agent to guess what operation is performed.

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

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

There is no guidance on when to use this tool versus alternatives. The phrase 'resolution-free' hints at a condition but does not explain when or why an agent should choose graph_sites over the many other code-analysis siblings.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it largely fails: it does not say whether the tool is read-only, what permissions it needs, how expensive it is, or how the 'ce.join-report schema' output is shaped (and no output schema actually exists). The parenthetical schema reference is the only behavioral hint.

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

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

One short line with no wasted words and the key content front-loaded, which is good; but the brevity is achieved through unexplained jargon rather than precision, so it reads as under-specification rather than effective conciseness.

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 annotations, no output schema, and a completely opaque one-liner, an agent cannot confidently determine what the tool returns or when it should be invoked. For a tool embedded among 20+ analysis siblings, this is insufficient context.

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 both optional parameters ('days' with its default of 14, and 'path' defaulting to project root) are fully documented in the schema. The description adds no parameter meaning beyond that, making the baseline 3 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 ('join') and enumerates three signals (similarity, graph position, churn), which hints at what is combined. However, it never states what resources are being joined or what the result represents, and it offers no differentiation from siblings like 'churn', 'similar_units', or 'graph_sites'; it borders on jargon shorthand.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many siblings (churn, similar_units, check_duplication). The agent is left to guess the scenario that warrants a combined three-signal join rather than one of the single-signal tools.

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

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

No annotations are provided, so the description carries the full burden. 'Advisory' usefully implies the output is non-mutating, and it enumerates what the report contains, but it says nothing about required permissions, cost/runtime, or how feasibility is computed.

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?

It is a single sentence plus a one-word trailer, so there is no padding, and it front-loads the resource. However, the heavy domain jargon (anti-unified, merge/1, ce.merge-report) makes it dense to the point of obscuring the point for a reader without prior context.

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 single-parameter, read-only analysis tool with no output schema, the description compensates reasonably by enumerating the report's fields. It still omits usage context (when this beats clone/check_duplication) and any behavioral constraints, leaving it only minimally sufficient.

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

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

Schema coverage is 100% and the single 'path' parameter is fully documented in the schema as 'subpath (default: project root)'. The description adds nothing about the path parameter, so the schema does all the work — 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 resource (clone-merge suggestions) and details the report contents — clone groups, T1/T2 families, T3 pairs, anti-unification by merge/1, parameters, kept member, lines saved, feasibility. This is far more specific than a restatement, though it never names related siblings like clone, check_duplication, or similar_units to disambiguate.

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?

Only guidance is the trailing word 'Advisory.' There is no explicit when-to-use, no statement of when NOT to use it, and no routing to alternatives such as clone or similar_units, which an agent would plausibly confuse it with.

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. It usefully discloses 'Report-only' (implying no mutation) and that every answer is labelled with its derivation under `why`. However, it omits any account of permissions, rate limits, failure behavior, or what happens to `path`/`file` defaults beyond what the schema already states.

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

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

The purpose is front-loaded, but the single semicolon-and-parenthesis-laden sentence is dense and hard to parse, and it partially restates parameter behavior already in the schema. Structure is functional but overloaded rather than economical.

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 must cover returns; it names the ce.query-report and ce.query-prelude schemas and the labelled-answer format, which is helpful but refers to external schemas an agent cannot see. Combined with missing usage guidance and error behavior, the coverage is adequate but not complete for a 5-parameter tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, making 3 the baseline. The description reinforces the `why` and `prelude` parameters and their semantics (prelude answers the prelude and `[rules.pack]` program instead of a question), adding marginal value but no syntax beyond the schema.

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

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

The description states a specific verb and resource: answering one CE Datalog question over the index's enumerated fact types (files, references, units, clones, mentions, path classes). It is clear what the tool does, but it never distinguishes itself from siblings like rules, deadcode, graph_sites, or structure, which an agent could easily confuse with a generic 'query' tool.

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

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

There is no explicit when-to-use guidance and no alternatives are named, despite many plausible siblings (deadcode, clone, graph_sites, rules). The description explains modes (`prelude` vs a question) and the rules file, but not the context that should select this tool over another.

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 burden. It usefully discloses that this variant does NOT exit/fail on violations (unlike the CLI) and that output includes witnesses and derivations, but it never states permissions, read-only nature, or whether the rules file is modified.

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

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

Two compact sentences with no filler, and the behavioral contrast with the CLI is front-loaded. It is dense with internal terminology, which slightly reduces readability, but 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?

There is no output schema, and the description compensates by describing the report's contents (asserts, violations, witnesses, derivations). For a low-complexity, all-optional-parameter read tool this is largely sufficient, with only usage/alternative guidance 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 the schema already documents why, file, and path, making 3 the baseline. The description touches the rules-file concept and the derivation output that corresponds to the `why` flag, but adds no format or syntax detail beyond the schema.

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

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

The description states a specific resource (the project's architecture rules) and what it returns (every assert with its violations, witness, and derivation), which lets an agent infer this is a static-analysis/report tool. It is understandable but phrased in dense internal jargon ("judged", "ce.rules-report schema") and never names or contrasts any sibling like check, architecture, or doctor.

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 only usage hint is the CLI contrast ("The CLI exits on counts.violations; here it is a report"), implying this is the non-failing reporting variant. It gives no explicit when-to-use, when-not-to-use, or alternative tool to prefer, leaving the agent to infer placement relative to the many sibling analysis tools.

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

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

With no annotations, the description carries the full behavioral burden and delivers almost none: it does not say whether the operation is read-only, what scope it scans, how costly it is on a large project, or how results are returned. The only hint is a dangling schema name (ce.scan-report) that the agent cannot resolve.

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

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

One front-loaded sentence with no filler or repetition. It is efficient, though the terseness edges toward under-specification rather than tight structure.

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

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

For a tool with no annotations and no output schema, the description should explain scope, read-only nature, and roughly what the report contains; instead it points at an external schema name the agent cannot inspect. The reference is a dangling pointer, leaving key behavior undocumented.

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 single path parameter (default: project root) is already documented in the schema. The description adds no meaning beyond that, which matches the baseline 3 when the schema does the work.

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

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

The description names the resource it produces (a size/complexity/readability metrics report) but supplies no verb, so it is unclear whether the tool scans, computes, or merely retrieves. It also does nothing to separate itself from adjacent siblings such as structure, churn, or check, leaving the agent to guess which reporting tool applies.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer for adjacent analysis tasks. The agent receives no routing guidance whatsoever.

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 does add one valuable behavioral fact: the output is advisory and 'never a verdict', plus that `widen` layers on a 'PPMI associative view'. It also sketches the return shape ('role bit and a six-channel evidence row'). However, it discloses nothing about permissions, performance, or read-only nature.

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?

It is compact at two sentences and front-loads the purpose, which is good. But the density of unexplained jargon ('ce.similar-report schema', 'role bit') means the brevity comes at the cost of comprehensibility rather than earning every word's 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 five-parameter, zero-required, no-output-schema, no-annotation tool, the description should clarify how the mutually exclusive target inputs (at/unit/text) are used and what the 'six-channel evidence row' contains. It gestures at the output format but leaves an agent uncertain how to actually invoke 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%, so the schema already documents all five parameters, giving a baseline of 3. The description adds marginal value by clarifying that the target can be 'one unit or a text' (implying at/unit/text) and by explaining that `widen` adds an associative view, but it leaves `at`, `path`, and the mutual exclusivity of the target parameters unexplained.

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

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

The phrase 'the units most like one unit or a text' does communicate a similarity-lookup action, so the core purpose is inferable. But it is buried in domain jargon ('same-role advisor', 'six-channel evidence row', 'the core's order') that obscures what the tool actually returns. It never explicitly distinguishes itself from close siblings like clone, docdup, or check_duplication.

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 only usage signal is 'Advisory — never a verdict', which hints at how to treat the output but not when to call the tool. There is no guidance on choosing this over clone/docdup/check_duplication, and no stated prerequisites or context for when similarity lookup is appropriate.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about whether this is a read-only analysis, whether it mutates anything, cost/latency of a tree-scale run, or what the eight axes evaluate. Only the referenced schema name hints at output shape.

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

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

A single compact sentence with no filler and the schema reference up front. However it is under-specified rather than genuinely concise, and the jargon 'tree-scale structure judgment' costs clarity for the space it saves.

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, no annotations, four optional parameters, and an analysis tool whose axes are named only obliquely ('eight axes', 'ce.structure-report schema'). An agent cannot tell what the report contains or what each axis flags, so the definition is incomplete for the tool's complexity.

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 four parameters (days, deep, path, split) are already documented in the schema, including which axis each toggles. The description adds no syntax, defaults, or interaction details 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?

The description names a resource (structure) and a scope (tree-scale, eight axes) plus a report schema, so it is more than a tautology. But the operative verb is fuzzy ('judgment'), and nothing distinguishes it from siblings like architecture or scan that also analyze project structure.

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

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

There is no when-to-use guidance at all: no prerequisites, no conditions, and no pointer to an alternative sibling such as architecture or scan. The agent must infer invocation context entirely from the name.

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

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose caching behavior ('points cache in the index, rebuildable from history'), which tells the agent a write side effect exists but is recoverable. It omits permissions, cost/rate concerns, and what the scoring actually measures.

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 an efficient parenthetical. No redundant filler, though the parenthetical packs two distinct ideas (output schema reference and cache behavior) which slightly compresses readability.

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

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

With no output schema and no annotations, the description references an external 'ce.trend-report schema' but never explains the return shape. It is minimally sufficient for an all-optional 3-param tool, but leaves output interpretation and usage context to the agent.

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, batch, and commits. The description adds no syntax, format, or intent detail beyond the schema, 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 and resource ('Score trajectory over mainline git history'), which is enough to distinguish it from most siblings like churn or scan. However it does not explicitly differentiate itself from the closest sibling (churn), leaving the agent to infer the boundary from the term 'trajectory' alone.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The description never mentions churn or any other sibling, so the agent has no routing signal despite 'trajectory' being ambiguous next to 'churn'.

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 behavioral burden and does well: it discloses network access ('reads the release index over the network'), explicitly states it mutates nothing ('places nothing'), and draws the boundary that applying updates is a human action. It omits auth requirements, rate limiting, and caching behavior, which keeps it short of a 5.

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

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

Two tightly packed sentences: the first front-loads what the tool returns, the second front-loads the behavioral constraint. No filler. The parenthetical schema reference and em-dash clause make it denser than ideal, but every clause carries information.

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

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

There is no output schema, so the description must describe the return payload, and it does (latest tag, SHA256 pins, action for this install). With no annotations it also covers the safety profile. What remains uncovered is auth/network failure behavior and how the path parameter scopes the check.

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?

One optional parameter at 100% schema coverage, so the baseline is 3. The schema already documents 'subpath (default: project root)' via its own description, and the tool description adds nothing about how path alters the scope of the update check, which is a genuinely ambiguous point here.

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 check (does a newer CodeEraser release exist) and enumerates what comes back: the latest tag, its SHA256 pins, and one recommended action. That is concrete and specific. It does not, however, distinguish itself from siblings like doctor, check, or scan, which an agent scanning the tool list might reasonably confuse with it.

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

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

Usage is only implied: the name and the phrase 'the one action for this install' suggest this is the update-status probe. It never states when to prefer it over doctor/check/scan, nor any prerequisite or trigger condition. The note that applying is a human act at the CLI or GUI is useful context but is not a when-to-use rule.

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