queue_undo_purge

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

Annotations are absent, so the description carries the full burden. It discloses the time-based limitation and the scope (tasks not yet started), which is useful. However, it omits potential failure modes (e.g., what happens if undo_batch is invalid or the 60-second window has passed) and does not state whether the operation is idempotent or reversible. The behavior is described, but not as exhaustively as a mutation tool without annotations might warrant.

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 two sentences, tightly packed with the core action and then critical constraints. It is front-loaded with the verb and resource, and every clause carries meaning. No redundant information or unnecessary elaboration.

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?

The description covers the purpose, the parameter, and the two key constraints (time limit and task state). It lacks explicit information about return values or error handling, but given the simplicity of a single-parameter tool with no output schema, this is a minor gap. The reference to the sibling queue_purge provides the necessary context for when this tool is intended to be used.

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?

The schema provides no description coverage for the single parameter 'undo_batch' (0%). The description compensates fully by explaining that it is 'the undo_batch id from that call's response', giving both the source and purpose of the value. This is sufficient for an agent to know how to obtain and use it correctly.

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 clearly states the tool's purpose: it re-queues tasks previously purged by a specific queue_purge call, using the undo_batch id from that call's response. This is a specific verb-resource pairing that distinguishes it from sibling tools like queue_cancel_task or queue_purge, and it explicitly references the prerequisite operation (queue_purge).

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?

The description gives clear usage conditions: it is only valid within 60 seconds of the purge and only for tasks that hadn't started running. This effectively tells the agent when this tool is applicable. It does not explicitly name alternative tools for scenarios where these conditions fail, but the constraints are unambiguous and sufficient for most realistic decision-making.

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