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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds genuinely new context — that removal is an archive, that the call is refused under open deals, and that the first invocation is a no-op preview. It doesn't say whether an archived pipeline can be restored, which is the main residual question for a destructive op.

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?

Three short sentences, zero preamble, with the core operation stated first and the constraint and two-step flow following in priority order.

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 mutation with no output schema, the description covers the safety profile, the blocking condition, and the confirmation flow. Reversibility of the archive and any permission requirements are the remaining gaps, but they don't prevent correct invocation.

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 67%, and the confirm_token parameter already carries a thorough description including the empty-on-first-call rule. The description's 'two steps: the first call only says what will happen' reinforces that but adds little beyond the schema, and pipeline_id remains undocumented in both places.

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?

'Remove (archive) a pipeline' gives a specific verb plus resource and importantly disambiguates that the removal is archival rather than a hard delete. It doesn't explicitly name sibling tools (e.g. dosai_update_pipeline, dosai_list_pipelines), so differentiation relies on the parenthetical alone.

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?

States a concrete precondition and what to do instead: 'Refused while it has open deals: move or close them first.' This gives an agent an actionable blocked-state path. It does not name the specific sibling tools (move_deal/update_deal) that resolve the block, leaving that to inference.

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