create_api_key

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

The description adds substantial behavioral context beyond the annotations: the generated key is displayed only once, prefixes are semantically equivalent, roles have anti-escalation rules, 'owner' is unavailable for API keys, and omitted rate_limit_per_minute defaults to the tenant plan maximum. This is valuable operational information that the sparse annotations do not convey.

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?

The description is well-structured with front-loaded purpose and security-critical warnings. Every sentence contributes operational knowledge, from the one-time display warning to prefix semantics, role restrictions, and rate-limiting defaults. There is no filler or redundant restating of the input schema.

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, this description covers return behavior, secret handling, role constraints, prefix semantics, and default rate-limit behavior. An agent has enough to invoke the tool correctly and to know what to expect, including the critical 'save immediately' warning. No essential call-time information is missing.

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 baseline is 3, but the description adds meaningful semantics: default behavior when rate_limit_per_minute is omitted, anti-escalation constraints on role, role capability details, and the note that 'owner' is not a valid API key role. This goes beyond the schema descriptions without needing to repeat every parameter.

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 opens with 'Cria uma nova API Key para o tenant', which is a specific verb plus resource. It also says the full key is returned and visible only once, immediately making the tool's purpose distinct from sibling tools like list_api_keys, get_api_key, update_api_key, and delete_api_key.

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 phrase 'Cria uma nova API Key' clearly signals when to use this tool, and sibling names make the alternatives for listing, retrieving, updating, and deleting unambiguous. It does not explicitly say 'use update_api_key to modify' or 'use list_api_keys to view', but the context is clear and no exclusions are needed.

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