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

Annotations only declare destructiveHint=true and idempotentHint=true; the description clarifies the mechanism by stating that required fields and the default selection are overwritten while addressLine2/administrativeArea/postalCode are retained when omitted. That merge/overwrite split, especially the warning that the default flag is overwritten, is real behavioral content not conveyed by the annotations. Auth requirements and error behavior remain undisclosed.

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 sentences, purpose first, then the destructive/merge behavior. No filler and nothing redundant with the schema or annotations.

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 mutation tool with an annotation-provided safety profile and no output schema, the description covers the most consequential detail an agent needs (which values survive omission and that the default selection is clobbered). Remaining gaps are authorization requirements and failure modes, which are secondary.

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 0% across 11 parameters, so the description must carry the load. It does explain the crucial overwrite-vs-retain split and names the optional 'address line, area, and postal code' fields, but it never addresses addressId semantics, countryCode format, phoneNumber constraints, or the individual required fields.

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 ('Update one saved delivery address') and scopes it to a single record, which distinguishes it from the list/delete siblings in practice. It never explicitly names customer_address_create or customer_address_delete as alternatives, so differentiation comes mostly from the verb.

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 merge semantics imply this is a partial-update tool for an existing address, which indirectly signals when to use it, but there is no explicit guidance on when to use it versus customer_address_create (new address) or customer_address_delete (removal). Usage is inferred, not stated.

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