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

With only destructiveHint=true available, the description carries real weight: it discloses atomic all-or-nothing semantics, that anchors are validated before any write occurs, that touched files are auto-formatted, and that validation is batched once at the end. These are behavior facts the annotation does not convey.

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

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

Three sentences, front-loaded with the atomicity guarantee, then ops, then execution traits, then the routing hint. No filler and nothing repeated from the schema.

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

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

For a mutation tool with no output schema, the description covers the essentials an agent needs: atomicity/failure semantics, pre-write anchor validation, post-write formatting, batched validation, and when to prefer it. No significant gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3; the description nevertheless adds meaning by explaining that validation runs once after all edits (vs. per edit) and that formatting applies to touched files, which clarifies how the check/format parameters behave at execution time.

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 (apply edits) plus the defining property (one atomic unit: 'all land or none do') and enumerates the supported ops. This is immediately distinguishable from single-edit siblings such as arno.replace_text, arno.insert, and arno.delete_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?

Explicitly routes the agent: 'Prefer this over several single edits when changing more than one site,' which names both the alternative approach and the condition that selects this tool. It also describes the validation model (one check at the end rather than per edit), giving the agent a reason to consolidate.

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 only destructiveHint=false in annotations, the description carries the behavioral load and does it well: it waits by default and returns pass/fail, always names the command that ran, dryRun names without running, and a root without a command returns a project list. It does not cover timeout/failure behavior in depth, but the core execution semantics are 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 action and defaults, then the fallback behaviors. Dense and mostly waste-free, though several clauses duplicate what the schema already documents, which slightly dilutes it.

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 must explain returns, and it does: pass/fail verdict, the command name in every result, and a job ID when wait=false. Combined with the multi-project fallback, 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 description coverage is 100%, so the baseline is 3. The description mostly restates schema content (wait default, dryRun meaning, kind default); its one genuinely additive point is the multi-project/target behavior and the fallback listing when no root command exists.

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 ('Run a validation command') and enumerates the validation kinds it supports (build/typecheck/tests). It is clearly a validation runner, but it never names how it differs from close siblings like arno.run_command, arno.run_tests or arno.declare_command, leaving the agent to infer the boundary.

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 for use: waits by default, pass target to check one project in a multi-project repo, and dryRun to preview. There are no explicit exclusions or named alternatives, but the conditions under which each mode applies are spelled out.

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

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

Annotations only declare destructiveHint=false; the description supplies the genuinely non-obvious behaviors — implicit parent-directory creation and a hard refusal on existing paths. It stops short of describing the failure mode (error vs. silent no-op) or encoding/permission requirements, which keeps it below 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 create semantics are front-loaded and the exclusion/alternative routing follows immediately. Every clause earns its place.

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

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

For a simple create tool with no output schema, the description covers the essential behaviors an agent needs: parent creation, overwrite refusal, and alternatives. It omits the return value and error surface, which are minor gaps given the tool's simplicity.

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

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

Schema description coverage is 100%, so path, root, and content are already documented by the schema. The description adds no format, encoding, or path-resolution detail beyond what the schema provides, 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?

States a specific verb and resource ('Create a brand-new file') plus a notable scope behavior ('and any missing parent directories'), so the agent knows this is a create-with-parents operation, not a plain write. It explicitly names the siblings that handle the mutation case (replace_text, apply), making it distinguishable from them without opening either schema.

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

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

Provides an explicit when-not condition ('Refuses to overwrite an existing one') and names the two alternative tools for modifying existing content. The routing rule for create vs. modify is fully spelled out with no inference required.

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 only destructiveHint=true supplied, the description carries the rest and does so well: it discloses persistence across sessions, that the target file is 'reviewed like any change' (i.e., a tracked, reviewable mutation), and that an existing name is overwritten rather than duplicated. It does not contradict the destructive hint. Remaining gaps are minor — no word on failure modes if the name is invalid or the workspace is unset.

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 action and artifact, followed by the operational rules. Every clause carries distinct information (persistence, review, overwrite, non-redeclaration) with no filler.

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

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

For a six-parameter declaration tool with full schema coverage, no output schema, and a destructiveHint annotation, the description supplies the missing pieces an agent needs: persistence scope, overwrite semantics, and the routing rule to run_command. Nothing essential is absent.

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

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

Schema description coverage is 100%, so all six parameters (including run, kind, root, and the remove toggle) are already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Declare) and resource (a named command in .arno/commands.json), and gives concrete examples of what such commands are (a reproduction, a benchmark). It explicitly separates itself from the sibling run_command by framing declaration as the setup step that run_command later consumes.

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

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

