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

Goes beyond annotations by disclosing that the operation never publishes, that it works against an expected revision (optimistic concurrency), and that the idempotency key must be reused on retries. The annotations already declare destructive=true and idempotent=true, but the description adds the retry semantics and its non-publishing nature, which is meaningful extra context.

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?

Three short, front-loaded sentences with no filler; the core action comes first and the constraints follow. Every sentence earns its place.

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 explained, and the safety profile is covered by annotations. But for a tool with eight parameters including a deeply nested settings object and zero schema coverage, the description is too thin to be complete.

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 parameter meaning, yet it only gestures at 'revision' and 'idempotencyKey'. The other six parameters, including the large nested 'settings' object, 'content', 'connectionId' and the media asset fields, are left entirely 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?

States a specific verb and resource ('Edit an editable post ... save it as a draft') with a clear scope qualifier ('at its expected revision'). It is distinguishable from publishing tools via 'Never publishes', but it names no sibling (e.g. create_draft) so the agent cannot route between the two with certainty from the text alone.

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?

Implies usage through 'editable post' and 'Never publishes', which suggests this is the draft-editing path rather than the publishing path. However there is no explicit when-to-use vs when-not guidance and no named alternative among the many sibling tools (create_draft, schedule_post, update_campaign_post).

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