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

Adds real behavior beyond the annotations: near-duplicate names at ≥0.85 similarity return the existing record with deduped=true, and force=true bypasses it. That is important because idempotentHint=false would otherwise suggest every call creates a new record. It stops short of disclosing permission requirements or the privacy consequences of the visibility field.

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 sentences, both load-bearing, with the core action front-loaded and the dedup caveat immediately after. Nothing is wasted.

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?

Wait — this is a 13-parameter mutation tool with no output schema, and the description usefully documents the one non-obvious return value (deduped=true), which is genuinely needed. However, it omits the required fields' significance, the meaning/default of visibility, and any permission or scope caveats, so it remains incomplete for a tool this wide.

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 only 23% across 13 parameters, so the description needs to compensate and largely does not. It explains force and the name-matching logic (relevant to firstName/lastName), but leaves kind (8-value enum), visibility (private/ecosystem/public), tags, notes, role and the contact channels undocumented in prose.

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 and resource (add a person to the signed-in user's care network) and gives a concrete example ('e.g. a doctor'), which is clear enough to separate it from list/get/update/delete contact siblings. It does not address how it differs from vitalli_link_contact_to_org, which is the one sibling an agent could plausibly confuse with it.

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 implies the use case (create a new care contact) and explains the dedup/force branch, but never says when not to use it — e.g. to check for an existing contact first, or to use vitalli_update_contact for a person already in the network. Usage is inferable, not explicit.

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