channels_delete

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety bar is partially met. The description goes beyond them by disclosing cascade behavior ("everything that hangs off it") and external side effects ("reaches other people on the platform, deletes, or redirects data"). The phrasing of that side-effect clause is ambiguous about what actually happens on the wire.

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 cascade statement is front-loaded and useful, and the endpoint metadata is compressed. But the second sentence is subject-less and grammatically muddled ("Reaches other people on the platform, deletes, or redirects data"), making it cost more attention than it returns.

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 one-parameter destructive tool, the description plus annotations cover the essentials: cascading scope, external effects, and a confirmation requirement. There is no output schema, and the description doesn't address error/partial-failure behavior on a cascade, which is the main residual gap.

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 description coverage is 0% and the description says nothing about the single `id` parameter — not which channel identifier it is, whether aliases are accepted, or what format is required. The schema's example string is the only clue, so the description fails to compensate for the coverage gap.

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 gives a specific verb and resource ("Delete a channel") and adds scope with "everything that hangs off it," which distinguishes it from a single-object delete. It does not, however, differentiate from sibling lifecycle tools like channels_terminate or channels_unload, which is a plausible confusion set.

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 does give a workflow directive — get explicit user confirmation before executing — which is valuable for a destructive tool. But it names no alternatives and no conditions distinguishing this from channels_terminate/channels_unload, so the agent must infer when deletion is the right call.

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