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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the tool is known to be a write operation. The description adds valuable context beyond annotations: priority is tenant-wide and flat (continuous), array index 0 maps to priority 1, and activationGroup is unaffected. This explains exactly what changes and what does not, which is more transparent than just the 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 description is two sentences, front-loaded with the action and key constraints. Every sentence adds essential information: the reordering action, the priority model, and the exclusion of activationGroup. There is no filler or redundancy, making it highly concise and well-structured.

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?

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description covers the core requirements: what the tool does, how priority ordering works, and what is not affected. It does not explicitly state whether the groupIds array must contain all groups or if partial reordering is allowed, but this may be inferred from the continuous priority model. Overall, it is sufficiently complete for an agent to call the tool correctly.

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 coverage is 100% because the sole parameter groupIds has a description: 'Group IDs in desired priority order (index 0 = priority 1)'. The description adds further meaning by clarifying that priority is continuous and tenant-wide, and that activationGroup is not affected. This goes beyond the schema's basic ordering semantics, providing useful context for constructing the array correctly.

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 the action: 'Reorder policy groups by priority.' It specifies the resource (policy groups), the operation (reorder), and the key constraint (priority is tenant-wide and flat). It also distinguishes itself from sibling tools like lexq_groups_update by clarifying that only priority changes and activationGroup is unaffected. This is specific and unambiguous.

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 policy groups by priority. It explicitly states what it does not affect (activationGroup), which helps set expectations. However, it does not explicitly name alternative tools or conditions for choosing this over others, though the scope is so narrow that an agent can infer the appropriate usage.

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