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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real value beyond them: an authorization prerequisite, the fact that secrets are encrypted and never returned (so the value cannot be read back later), and per-plan quotas (2/25/100). It omits duplicate-name behavior and any confirmation of idempotency, which matters for a write tool.

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 tight sentences with no filler: purpose and scope first, then the credential/alternative-input mechanics, then the encryption and quota facts. Every sentence carries information an agent needs to call the tool correctly.

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 7-parameter mutation with no output schema, the description covers purpose, auth, input alternatives, secret handling, and quotas. Remaining gaps are modest: no statement of return value (e.g., a generated id) and no guidance on what happens when a name already exists.

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 57% schema coverage, the description compensates by stating the one-of relationship among uri, secret, and imageBase64, the accepted format for each (otpauth://totp, Base32, PNG/JPEG QR), and concrete image limits (1 MiB, one million pixels) that are absent from the schema. digits, period, and algorithm are left to the schema's enums and bounds, and no defaults are stated.

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 ('Store a TOTP authenticator') plus a scoping condition ('for an account your human asked you to create or operate'). An agent can distinguish it from get_totp_code, list_authenticators, and delete_authenticator without opening any schema, though no sibling is named explicitly.

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?

Gives a clear precondition ('Requires an approved workspace key') and a scope restriction limiting use to accounts the human requested. It also explains that exactly one of uri/secret/imageBase64 should be supplied. It stops short of explicit when-not guidance or naming list_authenticators/get_totp_code as follow-ups.

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