Add or update a CRM record

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the description's value is in explaining *why* it is risky: ambiguous duplicate matching and the default fill-only merge that silently leaves existing values intact unless overwrite is true. That is real behavioral context beyond the annotations, though it omits what the call returns (created vs. updated identifier) and whether non-customer record types are ever matched.

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 dense sentences with no filler, front-loaded with the add-or-update outcome before the matching details. The opening clause is slightly awkward but still parses cleanly and every sentence carries information.

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 destructive upsert with a fully described schema and no output schema, the description covers matching, merge behavior, and duplicate risk — the things an agent most needs. The remaining gap is outcome feedback (which record was created or updated, and what happens with organization/potential types).

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 schema already documents every parameter, and the baseline is 3. The description adds one genuinely new fact the schema does not state — that record_id takes precedence over phone/email matching — but the overwrite and record_type semantics are restated rather than expanded.

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 pair ('Add a record, or update the customer it matches') and makes the upsert nature explicit, which an agent can act on directly. It does not name or contrast any sibling such as crm_set_field, so differentiation is left implicit.

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 a clear operating context: it adds when nothing matches and updates when a match is found, with match precedence defined (record_id first, then phone/email). It also warns that duplicates can match the wrong record, which is actionable caution, but it stops short of naming alternatives or stating when not to use this tool.

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