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

With no annotations, the description carries the burden of explaining behavioral characteristics. It does so by disclosing atomicity (all land or none), pre-validation of anchors before writes, auto-formatting of touched files, and consolidated validation at the end. This is substantially more useful than a bare 'apply edits' statement, though it does not explicitly address failure atomicity after the final validation or error return formats, which would make it complete.

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 tightly scoped sentences: atomicity, supported ops, behavior, and usage guidance. Each sentence earns its place with the most important information (atomic unit) front-loaded. There is no repetition or fluff; the description has high information density.

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 complex tool with nested edits arrays and multiple op-specific fields, the description covers the key contextual points an agent needs before calling: atomicity, validation, formatting, and when to use it. The schema covers parameter details and the output is not specified, but the description could have briefly noted how conflicts like 'expectedRevision' or 'expectedDigest' affect overall behavior. Still, it is sufficient for most correct invocations.

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

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

The schema describes all parameters with 100% coverage, so the baseline is 3. The description does not clarify parameter semantics beyond the schema; it reiterates the operation names (which are also in the schema's 'op' description) but does not add guidance on when to use each op or their dependencies. It therefore adds no real semantic value over the already-detailed 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 opens with a specific verb ('Apply') and resource ('several edits'), immediately stating the core operation: batching edits into an atomic unit. It enumerates the exact operations supported (replace_text, replace_range, replace_symbol, delete_symbol, insert), which clearly differentiates it from sibling single-edit tools like jade.replace_text and jade.insert. The 'one atomic unit' phrasing adds essential semantics not present in the tool name.

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 final sentence gives explicit routing guidance: 'Prefer this over several single edits when changing more than one site.' This tells the agent when to choose this tool over the single-edit siblings, and indirectly the when-not case (single edits are for single-site changes). No important usage condition is left implicit.

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 provided, the description carries the full burden of behavioral disclosure. It does well: it states that the tool waits by default, returns pass/fail directly, names the command that ran, and explains dryRun behavior. It also discloses the fallback behavior for lint (runs typecheck if none declared). The only minor gap is not explicitly stating side effects (e.g., whether running tests could modify files), but for a validation tool this is largely covered by the 'validation command' framing.

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 dense but well-structured: it opens with the core action, then covers defaults, return behavior, dryRun, and multi-project handling in a logical order. Every sentence earns its place, and there is no fluff or repetition of schema content. It is appropriately sized for a tool with 5 parameters and meaningful behavioral nuances.

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 validation tool with no output schema and no annotations, the description covers the essential context: what it runs, how it waits, what it returns, how dryRun works, and how to handle multi-project repos. The timeoutSeconds parameter is documented in the schema, and the description's mention of 'waits by default' plus the schema's timeout bound gives the agent enough to call it correctly. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining the default kind (build), the relationship between lint and typecheck, and the meaning of target in multi-project repos. It doesn't repeat parameter names but adds contextual semantics that help an agent choose correct values. This is above the baseline 3 because it clarifies behavior that the schema alone doesn't convey.

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 ('Run a validation command on demand and wait for the verdict') and names the resource (build, typecheck, tests). It also distinguishes itself from siblings by mentioning it uses the repository's own Makefile target, npm script, or cargo command, and it explicitly contrasts with dryRun. This is a clear, specific purpose that an agent can act on.

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

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

The description gives explicit when-to-use guidance: 'In a repository with several projects, pass target to check one; with no command at the root, the answer lists the projects.' It also explains the default behavior (waits by default) and the dryRun alternative. This is strong usage guidance that tells the agent when to use this tool and how to adapt to different repository structures.

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 full burden. It discloses the key behaviors: creating missing directories, refusing to overwrite, and directing to alternatives. It doesn't cover error handling or return values, but for a simple file-creation tool, the critical behaviors are transparent.

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 with zero waste. The purpose is stated first, followed by a critical behavioral constraint and alternative tools. Perfectly front-loaded and 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?

For a 2-parameter tool with no output schema, the description covers all essential information: what it creates, the side effect of creating parent directories, the overwrite refusal, and alternatives. An agent has everything needed to 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 coverage is 100% with both parameters described. The description adds no extra parameter-specific meaning, but it's not needed given the schema's clarity. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a brand-new file and creates missing parent directories. It also explicitly names alternatives (replace_text, apply) for modifying existing content, distinguishing it from siblings like apply and 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?

It explicitly says it refuses to overwrite existing files and directs the agent to use replace_text or apply for existing content. This provides clear when-to-use and when-not-to-use guidance with named alternatives.

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 disclosing behavior. It explicitly states that declaring an existing name replaces it, that commands persist across sessions, and that the file is reviewed like any change. This is strong for a mutation tool, though it stops short of discussing permissions, reversibility, or result output.

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, no filler. The action and target lead, followed by the critical caveat about replacing existing names and not redeclaring just to run. Every phrase 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?

The tool is simple and the schema covers all parameters, while the description covers persistence, overwrite behavior, and reviewability, and routes usage to run_command. It does not describe return values or errors, but that gap is minor given the straightforward mutation and clear parameter 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 description coverage is 100%, so the baseline is 3. The description adds overall context about persistence and replacement but does not enrich the meaning of individual parameters beyond what the schema already documents.

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

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

The description names a specific verb and resource: declare a named command in .jade/commands.json. It also states the purpose, running it with run_command in this and later sessions, and the caution against redeclaring just to run distinguishes it from its sibling run_command.

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 clearly says declarations are meant to be run via run_command and warns not to redeclare an existing command just to execute it, implying one-off execution should go to run_command instead. It does not explicitly enumerate when to use remove or other siblings, but the core usage context is 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 only declare destructiveHint, so the description adds meaningful behavior beyond it: failure on nonexistent files and a notable reversibility caveat ('Reverting to an earlier checkpoint recreates it'). No contradiction with annotations.

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

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

Three short sentences with no filler: first states action and scope, second covers failure and reversibility, third routes to alternatives. Every sentence earns its place and the most important information is front-loaded.

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

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

For a single-parameter tool with no output schema, this is complete: it covers purpose, failure mode, reversibility, and alternatives. Nothing essential is missing for an agent 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% and the path param is self-explanatory, so baseline is 3. The description adds value by clarifying the path must be a file (not a directory), which directly informs the parameter's acceptable value.

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 the specific action 'Delete a file', the resource type, and explicitly excludes directories. The failure condition ('fails if it does not exist') and the pointer to edit alternatives ('use replace_text or apply') distinguish it clearly from sibling tools like create_file, replace_text, and apply.

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

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

Provides explicit exclusion ('not a directory'), a precondition ('fails if it does not exist'), and names concrete alternatives for the adjacent use case of editing ('replace_text or apply'). An agent can decide unambiguously when to use this tool versus 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?

Annotations only say readOnlyHint=true, so the description carries the behavioral burden. It adds useful semantics: exact name matches win over substring matches, source is returned in the same call, and multiple names can be searched at once. These are genuine behavioral traits beyond 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?

The description is compact and front-loaded: the first sentence states the core action and value, then matching behavior and usage guidance follow. Every sentence earns its place, and there is no repetition of schema metadata.

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?

The description gives purpose, matching semantics, and an explicit usage condition, while the schema fully documents all eight parameters. The main remaining gap is that there is no output schema, so the agent gets less detail about the exact return shape, but the description still conveys what comes back: source code.

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 applies even without parameter detail in the description. The phrase 'Pass queries to find several names' mirrors the documented queries parameter and adds no new syntax or format details.

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 action ('Locate declarations by name') and a concrete outcome ('return their source in one call'), making the tool's purpose unambiguous. It also distinguishes itself from siblings like read_range and grep by positioning itself as the fused search-and-read, so an agent can tell what it is for.

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

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

It gives explicit routing guidance: 'Use this instead of outline and read_range when you have not located the symbol yet.' It also notes multi-name lookup via queries Serious. The only gap is that it does not give a full when-not matrix, but the guidance is clear and actionable.

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 readOnlyHint=true, matching the description's search-only semantics, so no contradiction. The description adds behavioral context beyond annotations: it is the replacement for `grep -rn`, supports regex and alternatives, and notes that the answer may be cut with `continue=<handle>` for pagination, which is not in annotations. It doesn't mention read-only explicitly but that's implied by the annotation; minor gap on permission details.

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 three sentences with no filler. It front-loads the core purpose and return format, then adds usage guidance and a tip about `queries`. Every sentence earns its place, and it's appropriately concise for the tool's complexity.

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?

The tool has 11 parameters and no output schema, but the description plus detailed schema parameter descriptions fully cover how to use it: it explains return format, pagination via `budget`/`continue`, alternatives like `queries` and `regex`, and path filtering. It also gives the sibling differentiation. For a complex search tool with multiple params, the description is complete enough for an agent to call 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% with detailed parameter descriptions (e.g., `budget` is 'Size of the answer in tokens. Cut at whole matches; the rest is behind continue=<handle>'). The description adds extra meaning by clarifying that `queries` is an alternative to `query` with same filters, and that `regex` matches grep-style syntax. It goes beyond the schema by explaining how `budget` interacts with `continue`, which is not in 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 uses a specific verb ('search') and resource ('workspace'), states the return format ('path:line matches with optional trailing context'), and explicitly distinguishes it from the sibling tool `find` ('anything that is not a declaration name' vs 'a declaration and its body'). It also names alternative uses (struct fields, string literals, error messages, config keys) making the purpose unmistakable.

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 provides explicit when-to-use: 'Use this for anything that is not a declaration name' and when-not: 'Use find instead when you want a declaration and its body.' It also mentions 'pass queries to search several patterns in one call' and 'grep-style alternation', giving clear guidance for multi-pattern searches. No exclusions are missing.

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 transparency burden. It discloses key behaviors: appending with no anchor, before/after placement with an anchor, and refusal when the anchor is absent or matches more than once. It does not discuss output or permissions, but the core failure and placement semantics are 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?

Three sentences, each earning its place: the core purpose, the when-to-use guidance, and the anchor/precondition behavior. The most important differentiator is front-loaded, and the sibling alternative is neatly at the end.

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?

The description is complete for selecting and invoking the tool in common cases: it explains additive use, anchor behavior, and the key alternative. It does not describe the success response or the digest/revision preconditions in prose, though those are fully covered in the schema. Given the tool's relative simplicity, this is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds behavioral meaning beyond the schema by explaining the interplay between anchor and position, including the append fallback and the refusal on ambiguous anchors. This enriches rather than merely repeats the parameter docs.

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 opens with a specific verb and resource: "Add text to a file without replacing anything," then gives concrete examples like a new function or section. This clearly distinguishes it from siblings such as jade.replace_text, so an agent can tell them apart immediately.

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

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

It explicitly states when to use the tool: "Use this for additive work instead of rewriting a surrounding symbol." It also names the alternative for multi-edit scenarios: "Several additions or edits at once belong in apply." This gives direct routing guidance with no inference needed.

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

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

The description adds behavioral details beyond the readOnlyHint annotation: the budget parameter cuts reads at whole lines and provides a continue handle, error handling for multi-range calls is described, and dependency reads are marked read-only, aligning with 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?

The description is slightly long but well-structured, front-loading the core purpose and then layering usage details. Every sentence carries information; the example is compact and illustrative.

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 tool with no output schema, the description covers key behaviors: how to address ranges, how to batch reads, how to handle dependency paths, and how pagination works via continue. It lacks an explicit description of the return format, but that is inherent to a file-read operation. Overall, it is complete for an agent to invoke correctly.

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

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

The schema already documents all parameters with descriptions, so baseline is 3. The description adds value by explaining the semantics of the 'lines' format, the 'ranges' structure with a concrete example, and the budget/continue flow, which clarifies usage 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 clearly states the tool reads file contents verbatim, whole or by line range, and positions it as the replacement for cat and sed -n. It distinguishes from sibling tools like find and grep by focusing on direct file content retrieval, and mentions dependency path syntax.

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 guidance on when to omit line numbers to read whole files (e.g., go.mod, config files), how line ranges behave (end past EOF reads to end), and how to read dependency sources read-only. It also shows how to batch multiple reads in one call with an example, making usage 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?

No annotations are provided, so the description carries the full burden. It discloses a safety-critical behavior—refusing when the anchor is absent or matches more than once—and explains why anchor-based edits are stable over line numbers. It does not explicitly state that the file is modified or describe post-edit confirmation, but the core refusal and stability behaviors are transparently presented.

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 tightly packed sentences: the first defines the operation, the second explains the rationale for anchor-based edits, and the third states constraints and routes to the appropriate sibling. No filler; every sentence earns its place.

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

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

Covers the operation, uniqueness requirement, disambiguation strategy, and alternative for multi-site edits. With no output schema and no annotations, it could have mentioned success/return behavior, but the parameter schema already covers the inputs and the description handles the essential behavioral context adequately.

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 adds practical framing for oldText (exact, unique, extend for disambiguation), which reinforces the schema, but it does not meaningfully expand on path, newText, expectedDigest, or expectedRevision beyond their schema descriptions.

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

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

Opens with a specific verb and resource: 'Replace an exact, unique string in a file.' It clearly distinguishes itself from sibling tools by framing edits as anchor-based rather than line-based and by redirecting multi-site edits to apply. Purpose is immediately recognizable.

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 instructs when to use an alternative: 'For several sites, use apply.' It also provides conditional guidance for the main use case—when the anchor is absent or duplicated, extend it with surrounding context to disambiguate. This gives clear decision rules for correct usage.

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 discloses that it waits for a verdict, returns pass/fail with output, and that wait=false returns a job ID for polling. It also mentions timeout behavior via schema. However, it does not mention side effects (e.g., does it modify the repo?) or any safety implications, but for a runner tool, the description covers the essential 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?

The description is concise, with three sentences that are information-dense. It front-loads the core purpose (run command by name, wait for verdict) and then provides usage alternatives and next steps. Every sentence earns its place with no fluff.

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

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

Given the tool's moderate complexity (3 optional params, async behavior), the description covers the main points: what it does, how to list commands, how to use wait=false, and the timeout bound. It doesn't describe the exact format of the verdict output, but since there's no output schema and the description mentions 'decisive output,' it's reasonably complete. A small gap is not explaining the relationship to run_tests, but that's minor.

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 three parameters. The description adds some context (e.g., omit name to list, wait=false returns job ID, timeout is a bound) but largely reinforces the schema. Baseline 3 is appropriate because 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 clearly states the tool runs a declared command by name and waits for a pass/fail verdict with decisive output. It also distinguishes it from the shell by saying to use it instead of a shell for anything check does not cover, and it mentions the sibling declare_command for declaring commands.

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

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

It explicitly says when to use it: instead of a shell for anything check does not cover. It also gives instructions for listing commands (omit name) and for declaring new commands (declare_command it once). This provides clear guidance on alternatives and conditions.

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 behavioral burden. It discloses the key wait behavior ('waits for pass/fail and the first failure') and implies a stop-at-first-failure mode. However, it omits the result payload shape, side effects, and how polling works after wait=false 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?

Two short sentences front-load the purpose and accepted scope variants, then cover wait behavior and the alternative tool. Every sentence earns its place, and there is no filler or repetition of schema content.

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

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

The schema handles the parameters well, but with no annotations and no output schema, the description should explain more about results and edge cases. It says tests wait for pass/fail and the first failure, but it does not characterize the returned object, what 'changed' is relative to, or how to poll an async job. Adequate for basic reruns, not fully complete for all invocation modes.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context by mapping 'changed files' tests' to scope=changed and clarifying that full-suite runs belong to check rather than run_tests. It doesn't add deep formatting details, but the scope interpretation is meaningful enough to merit a 4.

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 concrete verb ('rerun') and resource ('tests'), and enumerates the supported variants: failing test, test file, or changed files' tests. It also distinguishes itself from the sibling jade.check by directing full-suite runs there, so an agent can tell the tools apart without opening the schema.

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

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

It clearly frames the tool for re-running targeted tests and explicitly routes full-suite execution to the 'check' tool. The phrasing 'Full suite: check kind tests' is slightly telegraphic, but it does provide a usable when-not-to-use signal and names the alternative.

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