Update a contact

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

Beyond the annotations (readOnlyHint false, idempotentHint true, destructiveHint true), the description adds important behavioral details: only properties present in the request are changed, null clears a field, and the response carries only core attributes while other data must be fetched via a GET endpoint. This is consistent with the annotations and provides useful additional context.

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 is compact and well-structured: a one-sentence purpose, followed by two concise paragraphs covering partial-update behavior and response scope. No filler or redundant repetition of schema data. Information is front-loaded with the core purpose first.

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 no output schema, the description covers key operational semantics: partial updates, null clearing, response scope, and how to retrieve full contact data. It does not mention error cases or permissions, but those are not essential for calling the tool. Given the parameter complexity and annotations, this is sufficiently 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%, but many parameter descriptions are generic (e.g., 'name parameter'). The description explains the global partial-update semantics that apply to all parameters, clarifying how omitting vs sending null affects values. It also reinforces the fields array's behavior (already in schema) and the phone format. This adds meaningful interpretation beyond the schema.

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 clearly states the tool updates a contact's attributes and custom field values, a specific verb+resource. It does not explicitly differentiate from similar sibling tools like reach_updateAContactFieldV1, but the wording makes it clear it targets contact field values, not field definitions. The purpose is unambiguous.

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 description gives no explicit guidance on when to use this tool versus alternatives such as reach_createANewContactV1 or reach_updateAContactFieldV1. It explains partial update semantics but does not mention exclusions or define the boundary with sibling tools, leaving the agent to infer usage context.

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