Edit account

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is known without the description. The description's field list implies the mutation surface but adds no behavioral context beyond it — it never says whether omitted fields are left unchanged, whether archiving removes the account from reports, or whether the call is immediately persisted.

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?

Two compact sentences: the operation list is front-loaded and the disambiguation follows immediately. No filler, no restatement of the name or title.

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 destructive, idempotent mutation tool with no output schema and six parameters, the description covers the operation set and routes the balance-correction case correctly. The remaining gap is that it doesn't state whether unspecified fields remain untouched or what permissions are required, but annotations and the operation list make it callable as-is.

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 coverage is only 17% (just 'account'), so the description has to carry the parameters, and it largely does: rename→title, archive/unarchive→archived, include/exclude in balance→in_balance, mark as savings→savings, change credit limit→credit_limit. It stops short of saying these are the only optional fields or that they can be combined in a single call, but the mapping is a genuine gain over bare schema names.

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 names the resource and enumerates the concrete mutations it performs (rename, archive/unarchive, include/exclude from balance, mark as savings, change credit limit), so an agent knows exactly which field-level edits are in scope. It also explicitly contrasts itself with adjust_account_balance, which handles balance correction — a sibling it would otherwise be confused with.

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 closing sentence gives an explicit alternative with its triggering condition: use adjust_account_balance to fix a balance rather than this tool. That is real when-to-use guidance, though there is no broader statement of exclusions or prerequisites (e.g. required permissions, whether multiple fields can be combined in one call).

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