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 structurally. The description adds real behavioral context beyond them: the async non-blocking return ('answer without waiting for the download'), the server-name copy convention, the divergence-recovery semantics of full, and critically the human-approval interruption ('May stop to ask a human to approve'). It stops short of describing what exactly is overwritten on the target.

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 purpose is front-loaded in the first clause, and the branch conditions follow in a dense single paragraph with little wasted text. The phrasing ('hand the mirror what changed since its last pull') is colorful but slightly indirect.

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 an 8-parameter destructive mutation with no output schema, the description covers the core behaviors and the approval flow. It is still incomplete on the five undocumented parameters and on what precisely is destroyed or overwritten on the mirror target.

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 only 13% (only approval is documented), so the description must compensate. It usefully explains server, full, and the mode branch, but leaves volume, project, environment, request_key, and wait_seconds entirely opaque in both schema and description.

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+resource: making a Volume's mirror current, then distinguishes two operational modes (copy to a server vs. hand the mirror incremental changes). This is clear enough to select over unrelated siblings, but it never names or contrasts against the closest alternatives like volume_mirror_remove or volume_move.

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 implies when each branch applies (server present = copy there, absent = incremental, full = recopy a diverged mirror), which is useful conditional guidance. However, it never states when NOT to use this tool or routes the agent to a sibling alternative, so usage is only inferred.

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