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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real substance beyond them: the revoke is a soft-revoke, ownership is enforced server-side with a deliberate 404 (not 403), and parameter handling differs by caller type (agent connection vs API key). It also discloses the alternate 204 outcome that voids an unredeemed CI key claim, which an agent could not infer from annotations or schema.

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 is front-loaded in the first two sentences, but the remainder is a dense single block with multiply nested clauses ('a keyId that does not belong to the calling key's project (or, for an org key, its org)'), which is hard to scan. The closing sentence about post-redemption revocation is convoluted and packs several cases into one run-on statement.

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 mutation tool with no output schema, it covers permissions, ownership scoping, both success paths (revoke vs claim void), and error behavior, which is close to complete. The remaining gap is the meaning and consequence of 'soft-revoke' — whether the key can be restored or merely stops authenticating is left unstated, which matters for a destructive operation.

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 all three parameters are already documented in the input schema, making 3 the baseline. The description does add value by clarifying that projectId/orgId are ignored entirely for API-key callers and that exactly one must be supplied for agent connections, but the keyId provenance it cites duplicates the schema note.

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 opening states a specific verb and resource ('Revoke an API key', 'Soft-revoke a key by id') plus the required permission level, so the operation is unambiguous. It never explicitly positions itself against siblings such as list_api_keys (the source of keyId) or create_ci_key_claim, though the claim paragraph does describe the boundary case where revoking voids a claim.

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 strong preconditions and context: admin permission, owner scoping, and the fact that a non-owned keyId silently revokes nothing and returns a flat 404. What is missing is explicit when-not guidance — it never says to use a different tool (e.g. list_api_keys) to obtain a keyId or when a hard delete/different path applies.

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