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

Goes well beyond the destructiveHint=true annotation: it states the old key stops working immediately, that the new key carries replaced_key_ids for continuity, that the secret is returned ONLY in this response, and warns the secret will be visible in AI conversation context. These are non-obvious, high-impact behaviors an agent must know before calling.

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?

Purpose and irreversible effect are front-loaded, and the 2FA workflow and auth prerequisites are separated into clearly labeled blocks so an agent can scan them. It is longer than average but nearly every clause carries required pre-call information; the secret-visibility warning and replaced_key_ids note are not 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?

Despite having no output schema, the description explains the return payload (new id, new secret, replaced_key_ids) and the one-time nature of the secret, plus auth and 2FA prerequisites. Nothing an agent needs to invoke this destructive, credential-issuing tool 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% with a single self-describing 'id' parameter, so the schema already carries the load. The description still adds operational meaning by noting the caller should use the newly returned id from now on, which clarifies the id's lifecycle rather than just its type.

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 ('Regenerate an API key') and immediately defines what that means (new id and secret, same name/environment/scopes/project), which distinguishes it from create_api_key and revoke_api_key in the sibling list. An agent can tell what it does without opening the 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 states the precondition that this operation requires 2FA and lays out a numbered flow (start_2fa → user verifies → poll get_2fa_status → then call this tool), naming the exact sibling tools to use. It also states the ACCESS prerequisite and how to satisfy it, leaving no routing ambiguity.

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