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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes beyond them by explaining the actual destructive semantics: the default is non-destructive preservation, deletion of absent items happens only under an explicit opt-in, and removal tracking is done via draft removal tools. That is exactly the operational context an agent needs before firing a destructive ship action.

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?

Four sentences, front-loaded with the core action before the conditional semantics. Each sentence carries informational weight, though the middle two restate the preservation/removal rule from slightly different angles and could be tightened.

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 critical gaps: default behavior, the destructive escape hatch and its guardrail, and how the target draft is resolved. Return format is not required since no output schema exists, and annotations carry the safety profile.

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 100%, so the baseline is 3, and the description adds real value on top by framing replace_missing as a destructive mode with a user-confirmation precondition and explaining why draft resolution matters. It does not add meaning for members, draft_id, cluster_id, or expected_digest beyond what the schema already says.

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?

States a specific verb and resource: 'Apply the current stack draft to the cluster', then adds scope ('handles both brand-new database drafts and already-deployed stacks by computing the lifecycle and bill of materials internally'). This separates it from plain manifest/applies in spirit, but no sibling tool (e.g. redeploy_stack, apply_manifest, resolve_gitops_conflict) is named, so the distinction is inferred rather than explicit.

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?

Gives clear operating conditions: absent items are preserved by default, and replace_missing=true is reserved for a full replacement 'only after confirming the exact deletions with the user'. The destructive opt-in condition is spelled out, though no alternative tools are named for the non-draft path and no prerequisites (permissions, cluster lock) are mentioned.

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