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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered; the description adds the genuinely non-obvious behavior that quote=true prices the decisions and changes nothing, i.e. a dry-run mode. It also states the cardinality invariant (decisions must cover exactly the open positions, once each), which is behavioral rather than structural. It does not describe what retry/edit triggers downstream in the engine.

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, zero filler, purpose and action set front-loaded, then the sourcing precondition, then the quote modifier. Every clause carries distinct operational 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?

Return values need not be explained because an output schema exists. The description covers the preconditions, the action space, the coverage invariant, and the dry-run flag, which is enough for correct invocation. Minor gap: no statement of which run states are valid targets or what happens to skipped items.

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 0%, so the description has to carry the load, and it does: it explains the three action values in prose, defines `position` as the open position from recovery.items (not just an integer index), and defines `quote` as a non-mutating price check. `revision` is sourced to get_workflow_run's recovery payload; only run_id and step_id are left to obvious inference.

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 precise verb+resource ('Decide workflow items' → answer an engine run paused on `items`) and enumerates the exact choice space: retry, edit prompt and retry, or skip. This clearly separates it from the sibling run-lifecycle tools (retry_workflow_run, resume_workflow_run, cancel_workflow_run) which act on the run as a whole rather than on individual failed items.

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 the triggering condition ('an engine run paused on items') and the required prerequisite workflow: read open positions and the current revision from get_workflow_run's `recovery.items`, and cover exactly those positions once each. It also flags the non-mutating preview path via quote=true, but never names a sibling alternative for agents who actually want to retry or resume the whole run.

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