Names the alternative and the condition: commands are 'to run with run_command', and it states an explicit when-not — 'do not redeclare one just to run it.' The replacement rule for existing names is also given, so the agent knows redeclaration is only warranted when changing the definition.

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 only destructiveHint=true; the description adds genuinely new behavior: the tool errors when the path is absent, and deletion is recoverable because reverting to an earlier checkpoint recreates the file. That recoverability note is the single most decision-relevant fact for an agent about to destroy state, and it is not available anywhere else.

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 main constraint, then failure behavior, then the alternative-tool routing. No filler and nothing repeated from the schema or annotations.

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 destructive tool with no output schema, the description covers the essentials: what is deleted, what is not (directories), failure mode, recoverability, and where to go for the adjacent edit operation. Nothing an agent needs to invoke it correctly appears to be 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% for both parameters (path, root), so the schema already carries the semantics. The description contributes only the indirect file-vs-directory constraint on 'path' and says nothing about the 'root'/worktree parameter, 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+resource ('Delete a file') and immediately narrows the scope with 'not a directory', which an agent needs in order to avoid misusing it. It also names the sibling tools (replace_text, apply) that serve the adjacent editing intent, so it is distinguishable from them without opening any schema.

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

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

Gives clear conditions: only files (not directories), and it fails if the target does not exist. It routes editing intent to replace_text or apply. What it does not state is any prerequisite for deletion (e.g. permissions, whether the file must be closed/unmodified) or an alternative for removing directories.

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 genuinely useful behavioral context beyond that: exact name matches are prioritized over substring matches, and source bodies come back in the same call. It does not elaborate pagination/cutting, though the schema carries budget/continue.

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 fused search-and-read purpose. Every sentence carries distinct information (purpose, ranking rule, routing guidance, batch option) with no filler.

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

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

For a read-only search tool with fully documented parameters and no output schema, the description explains what is returned (declarations with source) and the ranking behavior. Only minor gaps around response shape/pagination remain, which the schema partly covers via budget and continue.

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 nine parameters including query, queries, budget, and continue. The description echoes a couple of these (queries for batch lookup, exact-over-substring matching) but adds little syntax or format detail. Baseline 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?

States a specific verb (locate) and resource (declarations) plus the distinctive behavior of returning source in one call. It explicitly differentiates itself from grep, outline, and read_range, so an agent can select it without reading any schema.

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

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

Gives an explicit when-to-use rule ('when you have not located the symbol yet') and names the alternatives it supersedes (outline and read_range). The routing condition between this and sibling search/read tools 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?

readOnlyHint=true already covers safety, but the description adds the return format (path:line matches with context), which matters since there is no output schema. It does not, however, expand on pagination/cut behavior, which the schema carries.

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

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

