Accounts rotate api key

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

Annotations declare readOnlyHint=false and destructiveHint=false, consistent with a rotate operation, so there is no contradiction. But the description adds nothing beyond the annotations: it does not say whether the prior key is immediately invalidated, whether clients using the old key break, or what credentials the caller must present for such a security-sensitive mutation. For a write tool touching credentials, this is a significant disclosure gap.

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?

A single front-loaded sentence with zero padding, so there is nothing to trim. The problem is under-specification rather than verbosity: the brevity costs the agent information it needs.

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?

A credential-rotating mutation with three opaque, undocumented parameters, no output schema, and only minimal annotations cannot be described in five words. Nothing tells the agent what the call returns (the new key?), whether confirmation is required, or what side effects occur.

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?

Three parameters (form, params, json_body) with 0% schema description coverage and no types or enums, and the description mentions none of them. The schema and the description together leave the agent with no idea what to supply, so the description fails to compensate for the coverage gap.

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 ("rotate the personal API key"), and the word "personal" implicitly distinguishes it from the sibling vaultwarden_organizations_rotate_api_key. However, it never names or contrasts that alternative explicitly, so the agent must infer the scope distinction rather than being told it.

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?

There is no guidance on when to rotate (e.g., key compromise, scheduled rotation), no prerequisites such as authentication or master password confirmation, and no mention of the organization-key alternative. The agent gets no criteria for selecting this tool over its siblings.

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