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

Annotations provide idempotentHint=true, but the description goes well beyond that by explaining idempotency keyed on phone, the exact fields updated, CRM sync behavior via source/external_id, and the nuanced opted_out semantics including the consent requirement for re-subscribing. This is rich behavioral disclosure beyond what annotations alone convey.

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 sentences, each earning its place: core upsert behavior, phone format, CRM sync, then opt-out semantics. The most important behavior is front-loaded, and the consent warning is included without expanding into unnecessary prose.

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?

Given seven parameters, nested objects, and no output schema, the description covers the behavioral essentials and parameter semantics well. A small gap is that it does not describe what the tool returns (e.g., contact object vs success indicator) or whether tags/fields are fully replaced or merged, but these do not block correct invocation.

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 71%, and the description adds real meaning to several parameters: E.164 format for phone, CRM sync purpose for source/external_id, and the two-state plus omit behavior for opted_out. It does not add much for name, tags, or fields beyond saying they are updated, but the most nuanced parameters are clarified.

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 states a specific verb and resource ('Add or update a contact') and immediately clarifies the distinguishing behavior: idempotency on phone, updating name/tags/fields when the contact already exists. This separates it from plain create or update tools without needing to inspect the schema.

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 clear operational context for when to use this tool: it handles both add and update based on phone, and it explains the specific opt-out/re-subscribe decision. It does not explicitly name alternative sibling tools like import_contacts or list_contacts, so it stops short of full when-not-to-use guidance.

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