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

Beyond the annotations' destructiveHint/idempotentHint, it discloses that the effect is reversible via the Bin for 30 days and enumerates the specific refusal codes publishing_now and stuck_publishing for edge states. This is exactly the kind of consequence and failure-mode information an agent needs before a destructive call.

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?

Five short sentences ordered by importance: what happens, reversibility window, hard exclusions, error codes, confirmation requirement. No filler and no repetition of the title or annotation data.

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 single-parameter destructive tool with no output schema, the description covers effect semantics, recovery path, refusal conditions, and the human-confirmation gate. An agent has everything needed to decide and to interpret the likely outcomes.

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?

With a single parameter at 100% schema description coverage, the schema already defines post_id fully. The description adds only an implicit constraint that the id must refer to a queued, unpublished post, which is useful context but not parameter-level detail beyond the schema. Baseline 3 applies.

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?

"Remove a post from the queue" gives a specific verb and resource, and the follow-on sentences immediately bound the scope: soft delete, only unpublished queued posts. An agent can tell this apart from sprkly_update_scheduled_post or sprkly_list_scheduled_posts without opening any schema.

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?

It states clear negative conditions (already-published posts cannot be deleted this way; in-flight posts are refused) and a mandatory pre-call step ("Always confirm with the user before calling"). What is missing is an explicit pointer to the alternative path for published posts, so the agent must infer what to do instead.

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