Three tight sentences, purpose front-loaded, with usage and alternative routing following. No wasted filler and the most decision-relevant information (what it is, what it isn't) comes first.

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 read tool with a fully-specified schema, one annotation, and no output schema, the description covers purpose, return shape, and sibling routing well. It leaves pagination/cut semantics to the schema, which is reasonable, so it is nearly but not entirely self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters in detail. The description only lightly reinforces the queries parameter ('pass queries to search several patterns in one call') and adds no syntax beyond what the schema provides. 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 (search) and resource (literal or regex text across the workspace), plus the returned shape (path:line matches with optional trailing context) and the grep -rn analogy. It explicitly distinguishes itself from the find sibling for declaration searches.

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 with concrete examples (struct fields, string literals, error messages, config keys), a when-not-to-use rule ('use find instead when you want a declaration and its body'), and a tip to batch patterns via queries. Both the condition and the alternative are 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 only supply destructiveHint=false, so the description carries most of the burden and does well: it discloses the append-by-default behavior, the anchor-placement rule, and the refusal conditions (anchor absent or matching more than once). It does not state whether the target file must already exist or how failures surface, which is the remaining gap.

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

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

Four tight sentences, front-loaded with the core behavior, then placement rules, then the routing note. Every sentence carries distinct information with no padding.

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

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

For a mutation tool with no output schema and minimal annotations, it covers when to use it, default placement, failure modes, and the multi-edit alternative. It stops short of stating whether the file must pre-exist or how the worktree/root resolution affects writes, which an agent would want.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real meaning beyond the schema by explaining that an omitted anchor appends to end-of-file and that a non-unique anchor causes refusal — semantics the anchor/position schema entries do not spell out.

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') with the key scope qualifier 'without replacing anything', then illustrates with concrete cases. It explicitly distinguishes itself from the surrounding-symbol rewrite use case covered by arno.replace_text.

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 ('additive work instead of rewriting a surrounding symbol') and when-to-use-something-else ('Several additions or edits at once belong in apply'). The alternative sibling is named by name, leaving nothing 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?

readOnlyHint=true already establishes the safety profile, but the description adds real behavior beyond it: an end line past EOF reads to the end, dependency sources appear as dep:<name>/<path> read-only, and a failing range does not abort the others. It does not mention output format, which is acceptable given no output 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?

Dense but front-loaded: the core verb/resource leads, followed by the whole-file rule, the EOF edge case, and finally the batching example. The inline JSON example is long but does genuine work by demonstrating the multi-range shape.

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 6-param read-only tool with no output schema, the description covers the operation, the two read modes, multi-range batching, error isolation, and the budget/continue mechanism. Nothing an agent needs to call it correctly appears missing, though the `root` semantics are left entirely to the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description still earns credit by explaining range edge-case semantics ('an end line past the end of the file reads to the end') and by showing a concrete multi-range payload that clarifies how `ranges` and `lines` interact.

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

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

The opening states a specific verb and resource with scope: 'Read a file verbatim, whole or by line range,' and frames it via the familiar 'replacement for cat and sed -n'. It never names a sibling (e.g. arno.grep or arno.find) to draw the boundary, so differentiation is implied rather than explicit.

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 for the whole-file mode ('how to read go.mod, a Makefile, or any JSON/YAML/TOML config that has no symbols to address') and demonstrates batched ranges. It stops short of an explicit when-not/use-instead rule against the symbol-oriented 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?

With destructiveHint=true already declared, the description adds genuinely non-obvious behavior: the tool refuses when the anchor is absent or matches more than once, and apply performs one atomic validation with no half-done intermediate states. It does not mention the concurrency guards, though those are documented on expectedDigest/expectedRevision in the schema. Solid added context, minor gap.

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

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

Three sentences, front-loaded with purpose, then rationale, then failure mode, then alternative. Every sentence contributes. The trailing "apply: atomic, one validation, no diagnostics from half-done intermediate states" is slightly compressed/ambiguous in phrasing but still compact for the information delivered.

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 6-parameter mutation tool with no output schema, the description covers the key risks: uniqueness of the anchor, refusal conditions, disambiguation strategy, and the multi-site alternative. Concurrency/expected-state handling is left to the schema, which is acceptable given 100% coverage, but the description never signals that staleness causes refusal.

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 already documented, including the exact-once requirement for oldText and the digest/revision guards. The description reinforces the anchor concept but introduces no syntax, format, or constraint beyond what the schema states. Baseline 3 applies when the schema carries the parameter burden.

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") with the uniqueness constraint baked in. It explains the anchor model (text doesn't move when lines shift) and thereby distinguishes itself from line-number based siblings like insert. An agent can tell it apart from arno.insert and arno.apply 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?

Names an alternative explicitly and the condition that selects it: "For several sites, use apply: atomic". It also gives a concrete recovery path when the tool refuses ("extend it with surrounding context to disambiguate"). Both the routed-away case and the disambiguation case are covered.

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 destructiveHint=true, so the safety profile is carried by structured data. The description adds the pass/fail verdict framing and the wait-for-result behavior, but never elaborates that executing a repo-declared command can mutate state or what auth/working-tree requirements apply, which is what the destructive hint warrants.

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 and compact, and each sentence carries a distinct instruction. The telegraphic fragments ('Nothing fits? declare_command it once') verge on cryptic, costing some clarity for brevity.

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-capable command runner with no output schema, the description conveys the result shape (pass/fail plus decisive output) and the listing fallback. The destructive/mutating nature implied by annotations is not spelled out, 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%, so all four parameters are already documented (name, root, wait, timeoutSeconds). The description only reinforces 'no name lists the declared commands', which the schema already states; it adds no syntax or format detail beyond the schema.

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

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

States a specific verb (run) and resource (a declared repository command) with the outcome (pass/fail verdict plus decisive output). It actively distinguishes itself from siblings by naming 'check' and 'declare_command', so an agent can route correctly without opening a sibling schema.

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

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

Explicit routing: use this instead of a shell for what 'check' does not cover, omit 'name' to list declared commands, and fall back to 'declare_command' when nothing fits. When-to-use, when-to-list, and the alternative path are all 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 only declare destructiveHint=false, so the description must carry behavioral weight. It usefully discloses that the call blocks and returns pass/fail plus the first failure, but says nothing about auth needs, cost, or how partial failures surface. Adequate but not rich.

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 clauses with zero filler: the action and scopes come first, the sibling routing last. Every word earns its place.

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

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

With no output schema, the description correctly mentions the returned pass/fail and first-failure signal, and the schema covers wait/job-ID polling and timeout bounds. It is nearly complete; only edge-case behavior on partial or errored runs is unaddressed.

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 explains file, root, test, wait, scope, and timeoutSeconds in detail (including runner-specific name filters). The description only loosely maps its three rerun scopes onto the scope parameter, adding little beyond the structured fields; 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 verb (rerun) and three concrete scopes (a failing test, a test file, changed files' tests), so the agent knows exactly what it executes. It also distinguishes itself from the full-suite path by pointing to the 'check kind tests' sibling, though that routing phrase is compressed and slightly cryptic.

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 selection criteria for the rerun cases and an explicit alternative for the excluded case (full suite goes to arno.check). It stops short of stating prerequisites or when a rerun is inappropriate (e.g., no prior failure exists).

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