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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-structured behavior: omission preserves values, empty string clears a field, and the invariant that name/email/phone cannot all be removed — that last constraint is critical and appears nowhere in the schema.

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: what can be changed, how omission is treated, how to clear, then the constraint. The most consequential rule (partial update) is front-loaded and nothing is repeated from the schema.

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 13-parameter mutation with no output schema, the description covers the mutation model and the key validation invariant. It leaves out error behavior for an unknown contact_id and whether clearing counts as a destructive change, which would have made it complete.

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 100%, so the baseline is 3, but the description goes beyond the schema by explaining partial-update semantics across the 13 fields and the mandatory remaining identifier. It adds useful meaning rather than restating per-parameter types.

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 opens with a specific verb ('Edit') plus resource ('a contact') and enumerates the editable field groups, including the address sub-fields. The verb alone separates it from create_contact, delete_contact and get_contact in the sibling list, so an agent can pick it without opening the schema.

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?

'Only the fields you send are changed; anything you omit keeps its current value' gives a clear usage model that distinguishes a patch-style edit from a full replace. It doesn't explicitly name when to prefer it over siblings (e.g., create_contact for new records) or state prerequisites like lookup via get_contact, so it stops short of a 5.

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