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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by disclosing the confirm:true preview contract, last-admin protection on set_role and remove, no-self-removal, no manager loops/self-reporting, records surviving removal with paid seat count following, best-effort invite email with `email_sent`, and admin-only access. These are exactly the mutation risks an agent needs before calling.

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?

Front-loaded with the purpose before the action-by-action breakdown, and most sentences carry distinct behavioral detail. It is dense and repeats the confirm requirement three times ('Every action but list and revoke_invite needs confirm:true' plus the closing 'Every invite and change to a person asks for confirm:true'), which is mild redundancy in an otherwise efficient structure.

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?

An output schema exists, so return values need not be explained, yet the description even lists the list fields. For a 7-parameter, 7-action admin tool, the when/when-not, confirm contract, and per-action constraints are all present — nothing an agent needs to call it correctly 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%, so the baseline is 3, but the description adds meaning beyond the schema: it maps which actions require confirm, explains that a preview without confirm names the person and exact change, and clarifies role defaults and null-clearing for manager_id. This cross-action semantics isn't fully captured in the per-field schema descriptions.

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+resource ('Administer who is in the workspace') and then enumerates all seven actions (list, invite, resend_invite, revoke_invite, set_role, set_manager, remove) with their exact effects. An agent can distinguish this from sibling admin tools like manage_company_billing or manage_approvals 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?

The 'When to use' paragraph explicitly covers seeing members, inviting/re-inviting, withdrawing invites, changing roles/reporting lines, and removing — all 'from the conversation instead of Settings → People.' It also states a clear when-not: leaving or switching your OWN workspace stays in the browser because the connection is bound to one membership.

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