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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context: saving with an id overwrites a saved address, addresses are only stored after user consent, and 'The sender name is always the name of the account holder.' It still doesn't say what happens to fields omitted during an update, which matters for a destructive-hinted mutation.

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 trigger sentence is front-loaded and the rest is short and dense. The trailing sentence about only the user changing the name on the account page is user-interface trivia that competes with the operational guidance for attention.

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 an output schema present and full schema coverage, the description covers the essentials: purpose, consent gating, add-versus-overwrite semantics, and the account-name override. Only the effect of a partial overwrite of an existing address is left unexplained for a nested three-parameter mutation tool.

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. The description explains the add-versus-change meaning of sender_address_id and the name-is-account-holder rule, but both points are already spelled out in the schema property descriptions, so added value over structured data is marginal.

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 plus the two modes: 'Adds a sender address to the account, or changes a saved address (with sender_address_id)'. The add-versus-change split also separates it from delete_address and get_account in the sibling list.

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?

Opens with an explicit trigger ('Use this when the user gives their postal address for letters, or wants to change a saved sender address') and adds a consent precondition: 'Save an address only after the user gave it or agreed to it.' It routes the agent to get_account to obtain a sender_address_id, but never names delete_address as the tool to use for removal.

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