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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses that the new token is visible only ONCE, that the old token dies immediately, and that the caller must update its config header. These are exactly the irreversible, easy-to-miss consequences an agent needs before invoking.

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?

Two dense sentences, front-loaded with the destructive consequence before the operational follow-up. Nothing is padded and no sentence is redundant.

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 correctly explains the return value (token shown once), the side effect (old token revoked), and the required confirmation flag. An agent has everything needed to call this safely.

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 50%, but the token parameter already carries a thorough warning (LAST RESORT, prefer the Authorization header, logging risk) in the schema itself. The description only echoes the confirm requirement, adding no syntax or meaning beyond the structured fields.

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 and resource ('Replace your agent token') and immediately scopes the effect: the new token is returned once and the old one is invalidated. No sibling tool overlaps with token rotation, so the agent can select it unambiguously.

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?

Gives operational preconditions ('confirm must be true', update your MCP config header afterwards) but never states when an agent should rotate versus not rotate, nor names any alternative. Usage is implied by the name rather than explained.

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