jobs

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.