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

Annotations already flag destructiveHint=true, yet the description goes far beyond them, spelling out exactly what is destroyed (answers, uploaded files, task progress, notifications) and that the action is irreversible. It also discloses non-obvious side effects: tickets are retained for managers, the tester is not notified, and workspace membership is untouched. Token single-use and expiry behavior is an additional useful disclosure.

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 irreversible consequence, then scope exclusions, then the two-step procedure. Sentences are dense but every one carries distinct information; nothing is 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?

For a destructive mutation with no output schema, the description covers what the first call returns (preview plus token), what the second call does, and all side effects an agent must communicate to the user. Nothing needed to invoke 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 workflow-level meaning to confirmationToken that a bare schema cannot convey: the preview-then-execute cycle, reusing the SAME arguments, and single-use short-lived tokens. The userId and productId meanings are largely restated from the schema, limiting it to a 4 rather than 5.

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 opens with a specific verb and resource, 'PERMANENTLY removes a tester from this beta project', and immediately enumerates the scope of the deletion. It distinguishes itself from siblings such as removeBetaManager by stating the tester remains a workspace member and stays in other beta projects.

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 gives explicit operational guidance: call without confirmationToken first, show the preview to the user, and only re-call with the same arguments after explicit approval. The only gap is that it does not name a sibling alternative for reversible or lesser removals, but the described prerequisites (get user id from getBetaTesters, project id from listProducts) are clear.

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