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

With only destructiveHint=true in annotations, the description carries real weight: atomicity ('all land or none do'), pre-write anchor validation, automatic formatting of touched files, and one validation at the end rather than per edit. These are concrete behavioral traits an agent cannot infer from annotations or 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 tight sentences, front-loaded with the atomic guarantee, then ops, then mechanics, then the routing advice. No filler or restatement of the title/name.

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

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

For a multi-op mutation tool with no output schema, the description covers atomicity, validation timing, formatting, and failure behavior, which is everything an agent needs to decide 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that 'check' runs a single validation after all edits (schema only lists the validation kinds) and that anchors are validated up front. Op names and edit ordering are reinforced but largely duplicate 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 and resource (apply several edits as one atomic unit) and enumerates the supported operations (replace_text, replace_range, replace_symbol, delete_symbol, insert). This clearly separates it from single-op siblings like arno.replace_text and arno.insert.

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 routes the agent: 'Prefer this over several single edits when changing more than one site,' naming the alternative and the selecting condition. The check options (build, typecheck, tests, impact) further guide correct invocation.

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

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

Annotations only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses synchronous-by-default behavior, direct pass/fail return, that every result names the executed command, and that dryRun names without running. It omits side effects of running a build (artifact writes) and how to poll the job ID returned when wait=false, but the core behavior 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?

Front-loaded with the purpose and the wait semantics, then defaults and edge cases; every sentence contributes. It is slightly dense with several clauses per sentence but no filler.

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

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

With no output schema, six optional parameters, and only a destructiveHint annotation, the description supplies the essentials: default kind, wait/dryRun behavior, timeout context, and the multi-project fallback. It stops short of describing error surfaces or the polling path for wait=false, which are the remaining gaps.

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 meaningfully supplements it: it explains the default kind, the multi-project meaning of target, and that dryRun names the command without executing. It adds interpretation rather than restating field types.

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+resource ('Run a validation command on demand and wait for the verdict') and enumerates the kinds (build/typecheck/tests), so the agent knows exactly what is executed. It is clear without opening the schema, though it never distinguishes itself from the sibling arno.run_tests, which overlaps on the 'tests' kind.

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 implied through the defaults and the multi-project note ('pass target to check one; with no command at the root, the answer lists the projects'), which gives real context. However, there is no explicit when-to-use versus siblings like arno.run_command, arno.run_tests or arno.declare_command, leaving the agent to infer the boundary.

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

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

Annotations only provide destructiveHint=false, so the description must carry the behavior burden and does: it discloses implicit parent-directory creation and the fail-on-existing-file semantics, which are non-obvious. It doesn't cover permissions, error surface, or return value, so it falls 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 tight sentences with zero filler; the core create-plus-parent-dirs behavior is front-loaded and the exclusion/alternative follows immediately.

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

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

For a simple creation tool with full schema coverage and no output schema, the description covers the key behavioral surprises (mkdir -p, no overwrite) so an agent can call it correctly. Minor gaps remain around permissions and failure responses, keeping it just under 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% with three self-documented parameters (path, root, content), so the baseline is 3. The description adds no format, path-resolution, or root-precedence detail beyond what the schema already says.

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 ('Create a brand-new file') and adds scope ('any missing parent directories'). It also names the siblings appropriate for the adjacent case (replace_text, apply), letting an agent distinguish creation from modification without reading 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?

Explicitly states the when-not condition ('Refuses to overwrite an existing one') and routes to the named alternatives ('use replace_text or apply to modify existing content'). No inference required to pick the right tool.

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

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

Annotations only supply destructiveHint=true; the description adds real behavioral context beyond that: persistence across sessions, that the manifest file is 'reviewed like any change', and the replace-on-duplicate semantics for an existing name. It stays silent on the deletion path (the remove param), which the annotation's destructive hint implies but the prose never explains.

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

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

Two dense sentences with zero filler; the core function and its target file are front-loaded before the caution about redeclaring, which is exactly the ordering an agent needs.

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

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

With no output schema, the description carries the return/behavior burden and does reasonably: persistence, review gating, and replacement are covered, and the schema fully documents parameters. The one gap is the removal/destructive path, which the destructiveHint annotation hints at but the prose never spells 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 (run, kind, name, root, remove, description) is already documented in the schema; baseline is 3. The description adds only the replace-on-existing-name behavior for `name`, which is modest value over 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?

Names a specific verb and resource ('Declare a named command in .arno/commands.json') and explicitly scopes the purpose ('to run with run_command in this and later sessions'). It also distinguishes the tool from the sibling run_command, telling the agent this is for declaration, not execution.

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 (declare so it can be run in this and later sessions), when-not ('do not redeclare one just to run it'), and names the alternative tool (run_command) for execution. 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?

