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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavioral value: omitted fields are left untouched (merge semantics) and the response is the updated contact's business fields. It omits auth/permission requirements, and the stated HTTP verb 'PUT' conflicts semantically with the partial-update behavior it describes, but that is an internal wording issue rather than a contradiction of the annotations.

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 short clauses lead with the 'WRITE:' classification, then the partial-update rule, then the return value and route. No filler, no restatement of the title, and every element earns its place.

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 19-parameter mutation tool the description covers the essentials: write nature, merge semantics, and the return shape, and the annotations cover the safety profile. It does not address failure modes (e.g. unknown contact id, invalid reference ids for client_source_id/client_status_id), so it is slightly short of 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 description coverage is 100% across all 19 parameters including the nested custom_fields object, so the schema already carries full parameter meaning. The description adds only the blanket rule that unlisted fields are unchanged, which is a semantic nuance (notably for custom_fields) but no field-level detail 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?

States a specific verb+resource ('change the given fields of an existing contact') and immediately scopes the operation as a partial update on an existing entity, which cleanly separates it from propstack_create_contact and propstack_get_contact. An agent can identify the target record type from the description alone.

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 phrasing 'change the given fields of an existing contact' implies when to use it (existing contact, partial change) but never explicitly contrasts with siblings such as propstack_create_contact or propstack_get_contact, nor states prerequisites like needing a valid contact id. Usage is inferable but not spelled out.

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