Retry or resume a post

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

The supplied annotations are thin: readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description goes well beyond them by saying if a publish may already have gone through, it checks Instagram first and never publishes twice, which is a real guarantee against duplicate posts caused by an external side effect. It also discloses that cancelled or missed jobs need re-confirmation, which explains when the tool will refuse to act.

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?

The description puts the recovery scenarios first and the safety behavior second. The sentences are dense and specific, and each one carries information, though the opening enumeration is long enough to require careful reading.

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?

No output schema exists, yet the description says nothing about what a successful call returns, such as a new status or a job state. For a tool with a mutate-and-wait model, that leaves a real gap. Given the tool's complexity, permissions needs, and no annotations covering the side-effect profile, the description still does most of the essential work.

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 only 33%, with only confirmation_token documented. The description ties the confirmation step to cancelled and missed posts, which helps with that parameter, but it says nothing about job_id or wait_seconds; the range of 0–110 seconds in particular is unexplained, so the agent cannot tell whether the tool blocks until the publish completes or returns immediately.

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 description does not stop at a vague 'retry'; it reads as a specific set of recovery actions on one named resource (an existing publish job), with a concrete verb for each state: retry a failed post, continue one paused on an expired sign-in, re-check one waiting for the publishing limit, restore a cancelled one, or publish a missed one right now. This scope makes it unmistakably different from siblings such as publish_photo or publish_reel, which create a new publish, and from get_publish_status, which only reads status.

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?

Each scenario that calls for this tool is spelled out, and one prerequisite is stated clearly: cancelled and missed posts need the user's confirmation again. What is missing is an explicit correction or negative case, such as telling the agent not to call this for a post that has never been created, or to use publish_photo when restarting from scratch.

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