Annotations already carry destructiveHint=true, so the safety profile is known; the description goes beyond that by disclosing the error behavior ('fails if it does not exist') and, valuably, that the deletion is recoverable via checkpoint revert. That reversibility detail is exactly the kind of trait annotations cannot express. It does not mention permissions or confirmation behavior.

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 clauses, front-loaded with the core action and its key constraint, and every clause carries distinct information (scope, failure mode, reversibility, alternative). 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 two-parameter mutation with no output schema, it covers failure behavior, reversibility, and the alternative editing path, which is nearly everything an agent needs. Only the return/confirmation shape and any permission requirements are unstated, 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 description coverage is 100%, with both 'path' and 'root' documented in the schema itself, so the baseline is 3. The description adds no syntax, format, or defaulting nuance 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?

The description states a specific verb (delete) and resource (file), and immediately scopes it negatively with 'not a directory', which rules out the most likely confusion. It also names the sibling tools (replace_text, apply) that handle the adjacent editing case, so an agent can distinguish it 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?

It gives an explicit exclusion and an explicit alternative: to edit content, use replace_text or apply. What's missing is any positive context on when deletion is appropriate or prerequisites, but for a self-evident destructive verb this is close to complete 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds genuine behavior beyond that: exact name matches outrank substring matches (a result-ordering rule that affects interpretation), and the call fuses search with body retrieval. Pagination via continue is left to the schema, so this is not fully self-contained.

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 value proposition before the routing advice and the batch hint. The shell-command analogy earns its place by compressing a lot of behavior into a few words. No padding, though the sentence count is near the upper bound for a description this dense.

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 nine-parameter read tool with no output schema, the description covers purpose, sibling routing, ranking behavior, and batch querying. The remaining gaps — result envelope shape and how continue/budget interact — are handled by the schema's own parameter descriptions, so an agent has enough to 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 coverage is 100%, so a 3 is the baseline and the schema already documents all nine parameters thoroughly. The description still adds semantics the schema does not: that `queries` is a batch alternative to `query` and that match ranking favors exact names, which shapes how an agent should phrase query input.

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

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

States a specific verb ("Locate declarations by name") plus a second action ("return their source in one call"), which makes the fused search-and-read behavior clear. The grep -n 'func X' -A 30 analogy immediately distinguishes it from a plain search tool. An agent can tell it apart from grep and read_range 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?

Explicitly names the alternatives ("Use this instead of outline and read_range") and the selecting condition ("when you have not located the symbol yet"). It also directs batch use via "Pass queries to find several names in one call." Nothing about when-to-use 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description still adds real behavioral context beyond that: result truncation is cut at whole matches with the remainder behind continue=<handle>, the true total is always reported, and dependency search is read-only at the locked version. It stops short of describing match ordering or deduplication, so not 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 sentences, front-loaded with what the tool does, then the distinction from `find`, then the multi-pattern tip. No filler; every clause carries routing or behavioral information.

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

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

For a 12-parameter, no-output-schema tool with only a readOnly annotation, the description supplies return format, context lines, truncation/pagination, dependency scoping, and sibling routing. The only real gap is that it does not touch the glob/exclude/root/ignoreCase filters, but the schema documents those at 100% coverage.

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 would be 3. The description nevertheless adds cross-parameter meaning the schema lacks: that `queries` exists to search several patterns in one call and each is answered 'as query would be, with the same filters', and that `continue` ignores arguments except budget.

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 verb+resource ('literal or regex text search across the workspace') and states the return shape ('path:line matches with optional trailing context'). It explicitly positions itself as the replacement for `grep -rn` and contrasts with the `find` sibling, so an agent can distinguish it 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?

Gives explicit when-to-use ('anything that is not a declaration name: struct fields, string literals, error messages, config keys, or any search needing a path filter') and a clear alternative with its own condition ('use find instead when you want a declaration and its body'). The routing rule against siblings is unambiguous.

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

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

Annotations only declare destructiveHint=false, so the description carries the real burden and delivers: it explains append-vs-anchor placement, and discloses two concrete refusal conditions (anchor absent, anchor matches more than once). This is failure-mode disclosure an agent cannot infer from 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?

Four tight sentences, front-loaded with purpose and the sibling routing, then behavior, then the escalation path. No sentence is redundant.

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 insertion tool with no output schema, the definition covers purpose, alternatives, placement semantics, and refusal conditions — everything needed to invoke it correctly and safely.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds inter-parameter semantics the schema states only per-field: that omitting anchor implies append and that position refines placement relative to anchor. It does not, however, explain expectedDigest/expectedRevision beyond what the schema already says.

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 ('Add text to a file'), then immediately contrasts it with the rewrite behavior of a sibling ('instead of rewriting a surrounding symbol'). An agent can distinguish this from arno.replace_text and arno.apply 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?

