Reorder roles

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

The description adds useful context about hierarchy mechanics ('Higher positions sit higher in the list and outrank lower ones') beyond the annotations' readOnlyHint:false and destructiveHint:false. However, it does not disclose potential ambiguities, such as how multiple moves are applied (sequentially vs simultaneously) or what happens with conflicting positions. This leaves some behavioral gaps unaddressed.

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 two concise sentences with no redundant phrasing. It front-loads the primary action and quickly adds a semantic clarification, making it efficient and easy to parse.

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 mutation tool with no output schema, the description adequately covers the core purpose and key semantics. It explains the ordering logic and the 'one call' batching. It does not describe return values or error conditions, but given the simplicity of the tool and the annotations providing safety hints, this is acceptable.

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 50%: 'guild' is described in the schema, and the nested 'role' and 'position' fields are also described, but the 'moves' array itself lacks a description. The description's statement about higher positions adds meaning to 'position', but it does not compensate fully for the missing top-level 'moves' description or explain the array structure beyond what the schema already provides.

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 explicitly states 'Move roles to new hierarchy positions in one call', which is a specific verb ('move') plus resource ('roles') and scope ('hierarchy positions'). This clearly distinguishes it from sibling tools like update_role (editing role settings) or reorder_channels (reordering channels instead of roles).

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 context for when to use the tool: when reordering roles in a server hierarchy. It says 'in one call', implying batch efficiency, but does not explicitly contrast with alternatives or mention exclusions like the need for specific permissions. No when-not-to-use guidance is given, so it stops short of the highest bar.

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