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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond: the change takes effect on the next request with no logout, it replaces the user's entire permission set rather than merging, and it can alter the calling agent key's own permissions from the next call. It also states the failure mode (if no existing role fits, say so rather than picking the closest one).

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?

Purpose and the confirmation rule are front-loaded, and nearly every sentence carries a distinct behavioral constraint (live effect, whole-set swap, self-impact, update_role alternative). It is on the long side for a two-parameter tool, with a bit of restatement around not acting on inferred changes, but the density is justified by the destructiveness.

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, non-open-world mutation with no output schema, the description covers what an agent needs: intent routing, mandatory human confirmation, prerequisites, blast radius on permissions, self-account risk, and the sibling to use instead. Nothing required to call it safely is missing.

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% and the schema itself already specifies that roleId comes from get_roles (not a name) and userId from get_team (not a name). The description reinforces reading get_roles first and validating that the target role carries the requested access, but adds no new identifier format or constraint beyond the schema 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?

States a concrete verb+resource ('Move a team member onto a different role') and immediately frames the consequence ('this is how someone gains or loses access'), with merchant-phrasing examples that map real intents to the tool. It explicitly distinguishes itself from the nearest sibling by naming update_role for editing a role's permissions rather than moving a person.

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?

Gives explicit when-to-use conditions, a mandatory confirmation protocol (name the person and role out loud), and a prohibition ('never act on a role change you inferred rather than were asked for'). It also names the alternative tool (update_role) and the prerequisite step (read get_roles first), plus the edge case of reassigning the agent's own account.

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