create_api_key

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world, so the safety bar is partly covered. The description adds genuinely non-obvious behavior: the secret is shown only once and must be surfaced to the user but not repeated elsewhere, plus the required `api_keys:write` scope. It does not mention that a repeated call creates a second distinct key (relevant given idempotentHint=false) or that the key can later be revoked.

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 short sentences, front-loaded with the one-shot secret warning, zero filler. Every sentence carries actionable information.

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?

With no output schema, the description correctly explains that the response contains a one-time secret, which is the critical return-value fact. However, for a security-sensitive creation tool it leaves the two required parameters unexplained and gives no guidance on scope selection, so an agent could create an over- or under-privileged key.

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 expiresAt is documented (omit/null for no expiry). The description says nothing about `name` (uniqueness, max length) or `scopes` (whether scopes are fixed at creation, whether `admin` subsumes others, whether the creator can grant scopes they lack). With low coverage, the description should have compensated and does not.

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 ('Create an API key') and adds the key lifecycle fact that the secret is returned once. It is distinguishable from siblings like list_api_keys and revoke_api_key by name, but it never explicitly contrasts with rotate_api_key, the nearest ambiguous alternative.

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?

Usage is only implied by the create semantics; there is no statement of when to use this versus rotate_api_key (existing key, new secret) or when not to create a new key. The scope requirement gives a precondition but not a decision rule.

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