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

Annotations declare destructiveHint=true and idempotentHint=true, but the description supplies the reasoning behind them: a partial list is rejected atomically and 'the old order stays', which tells the agent the failure mode is safe and non-partial. It also mandates an approval step before invocation, which is exactly the human-in-the-loop guidance a destructive-flagged tool needs. Adds genuine context beyond the annotation set rather than restating it.

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?

Three tight sentences, each earning its place: what it does, the prerequisite plus failure mode, and the sibling boundary plus approval requirement. The core action is front-loaded and no sentence is filler.

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?

There is no output schema, yet the description implies the resulting order is surfaced ('Show the new order'), covering the return behavior an agent needs. For a two-parameter, non-nested mutation tool, everything required to invoke it correctly — prerequisite call, completeness constraint, failure semantics, and approval gate — is present.

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%, so both parameters are already documented, making 3 the floor. The description still adds non-obvious semantics: orderedShortIds must be exhaustive ('must contain every transfer number') and the ordering direction is 'top first', reinforcing that a partial list fails validation rather than appending.

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?

States a specific verb and resource ('Set the priority order of all of a receptionist's transfer numbers') and immediately defines what the order means operationally ('the order the receptionist tries them when transferring a caller'). It also names the sibling it is not (transfer_numbers_update) and the sibling it depends on (transfer_numbers_list), so an agent can distinguish it without opening any schema.

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?

Explicit prerequisites ('Call transfer_numbers_list first'), an explicit alternative for a different need ('to edit a number or its rules use transfer_numbers_update'), and an explicit process constraint ('Show the new order and get explicit approval before calling'). Both when-to-use and when-not-to-use are covered.

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