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

Goes well beyond the destructiveHint annotation: it discloses immediate effect ('stops working at once'), the self-destruction risk ('including this connection if it is the one in use'), and that omitting confirm yields a preview rather than a mutation. These are exactly the behavioral traits an agent needs before an irreversible action.

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 action and its two targets, then layers the destructive consequence, the confirm gate, and the token-creation note. Every sentence carries weight, though the confirm behavior is restated from the schema description.

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?

Without an output schema or rich annotations, the description carries the burden well by covering effects, the preview/confirm mechanism, and the self-revocation caveat. The main omission is the relationship/format of the two ID parameters.

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 33% (only confirm is documented), so the description must compensate. It does clarify that apiTokenId targets an API token and appClientId targets a connected app, but it gives no format, sourcing, or mutual-exclusivity guidance for these two IDs, leaving the gap only partly closed.

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 (revokes/disconnects) and the exact resources involved (API token via apiTokenId, connected app via appClientId). No sibling tool overlaps with credential/app revocation, so it is clearly distinguishable.

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?

Explains the two revocation modes and the confirm:true requirement, and the closing line that new tokens are only created in Settings steers the agent away from misusing this for creation. It does not explicitly name an alternative tool, but no sibling competes for this job.

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