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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: complete replacement of richDocument, preserving untouched content and stored media URLs, text replacing layout, media binding rules, and the never-publishes guarantee. These non-obvious side effects are the value-add, though the exact output/response contract is left to the output schema.

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?

Compact and dense, with the usage trigger front-loaded and operational sequencing packed into short clauses. It is effective but slightly telegraphic — the second half reads as a list of imperatives (Import files, Include the image, Inspect preview_post) that could be structured more clearly.

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 15-parameter mutation tool with a complex nested richDocument and an output schema present, the description covers the critical authoring workflow, preserve-what-you-don't-touch behavior, media binding, and the no-publish guarantee. Return values are rightly deferred to the output schema, leaving only minor gaps such as idempotency/error behavior.

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 73%, so the schema carries much of the load, but the description adds meaning beyond it: 'text replaces layout', richDocument must be the complete edited document started from preview_post.documentJson, media files bind as media.src, and instructions is limited hints only and does not run an AI editor. These clarify non-obvious interactions between parameters that the schema alone does not convey.

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 name and title say 'update a post draft', while the description opens with 'Use this when editing a draft' — a usage trigger rather than a clean statement of what the tool does. It implies a draft-editing/update operation but never states plainly that it modifies an existing draft by id, and it does not differentiate itself from siblings like update_post, attach_media_to_draft, or create_post_draft.

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 names prerequisites (read preview_post and get_formatting_capabilities first) and routes image-only additions to attach_media_to_draft, which is genuine when-to-use guidance. It stops short of saying when not to use it (e.g. versus update_post or create_post_draft), so it is clear context but incomplete exclusions.

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