List API keys

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

Annotations already declare readOnly/destructive-free/idempotent, and the description adds substantive context beyond them: the admin-scope requirement, the guarantee that plaintext secrets are never returned, the cascade rule that revoking a key revokes every key minted below it, and the caveat that last_used_surface is derived from a caller-controlled User-Agent header and is 'a hint, not proof of identity'. That last point is exactly the kind of trust caveat an agent needs and cannot get from annotations.

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?

Front-loaded and dense: the auth requirement and the no-plaintext guarantee come first. The long middle sentence carries heavy parentheticals (created_by_key_id, last_used_surface) that are informative but make the structure slightly harder to scan than a shorter enumeration would.

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?

There is no output schema, so the description must document the return shape, and it does: prefix, scope enum values, created_by_key_id with its cascade semantics, last_used_at, and last_used_surface with its source and trust caveat. Combined with the auth prerequisite and secret-redaction guarantee, nothing material is left out.

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?

With zero parameters and 100% schema coverage, the baseline is 4. The description does not need to explain inputs, and instead spends its space on return-field semantics, which is appropriate 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?

States a specific verb and resource ('Lists the project's API keys') and immediately narrows scope with 'without plaintext values', which cleanly separates it from create_api_key, revoke_api_key and regenerate_api_key among the siblings. An agent can identify the operation 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?

It gives a concrete precondition ('Requires the admin scope or higher'), which tells the agent whether it is even eligible to call the tool. There is no explicit when-not-to-use or named alternative, but the list-only nature and the permission gate make the usage context clear.

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