Cancel / delete a post

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

Annotations already declare destructiveHint=true, so the description is not responsible for that. It adds useful context: the post must belong to the active org and the operation is safe for a draft-only token. However, the CAPABILITY line claiming it 'creates content' is misleading for a delete tool and harms transparency, though it doesn't contradict annotations.

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 first sentence is front-loaded and effective, but the CAPABILITY sentence is confusing and doesn't serve a clear purpose in the context of deletion. This makes the description less concise than it could be, though it is still short.

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 tool with one parameter and clear annotations, the description is mostly adequate. It covers the core action and org constraint, but it doesn't clarify whether published posts can also be deleted or what happens if the post doesn't exist. The confusing CAPABILITY sentence also creates a gap in understanding the tool's exact scope.

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?

The input schema has 100% coverage for the sole 'id' parameter (described as 'Post id'), so the description doesn't need to explain it. The description adds no extra meaning about the parameter, so the baseline score of 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?

The description begins with 'Delete a post (e.g. to cancel a scheduled one)', which clearly identifies the verb and resource and distinguishes it from scheduling/publishing tools. However, the later CAPABILITY line about 'creates content' is confusing and slightly obscures the delete purpose.

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 provides a concrete use case ('cancel a scheduled one') and a key constraint ('Must belong to the active org'), which gives clear context. But it doesn't explicitly mention when not to use it or name alternatives like reject_draft or unpublish.

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