discord_delete_role

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It mentions the confirmation requirement, but it does not state that deleting a role is permanent and destructive, that associated permissions are removed, or that the audit log may record the reason. This is a significant gap for a delete operation.

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 only two sentences and front-loads the core operation. Every sentence contributes useful information, with no filler or repetition.

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 tool with no annotations and low schema description coverage, the description is too thin. It does not address prerequisites, deletion consequences, guild context, or when this action is appropriate versus the many role-related siblings.

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 only clarifies the confirm parameter condition. It does not explain the role of guild_id, role_id, or reason, leaving the agent to infer their meaning solely from property names and types.

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 states a clear action ('Delete a role') and resource. However, it does not distinguish itself from the similar sibling discord_remove_role, which could be confused as an alternative way to 'remove' a role vs deleting it entirely.

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 gives one important invocation condition: 'Requires confirm=true when confirmation is enabled.' It does not, however, explain when an agent should choose this tool over alternatives like discord_remove_role or discord_edit_role, so context is incomplete.

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