aiworkhub_task_retry_terminal

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

With no annotations, the description carries the full burden and does so: it declares this is a write/requeue of the same task ID, that append-only audit history is preserved, and that the response is a versioned receipt with idempotency and linkage keys. The payload-size warning tied to include_card=full (67,395 chars on one measured call) is exactly the kind of behavioral context annotations would otherwise supply.

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 coordinator-write framing and eligibility before the receipt detail, and most sentences earn their place. The incident reference (NF-2026-01447) and exact character count are borderline anecdotal, though they do justify the include_card warning.

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 annotations and a 5-param schema, this covers eligibility, audit consequences, idempotency, and return shape well beyond what the output schema alone would convey. Only the `reason` parameter and any permission/precondition requirements are left 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 coverage is 0%, so the description must compensate, and it does for the critical ones: request_id and terminal_substatus are declared mandatory and paired to the prior failure, and include_card is fully explained including its default and the size consequence of 'full'. The optional `reason` parameter is never mentioned, leaving one gap.

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 ("retry one exact operational terminal episode") and pins the scope to task requeue with preserved audit history. An agent can distinguish this from generic recovery/retry siblings like aiworkhub_task_recover_blocked_rework 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?

Explicit eligibility list (blocked cancelled/timed-out/launch/worker/process/liveness failures) and an explicit exclusion (semantic validation/review failures stay on the review workflow), plus the mandatory prior request id and substatus. It does not name the sibling tool an agent should use for the excluded review case, so routing is good but not fully closed.

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