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

With no annotations provided, the description carries the full disclosure burden, and it does well: it states the operation is a soft-delete, irreversible ('can never authenticate again'), preserves metadata, and requires admin-level auth. It does not mention idempotency or what happens to existing sessions/tokens, which keeps it slightly short of a 5.

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?

Three terse sentences deliver the action, the critical identifier nuance, the side-effect model, and the auth requirement. Nothing is wasted, and the most decision-relevant fact (revoke by id) is front-loaded.

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 mutating tool with no output schema and no annotations, the description covers the essential context: what is revoked, how it is identified, what the long-term effect is, and what auth is needed. Missing are error cases and idempotency, but an agent can safely invoke this tool from the given information.

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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds the 'admin' requirement for owner_key and re-emphasizes that id is not the raw key material, but these largely paraphrase what the schema already states. This matches the baseline for full coverage.

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 names a specific verb and resource ('Revoke an access_key by its id') and clarifies the identifier type ('not the raw ak_... key material'), which sharply distinguishes the action from create/update/list siblings. It does not explicitly name sibling tools, but the action is clear and unambiguous.

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?

The description states a prerequisite ('Requires an admin owner_key') and hints at the soft-delete trade-off (metadata stays queryable), which implies when to choose this over a hard delete. However, it never explicitly states when to use this tool versus alternatives, nor does it name any sibling like update_access_key or list_access_keys.

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