Cancel scheduled post

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description goes beyond them by disclosing the concrete side effect ("Deletes its staged media copies") and the approval posture ("Local only; no approval needed"). It leaves the failure mode unspecified: with idempotentHint=false, an agent cannot tell from the description whether re-cancelling an already-cancelled job errors or silently succeeds.

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?

Four short sentences, front-loaded with the action and its precondition, then side effects, then the safety/approval note. Nothing repeats the schema or annotations verbatim and nothing is padding.

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 destructive, non-idempotent mutation with no output schema, the essential pieces are covered (precondition, side effect, confirm requirement, no approval gate). The gaps are operational: where job_id comes from and what the agent should expect on error or repeat invocation, both of which matter for correct invocation in a 40+ tool surface.

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%, so the description carries the burden, and it only clarifies one of two parameters — "Requires confirm: true" explains the intent behind the const boolean. job_id gets no semantic help at all: no statement of where to obtain the id (e.g., from instagram_list_scheduled or instagram_get_publish_status) or its format, leaving the agent to guess its provenance.

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 ("Cancel a scheduled publish job") plus a scope qualifier ("has not started (status \"scheduled\")") that separates it from cancelling anything already running. It does not name a sibling tool, so an agent must infer from the tool list that this is the only cancellation entry point, but the resource is unambiguous.

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 a clear applicability precondition (job must be in "scheduled" status and not started) and answers the biggest workflow question for a destructive tool with "Local only; no approval needed." It stops short of stating what to do instead when the job has already started or completed — no alternative tool is named for that case.

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