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

Annotations already declare the safety profile (mutating, idempotent, non-destructive). The description still adds real value beyond them: human-review-required outputs, byte-identical attachments, immutable field provenance with no citation pollution in numeric/boolean values, and explicit retry/idempotency discipline for failed operations.

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?

It is front-loaded with the core action and is not bloated with filler, but it is a dense run of semi-colon-joined clauses mixing parameter rules, mutation semantics, and retry policy, which makes it hard to scan for a single actionable instruction.

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 14-parameter mutation with nested objects, no output schema, and near-zero schema annotation, the description should define the key inputs and their interplay. It covers adaptive/provenance/retry aspects but omits the meaning of selection, the revision objects, expectedVersion, and the target arrays, leaving significant gaps.

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 only 7% (just idempotencyKey), so the description must carry the burden for 14 parameters. It clarifies adaptiveRevision, adaptiveDocumentId, and per-target fieldId for the adaptive case, but leaves planRevision, draftRevision, selection, confirmationId, itemId, expectedVersion, sectionIds, consistencyFacts, and the target-array shapes unexplained.

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 opening sentence states a specific verb (produce) and resource (one selected item / document) and situates it under 'exact-plan human agreement', and later sentences name DOCX, adaptive dossiers, and legacy forms. An agent can tell this is a document-generation tool, though it never explicitly distinguishes itself from siblings like submit_draft or export_document_pack.

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?

The description gives conditional context ('For an adaptive dossier, provide its exact adaptiveRevision', 'Legacy forms use named draft sections') and a retry rule ('inspected before retry, never forced with a new key'), which helps the agent choose parameters. However it never states when to prefer this tool over alternative siblings, so usage is implied rather than routed.

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