Update a contact

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing replace-as-a-whole semantics, empty-value clearing conventions, silent data loss risk, etag-conflict behavior (HTTP 400), and last-write-wins fallback. This is exactly the behavioral nuance needed to avoid destructive mistakes in an update operation.

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 description front-loads the core purpose and packs essential warnings into dense, purposeful clauses. Three sentences carry a lot of critical information, and while the parenthetical density makes it somewhat hard to parse, every sentence earns its place given the tool's destructive potential.

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 16-parameter, nested-object mutation with no output schema, the description covers the essential decision points: prerequisite fetching, complete-group requirements, etag strategy, and the minimum-field constraint. Combined with the rich per-parameter schema descriptions, an agent has enough information to invoke this tool correctly and avoid silent data loss.

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 descriptions already cover each parameter at 100%, but the description adds a unifying semantic layer: group replacement rules, empty-value clearing, and the critical 'At least one contact field is required' constraint that is not evident from the schema's required array (which only lists resource_name). The etag behavior is also clarified beyond the schema note with failure mode details.

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 — 'Updates an existing contact and returns the updated Person.' This clearly distinguishes it from sibling tools like get_contact, create_contact, delete_contact, and batch_update_contacts by focusing on single-contact modification. The title and description align perfectly.

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?

Explicitly instructs to fetch current values with get_contact first and send complete groups, or data is silently dropped — a concrete when-to-use rule with a referenced alternative. It also explains the two etag strategies (pass from get_contact or auto-fetch). It doesn't explicitly contrast with batch_update_contacts for multi-contact updates, but the single-vs-batch distinction is inferable from the tool names.

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