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

Annotations already mark this destructive, idempotent and open-world; the description goes well beyond them by explaining that only passed fields mutate, that new values fully replace old ones, that edits are re-validated against per-platform limits, that a human must confirm, and why create-new beats re-sending a failed post. This is exactly the mutation-risk context an agent needs before invoking.

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-loads what the tool changes, then the replace-and-confirm rule in caps, then validation, then the refusal list and alternatives. No sentence is filler; each carries either a rule or a routing decision.

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 7-parameter mutation tool with no output schema, the description covers the preconditions, the non-obvious mutation semantics, human-confirmation needs, and the sibling escape hatches. Nothing an agent needs to invoke this correctly appears to be missing.

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 100%, so the schema carries the parameter detail and baseline 3 would be acceptable. The description still adds cross-parameter reasoning the schema does not: tiktokPrivacy must be chosen by the person, the caption/media replacements are wholesale, and replacePlatformCaptions is only needed in a specific case. That is a modest but real value-add over the schema.

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 (change/edit) and resource (a draft or scheduled post) plus the editable facets: caption, media, TikTok visibility or time, and unscheduling. It also names the sibling tools it is not (cancel_post for delete, schedule_post for create), so an agent can discriminate without reading sibling schemas.

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?

Explicitly declares the refusal conditions that redirect the agent elsewhere: published/publishing posts (edit on the platform), failed posts (create a new one via schedule_post, because re-sending could double-post), and posts in a running hook test. It also states the delete and create alternatives by name.

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