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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: irreversibility, the exact two-step confirmation protocol, token expiry, the authorization requirement (owners only), and the guard rails against self-removal and primary-owner removal. It also discloses what the confirmation-less call actually returns, which no annotation conveys. No contradiction with 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?

Front-loads the danger ('DESTRUCTIVE and cannot be undone') ahead of the procedure, then flows from effect, to protocol, to permissions. Dense but every sentence carries a distinct, load-bearing fact with no 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?

With no output schema, the description compensates by describing what the first call returns (who would be removed plus a confirmation) and how that value is reused. Authorization, irreversibility, expiry and edge cases are all covered, leaving nothing an agent needs before calling.

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 description coverage is 100%, so the baseline is 3, but the description adds real semantics for the confirmation parameter that the schema only gestures at: it is omitted on the first call and is the exact string returned by that call, valid for 10 minutes. It also frames email as identifying the target person's membership/invitation state.

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 destructive verb and resource ('removes a person from the company') and immediately differentiates outcomes the sibling list does not cover: a joined member loses access to the company and its signature, while a pending invitation is withdrawn. An agent can distinguish it from add_member, list_members and update_member_field without reading either 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?

Explicitly defines the when: call first without confirmation to obtain a preview, show it to the person, then call again only after they approve. It also states prerequisites and exclusions up front — company owners only, nobody can remove themselves or the primary owner — and gives the 10-minute expiry as a usage constraint.

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