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

Annotations already disclose destructiveHint=true, openWorldHint=true, and non-idempotent, so the safety profile is covered upstream. The description adds genuinely useful behavior beyond that — the billing boundary ("Never cancels Stripe billing") and the effect of each action — but omits permission requirements, whether revoked/blocked access takes effect immediately, and what a failed action returns.

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?

A single dense sentence with the action list front-loaded and the billing constraint placed at the end as a boundary. It is efficient and telegraphic; the parenthetical "(email, plan?, sendInvite?)" packs per-action parameter hints without waste.

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 9-parameter destructive mutation with no output schema and no annotations covering return behavior, the description is too thin: it never explains the `id` (site id) versus `customerId` distinction, which action consumes `name`, `note`, or `expiresAt`, or what the tool returns on success. An agent could invoke it with a plausible but wrong argument set.

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 only 44%, but the description compensates for the most important gaps by binding parameters to actions: email/plan/sendInvite for add, and customerId-or-email as the member lookup key. It leaves the ambiguous `id` (site id) and `note`/`expiresAt` unexplained, and never states which action requires expiresAt or name, so roughly half the parameters still lack meaning.

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?

The description enumerates the concrete operations (add, grant/revoke/extend a plan, block/unblock, rename) and the lookup keys (customerId or email), so the agent knows exactly what the tool does. It does not reference the closely related siblings (remove_member, invite_site_member, list_members), so differentiation from them is left to inference.

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 shows what each action does and includes a partial when-not clause ("Never cancels Stripe billing"), which implies this is not the tool for deleting a member or managing billing. However, it never says when to prefer remove_member, invite_site_member, or list_members over set_member, leaving routing between these overlapping tools implied rather than stated.

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