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

With no annotations, the description fully carries the burden: it discloses the isolated-worktree execution model, that checks are run, that the result lands uncommitted in the caller's tree, that the agent should read the result block instead of re-checking, and the BLOCKED/RUNNING settling behavior. That covers exactly the traits an agent needs before invoking a mutating tool.

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

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

No filler sentences and the most important rule is first, but it is packed into long semicolon-chained sentences, and the dense inline plan-format spec is harder to scan than a short bulleted block would be.

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

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

For a 10-parameter mutating tool with no annotations and no output schema, the description covers execution model, return semantics ('result block'), and the full plan/steps protocol. It stops short of describing what a landed result or a BLOCKED group actually looks like, and says nothing about permission or conflict handling.

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 3 baseline is already met; the description goes further by specifying the plan file format (heading, files/do/done-when keys, needs:, dont:), the difficulty bucketing, the steps grouping grammar ('3-5', '1-2,3'), and that backticked done-when text is executed as a shell command. Minor deduction for not clarifying note/brief/source interaction with each other.

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 scope: 'Make any code change' and explicitly extends it to small, mechanical, and multi-file edits, which implicitly separates it from research/land siblings. An agent can tell this is the general edit-delegation tool without opening the schema.

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

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

Gives an explicit rule ('use this for every edit') plus the rationale (cheap worker vs. expensive orchestrator tokens), and names the branching condition: use plan + steps instead of task for multi-step work. It also names jobs(action="wait") as the follow-up when wait=false.

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

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

With no annotations, the description carries the full burden, and it does disclose two genuinely useful traits: cancel preserves the worktree (a non-obvious side effect) and wait blocks until settlement (a latency trait). It says nothing about whether cancel is otherwise irreversible, whether wait can time out or hang indefinitely, or what state changes show/list cause.

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

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

A single sentence with each clause mapping to exactly one action, and the non-obvious detail (worktree retention) placed in a parenthetical rather than buried. It is dense but every clause earns its place; 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 2-parameter multi-action tool with no annotations and no output schema, the description covers all four modes and the batch variant, and flags the one destructive-adjacent nuance. The remaining gap is that nothing explains which action is the common/default one or what list and show actually return in shape.

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

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

Schema coverage is 100% and the action enum already documents all four modes plus the job-vs-batch id distinction, so the schema does the heavy lifting. The description adds only marginal value beyond it — the word 'again' for show and 'batch' for wait — which matches the baseline 3 for high-coverage schemas.

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 enumerates four concrete verb+resource operations (list jobs, show last result block, wait for settle, cancel) rather than restating the name, so an agent immediately knows the tool is a multi-action job control surface. It does not, however, distinguish itself from siblings like delegate or land, so an agent must infer that this tool observes/controls jobs while delegate presumably creates them.

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?

Each action clause implies a situation ('wait for a job or batch to settle', 'cancel a running job'), which gives implied usage guidance per action. But there is no explicit when-to-use-this-vs-alternative routing (e.g. 'use delegate to start a job, then jobs to wait on it'), and no stated exclusions or prerequisites.

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 and does well: it discloses that apply is a 3-way application, leaves changes uncommitted, and leaves the tree untouched on conflict, while discard deletes the worktree. It could go further on irreversibility or permissions, but the key side effects 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?

It is three tight sentences with the core scope and action behavior front-loaded. Every clause adds information, and there is no redundant restatement of the tool 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 two-parameter tool with no output schema, the description covers the action semantics, conflict behavior, multi-job handling implied by 'one line per job,' and the relevant job statuses. An agent has enough context 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%, so the schema already documents both parameters including the comma-separated job format and action enum meanings. The description adds little parameter-specific detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Land or discard finished jobs') and scopes it to jobs that did not land, naming example statuses (PARTIAL, FAIL, CONFLICT). This clearly separates the tool from unrelated siblings such as reply, jobs, and delegate.

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 implies when the tool applies: finished jobs that did not land, with statuses given as examples. It also explains the two actions enough to choose between them, though it does not explicitly name alternatives or exclusions.

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

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

No annotations are provided, so the description carries the burden, and it does reasonably well: it discloses that the call verifies server availability and returns version information, implying a side-effect-free read. It does not state failure behavior (e.g. what happens if the server is down) or auth requirements, keeping it just 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?

A single, front-loaded sentence with no wasted words that conveys both the action and the returned 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 trivial no-parameter health check with no output schema, the description covers purpose and the key return value (version). Minor gaps: no mention of error/timeout behavior if the server is unreachable.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a no-parameter tool 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: checks that the Cheap Agent server is running and reports its version. This is unambiguous and clearly distinct from siblings like reply, jobs, and delegate.

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 intended use (a health/connectivity check) is strongly implied by 'ping' and 'check that the server is running,' but the description never explicitly says when to use it versus alternatives or when not to call it.

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

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

With no annotations, the description carries the burden well: it discloses that the worker resumes in the same session and describes the return (OK, FAIL, or BLOCKED again), plus batch settlement behavior. Lacks details like auth or idempotency but is solid for a reply action.

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, front-loaded with the action and followed by return semantics. Zero waste.

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, yet the description explains the return block variants, which is exactly the missing context. Complete enough for a two-param action tool, though batch edge cases could be elaborated slightly.

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

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

Schema coverage is 100%, so both parameters (job, answer) including the answer format examples are already documented. The description adds no param meaning 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?

Specific verb+resource: answers a BLOCKED job's question and resumes its worker. The BLOCKED-state scoping clearly distinguishes it from sibling job-management tools like jobs, land, and delegate.

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 BLOCKED precondition makes the trigger condition clear, and the return semantics hint at follow-up states. It doesn't explicitly name alternatives among siblings, but the state gate is strong context.

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

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

With no annotations, the description does real work: it declares the operation read-only, notes it is cheap, discloses data freshness ("reads the working tree, uncommitted changes included"), and describes the return shape with path:line refs and a confidence value. The remaining gap is latency/rate expectations and any limits on the number of distinct searches.

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

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

Front-loaded with the core purpose, then the mechanism, then the return contract and a caution — a sensible ordering with almost no filler. The parenthetical about the working tree slightly interrupts the sentence flow but still 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 and no annotations, the description covers what an agent actually needs: side-effect profile, tree freshness, return shape, and a reliability caveat. Cost and latency expectations for the "research worker" are the only meaningful omission.

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 three parameters are already fully documented in the schema itself. The description adds only that a question is asked and that answers are short, without clarifying how `paths` scoping or `max_words` cap interact with the reported confidence. 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?

Opens with a specific verb+resource ("Find and explain code in this repository") and clarifies the mechanism (a read-only research worker answering a question). An agent can tell this is a code-lookup tool rather than a generic action tool, though it never contrasts itself with the ambiguously named `delegate` or `jobs` siblings.

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

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

Use is implied by "find and explain code" and the closing instruction to "verify low-confidence answers before acting," which gives useful follow-up behavior. However there is no explicit when-not-to-use or which sibling to pick for adjacent tasks, leaving the agent to infer routing against `delegate`.

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