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

Despite annotations already marking this destructive and non-idempotent, the description adds substantial behavior detail beyond them: lineage preservation, transfer of prerequisites and downstream dependents, cancellation with supersession provenance, audit history retention, and that nothing is marked delivered. It also discloses validation limits that reject inputs without writes, the authenticated GitHub read required for carry_forward, and that the head SHA is server-resolved.

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 description is front-loaded with the core action and effects, then moves to constraints and parameter semantics in a logical order. Paragraphs are dense but every sentence adds operational value (lineage, limits, strategy choice, authentication requirement) with 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 destructive, multi-effect task-replacement operation with an output schema, the description covers what changes, what is preserved, what is rejected, and the critical workspace_strategy decision. Given the output schema exists, return-value detail is unnecessary, and nothing essential for correct invocation is missing.

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?

With 0% schema description coverage, the description must compensate, and it does well for workspace_strategy (fresh_main vs carry_forward, required when undelivered implementation is identified) and recovery_source_pr_number (declared PR checked via authenticated GitHub read). It also specifies size limits for title, body_md, acceptance_criteria, and decision_md. However, project_id and task_id are not described, and decision_md semantics beyond its character limit remain unexplained.

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 line gives a specific verb and object ('Replace an unretryable blocked task') and immediately distinguishes the scope from retry semantics via 'unretryable'. The follow-up sentences enumerate the concrete effects (fresh task under same lineage, transfer of prerequisites/dependents, cancellation with supersession provenance). An agent can tell this is not retry_blocked_task.

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 establishes the condition for use ('unretryable blocked task') and gives detailed when-to-use/when-not guidance for workspace_strategy, including that carry_forward is refused until the runner path is enabled. The main gap is that it never names the sibling retry_blocked_task as the alternative for retryable blocks, leaving that contrast implicit.

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