List API keys

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds value by noting that the list includes revoked keys, which is a behavioral trait beyond what annotations convey. This is useful context an agent wouldn't get from the schema or annotations alone.

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?

Single sentence, front-loaded with the core verb+resource, and the 'including revoked keys' clause is relevant additional detail. Zero waste or redundancy.

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 read-only list operation with no output schema and 3 simple params, the description is reasonably complete. The 33% schema coverage means limit and cursor lack documentation, but these are standard pagination params that agents commonly understand. No output schema means the return format is not described, which is a minor gap for a list tool.

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 only 33% (only project_id has a description). The description doesn't cover limit/cursor semantics, which are common pagination params an agent could infer. The project_id parameter's schema description ('list_projects returns valid project ids') already covers the most nuanced parameter, so the description adds minimal additional value here.

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 uses a specific verb+resource ('List API keys') and adds a meaningful scope detail ('including revoked keys'), which distinguishes it functionally. It's clear what the tool does. However, it doesn't distinguish itself from the sibling 'list_project_api_keys', which sounds near-identical in purpose — a missed opportunity for differentiation.

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 notes it operates on 'the authenticated project' and includes revoked keys, which gives some context on scope. It doesn't explicitly state when to use this versus list_project_api_keys or list_personal_tokens, despite these being plausible alternatives. The project_id parameter description helps, but no explicit when/when-not guidance is provided.

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