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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so safety is partly covered. The description adds genuinely new behavioral context: it discloses partial-merge semantics ('Changes the fields you send') and that email/platform ids are read-only identity fields. It does not, however, explain the destructiveHint=true implication (what gets overwritten or lost).

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 short sentences, front-loaded with the purpose before the constraint. 'Changes the fields you send' is slightly informal but every sentence earns its place with no padding.

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 and nested custom_fields, the description covers the key gotcha (partial update, read-only identity). It leaves the destructiveHint=true and idempotent behavior unexplained, so an agent cannot fully predict the consequences of the call.

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?

At 67% schema coverage the schema carries most weight, fully documenting mobile, agent_id, contact_id and custom_fields, while name and status remain bare. The description adds partial-update semantics and the read-only identity-field note (email, which is not even a parameter), so it contributes some meaning but does not fully compensate for the undocumented 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 clear verb+resource ('Update a contact') and adds scope via 'Changes the fields you send', making the partial-update nature explicit. It does not, however, name any sibling (e.g. update_lead, get_contact) to differentiate itself in a crowded set of update_* tools.

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?

There is no when-to-use/when-not guidance and no mention of alternatives among the many update_* siblings. The reader must infer from 'Changes the fields you send' that this is the correct tool for editing an existing contact, but nothing tells them when to reach for update_lead or get_contact instead.

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