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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is known. The description adds nothing about what destruction means here — whether omitted media/targets are replaced or merged, whether changes are reversible, or what errors occur after the post has already run. For a destructive mutation that is a real gap.

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?

A single seven-word sentence with zero filler and the scope qualifier front-loaded, but it is sized for a trivial tool while this one has deeply nested targets/media options. Conciseness is achieved by omission rather than by efficiency.

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?

The tool takes seven parameters including nested media and per-target platform_options, is destructive and open-world, and the description is one sentence. An agent could not call this correctly without reading the entire schema, and even then the replacement-vs-merge semantics of an update remain undefined.

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?

Top-level schema description coverage is 0% for seven parameters (id, media, content, targets, publish_at, external_id, idempotency_key), and the description mentions none of them. It implies an existing post is identified, but says nothing about partial-update semantics, publish_at format/constraints, or idempotency_key behavior.

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?

"Updates a scheduled post" states a specific verb and resource, and "before it runs" scopes it to pre-publication posts, which implicitly separates it from update_draft and publish_post. It stops short of naming any sibling, so the distinction has to be inferred.

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 only guidance is the temporal qualifier "before it runs" — there is no statement of when to prefer this over update_draft, cancel_post, or delete, no prerequisites (does it need the post to still be scheduled?), and no exclusions. An agent must guess at the routing.

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