Delete a category

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

The annotations already indicate destructive=true and readOnly=false, but the description adds substantial behavioral context beyond these flags. It discloses that there is no trash or undo, that articles remain published with a null category_id, and that a secret key with taxonomy:write scope is required. It also explains the confirm parameter's role in preventing accidental deletion, which is critical behavioral information.

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 is concise yet comprehensive. Every sentence contributes unique information: the action, the effect on articles, the permanence, the confirmation requirement, and the permission scope. There is no redundant or filler text, and the most critical warning (permanent, no undo) is placed prominently.

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?

The description is exceptionally complete for a destructive tool given its annotations and schema. It covers all necessary context: impact on related content, permanence, confirmation flow, and security requirements. Although there is no output schema, the description explains the behavior when called without confirmation, which provides sufficient return-value context for a delete operation.

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 100% schema_description_coverage, the schema already documents both parameters. The description adds value by explaining that calling without confirm=true returns a description of what would happen and changes nothing, which clarifies the parameter's purpose and the tool's dry-run behavior. This goes beyond the schema alone, justifying a score above the baseline.

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 clearly states 'Delete a category' with a specific verb and resource. It goes beyond a repitition of the title by explaining the distinct impact on articles: they are not deleted, their category_id becomes null, and they remain published. This effectively distinguishes it from similar deletion tools for articles, tags, or authors.

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?

The description provides clear usage context by stating that the action is permanent, requires user confirmation, and that removing a category never removes content. It does not explicitly name alternative tools, but it clearly defines when this tool should be used (final deletion after user agreement) versus a non-destructive operation. The explicit instruction to ask the user before calling is a strong usage guideline.

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