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

Annotations only say it is destructive, non-read-only, idempotent, and closed-world; the description goes far beyond them by disclosing that new permissions apply immediately, personal exceptions persist, you cannot change your own role, the last admin cannot be moved, tokens expire and are single-use, and replays return applied with replayed:true rather than double-acting. It also flags CRM field values as untrusted content, which is real operational context not carried by any structured field.

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 purpose is front-loaded and the rest is a stepwise protocol where each sentence carries a distinct rule (approval, staleness, replay, expiry). It is dense but not padded; a small amount of overlap between the preview paragraph and the token paragraph keeps it slightly below maximal conciseness.

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, so the description must carry the return shape, and it does: the preview returns a summary, changes, warnings, and a confirmationToken, and the replay returns status applied with replayed:true and change ids. Combined with the preconditions and token lifecycle, an agent has everything needed to drive this multi-step mutation 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%, so memberId, roleId, and workspaceId are already well documented in the schema, and the description correctly leaves them alone. The description does add genuine meaning for confirmationToken (omit to preview, send only after explicit approval of the shown preview), but since the schema already describes both parameters thoroughly, this stays at 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?

Opens with a specific verb+resource: 'Moves a member to another role.' It is clearly distinguished from adjacent siblings like update_role, set_member_access_overrides, and reset_member_overrides because it acts on a member's role assignment and explicitly notes that personal exceptions stay in place. An agent can pick 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?

It prescribes the exact operating procedure: call first WITHOUT confirmationToken to preview, show the summary and every warning in your own words, stop and get explicit approval in the same turn, then call again with identical arguments plus the token. It also covers the re-preview triggers (user changes anything, stale_revision) and states what does not count as approval, leaving essentially nothing to inference.

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