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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, but the description adds genuinely new behavior: it may fetch external image URLs during rendering, it is safe to retry 'unavailable' screenshots without recreating the draft, and it never publishes. The note to follow display.instruction and check screenshot.truncated is operational guidance not derivable from annotations, and nothing contradicts them.

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?

Front-loaded with the trigger and then moves through returns, alternative, and operational caveats in a logical order. Dense with several clauses packed into a short block, but each sentence carries distinct information; only the display.instruction/screenshot.truncated clause feels slightly terse for its importance.

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?

An output schema exists, so return values need not be fully described, yet the description nonetheless names the key return artifacts (documentJson/richHtml, JPEG) and preview-link creation. Combined with the retry/no-recreate guidance and external-fetch disclosure, an agent has everything needed to call this complex, open-world tool correctly.

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 0% for the single draftId parameter, but the description compensates by naming its provenance ('Find draftId with search_post_drafts'), which is exactly what the schema lacks. It does not describe the ID's format or type, keeping it below a 5, but the sourcing hint is materially useful.

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 and resource (preview a draft post), and immediately enumerates the three outputs it produces: screenshot, public browser preview, and validation warnings. It explicitly distinguishes itself from the sibling show_post_card for in-chat cards, so an agent can route without opening 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 an explicit trigger condition (requesting screenshot/public preview/validation warnings), tells the agent how to obtain the required draftId (search_post_drafts), and names the alternative (show_post_card) with its distinct purpose. When-not guidance is also present via 'Never publishes.'

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