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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the mutation and idempotency profile is covered. The description adds genuine value beyond them: bounded/partial-update semantics ('Preserve unrelated and hidden content') and the concurrency recovery protocol for version conflicts. It stops short of describing error/return behavior.

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 dense sentences with no filler, and the core purpose leads. Preservation and conflict/retry rules follow in logical order. Slightly terse given the enormous operations surface, but nothing is wasted.

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 highly complex, no-output-schema mutation tool, the description covers the hard parts an agent must get right: partial-update preservation, version-conflict recovery, and retry idempotency. Return values and the operations catalog are left to the schema, which enumerates operations fully.

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 0%, so the description must carry the load. It gives useful meaning for expectedVersion and idempotencyKey ('Reuse the same idempotency key for retries', 'at its expected version'), but says nothing about the operations parameter, which is the bulk of the schema (30+ operation variants, 14 sections, item shapes). Partial compensation only.

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 ('Apply the requested bounded changes') and resource ('a selected resume at its expected version'), which is clear and actionable. It implicitly distinguishes itself from create_resume and restore_resume_version via 'bounded changes,' but never names a sibling or explicitly contrasts operations.

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?

Provides real operational guidance: re-read the latest document after a version conflict, never retry stale edits, reuse the idempotency key. This tells the agent when and how to retry. It does not, however, route the agent to alternatives (e.g., restore_resume_version or get_resume) for cases this tool cannot handle.

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