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

Goes well beyond the annotations: it discloses that existing sections, blocks, chart data or Visual Story are replaced or removed, that the prior state is recoverable from version history (one step back for the Visual Story), and that publishing flows through Clarifo's own Publish step with plan rules and content review. The base_version/preview_hash concurrency guard and the version_conflict refusal are behavior an agent could not infer from readOnlyHint/destructiveHint alone, and nothing contradicts the declared destructive and idempotent hints.

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 workflow and conflict-handling rules are front-loaded in the first two paragraphs, which is the right structure. The long Args list is repetitive and adds bulk, though each line does at least repeat the 'copy it exactly' rule; the Returns block is redundant given the output schema but harmless.

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 16-parameter mutation, the description supplies the full call sequence, the concurrency contract, the conflict recovery, and the safety story around publish and version history. The main remaining gap is the undocumented seo parameter and the unstated semantics of operation values, but the 'use exactly the preview's arguments' rule largely compensates by routing the agent through preview_document_update.

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?

With 0% schema description coverage, the Args block carries the load, but nine of the sixteen parameters are described only as 'As in the preview', which tells the agent where to get the value, not what the value means. base_version, preview_hash, idempotency_key, workspace_id and publish are genuinely explained, but the meaning of operation values is left implicit and the seo parameter is never mentioned at all.

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?

Opens with a specific verb and resource ('Save a change shown with preview_document_update') and explicitly names both modes: applying a previewed edit or publishing it. It also names the companion tool preview_document_update, so an agent can distinguish the two without inspecting either schema.

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 the exact precondition (only after the preview and the user's agreement), the alternative route (publish= as previewed), and the recovery path on failure (on version_conflict, read the document and preview again). The retry rule for idempotency_key — leave it out unless retrying this same request — is also explicit.

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