aiworkhub_task_recover_blocked_rework

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

No annotations exist, so the description carries the full load. It does valuable work on the response contract and on refusal behavior (oversized feedback_reason is refused, never truncated; argv containing the reason is never echoed — a real leak-prevention detail). But for a recovery/mutation transaction it says nothing about eligibility preconditions, what state transition occurs, whether the action is idempotent or reversible, or whether it re-launches a worker.

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 opening sentence is correctly front-loaded and no sentence is pure filler, but the bulk of the paragraph is devoted to the receipt projection and stdout-parsing behavior. Since the tool already has an output schema, that length is largely misallocated relative to the unaddressed parameters.

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?

An output schema exists, so explaining the _lifecycle_receipt shape is optional; meanwhile the gaps that matter — when this tool applies, what it changes, and four undocumented parameters — are unfilled. For a 6-parameter manager-level transaction tool with no annotations, the description is not sufficient 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 description coverage is 0% across 6 parameters, so the description must compensate and it covers only two: feedback_reason (8000-byte UTF-8 cap, required when scope_rejection_resolved is set) and scope_rejection_resolved. validation_amendment, validation_only_replay, and clean_root_if_predecessor_missing are left entirely undefined, including the last one which appears to be a significant safety switch.

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 first sentence names a specific verb and scope ("Recover one exact blocked task") which is better than a restated name, but "blocked rework" and "the canonical transaction" are internal jargon. Critically, the sibling list contains many adjacent recovery/retry tools (aiworkhub_task_stale_recovery_recommend, aiworkhub_task_retry_terminal, aiworkhub_manager_reconcile_dead_processing, aiworkhub_agent_retry_finalization) and the description draws no boundary against any of 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?

There is no statement of when to reach for this tool versus a retry, a stale-recovery recommendation, or a reconcile. The only precondition-like content is that scope_rejection_resolved is the manager's audited resolution of a scope_rejected card and requires feedback_reason, which is parameter semantics rather than routing guidance.

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