Explicitly names when to use it (additive work) and names the alternative for a different case ('Several additions or edits at once belong in apply'). Both the routing condition and the exclusion 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real behavior beyond that — out-of-range end lines clamp to EOF, dependency sources read as dep:<name>/<path> read-only, and a failing range in a batch reports its own error without failing the others. It doesn't explain truncation/continue behavior in prose beyond what the schema says.

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

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

Front-loaded with the core action and its analogy before the edge cases. Information-dense with no filler, though the multi-range JSON example makes it longer than strictly necessary given the schema already documents the array.

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 carries return-behavior weight and does so reasonably — it covers clamping, per-range error isolation, dependency-path reads, and (via schema) budget/continue. Minor gap: no explicit statement of the response shape for a normal read.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning above the schema: it clarifies that omitting both line numbers reads the whole file and supplies a concrete multi-range example ('ranges' array shape) plus the dep:<name>/<path> path convention.

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

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

States a specific verb+resource ('Read a file verbatim, whole or by line range') and anchors it against familiar tools ('the replacement for `cat` and `sed -n`'), which cleanly separates it from file-mutating siblings like insert/replace_text and search siblings like find/grep.

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 conditions: omit both line numbers for whole-file reads, which is the route for go.mod, Makefile, or symbol-less config formats — implicitly pointing symbol-addressing work at other tools. It stops short of explicitly naming a sibling (e.g., find/grep) for symbol-based lookup, so it's strong but not fully routing.

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

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

Annotations declare destructiveHint=true, so the safety bar is lower, but the description adds the key behavioral guarantee: refusal on absent or ambiguous anchors, and how to fix it. Omits expectedDigest/expectedRevision semantics, which are confined to 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 tight sentences, front-loaded with the action and rationale, then refusal conditions, then a sibling routing note. No waste; minor density in the final sentence.

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

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

For a mutation tool without an output schema, the description covers purpose, failure modes, disambiguation, and multi-site routing. Missing digest/revision behavior context, but the schema covers those parameters.

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%, documenting all six parameters including optional expectedDigest and expectedRevision. The description doesn't add parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Replace an exact, unique string in a file') and explains the anchor-based motivation. Clearly distinguishable from siblings like arno.insert and arno.create_file.

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 specific routing rule: 'For several sites, use apply: atomic, one validation.' Also explains refusal conditions and how to disambiguate. Lacks explicit when-not-to-use beyond multi-site edits.

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?

Adds real behavioral value by disclosing the return shape (pass/fail plus decisive output) in the absence of an output schema. However, annotations flag destructiveHint=true and the description says nothing about commands mutating the worktree, side effects, or that omitting 'wait' yields a pollable job. Some value added, but the destructive profile is left entirely to the annotation.

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 tight sentences with no filler, and the core purpose plus the 'no name lists commands' behavior are front-loaded. The telegraphic fragments ('Nothing fits? declare_command it once.') are efficient but slightly cryptic in tone.

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?

Covers purpose, routing, listing, and escalation, and the schema handles root/wait/timeout defaults. With no output schema, the description supplies the return contract. What is missing is any hint about destructive side effects, which matters given destructiveHint=true.

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 is already documented (name omission, root default, wait polling, timeout bounds). The description restates only the name-omission behavior, adding no syntax or format detail beyond the schema. 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 a repository-declared command by name — plus the outcome contract (pass/fail with decisive output). It explicitly contrasts itself with 'check' and with a raw shell, so an agent can place it among the siblings 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?

Gives direct routing rules: use instead of a shell for anything 'check' does not cover, omit the name to list declarations, and escalate to 'declare_command' when no declared command fits. When-to-use and the alternative (declare_command) are both 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?

Annotations provide only destructiveHint=false, so the description carries most of the behavioral burden. It discloses that the call blocks for pass/fail and surfaces the first failure, which is useful return information with no output schema to lean on, but it says nothing about side effects of running tests or behavior when wait=false beyond what the wait parameter already documents.

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 clauses with the primary action front-loaded and the alternative at the end; there is essentially no filler. The compressed phrasing of 'check kind tests' is slightly terse but does not waste space.

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 parameterized test runner with full schema coverage but no output schema or rich annotations, the description covers the main scopes, notes the waiting behavior, and points to the sibling for full suites. It is largely sufficient, missing only edge behavior for wait=false and side effects, which keeps it short of a 5.

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 six parameters are fully documented in the schema itself. The description only restates scoping at a high level and adds no syntax or format detail beyond what the schema already provides; 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 states a specific verb and resource ('Rerun ... tests') and enumerates the scope variants it covers (a failing test, a test file, changed files' tests), which lets an agent distinguish it from generic siblings like run_command. It explicitly routes the full-suite case to another tool ('check kind tests'), though the default scope=all in the schema creates mild tension with that routing.

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

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

It gives clear conditions for use (rerunning a failing test, a file, or changed files) and names an alternative for the excluded case (full suite -> check kind tests). It stops short of explicit when-not guidance beyond that one case, so it is strong but not exhaustive.

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