aiworkhub_dashboard_task_quarantine_purge

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 covered; the description goes further by enumerating the concrete effects — payload deletion from task_retention_batches, a purged audit row, and invalidated storage telemetry — plus the precondition on restore_deadline. This is exactly the kind of beyond-annotation context that matters for an irreversible operation.

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 'DESTRUCTIVE:' prefix is front-loaded before any procedural detail, and the two sentences are dense with preconditions, alternatives, and side effects without filler. Every clause earns its place.

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?

With an output schema present, return values need not be explained. The description covers the irreversible nature, the required confirmation, the deadline precondition, alternatives for inspection and recovery, and the concrete downstream effects — everything an agent needs to invoke it safely.

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 100%, so both parameters are already documented, which sets a baseline of 3. The description adds real meaning on top: it clarifies that confirm=True is a hard requirement and that batch_id must reference a batch that is expired or already restored, a precondition absent from the schema.

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 opens with a specific verb and resource ('DESTRUCTIVE: permanently delete one expired or already-restored archived-task quarantine batch') and pins down scope to a single batch. An agent can distinguish this from the sibling quarantine, restore, and retention-preview tools without inspecting 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?

It names two concrete alternatives and the conditions that select them: inspect with aiworkhub_dashboard_task_retention_preview first, or recover with aiworkhub_dashboard_task_quarantine_restore while the undo deadline is active. It also states the gating prerequisites (confirm=True and an expired restore_deadline unless already restored), leaving nothing to inference.

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