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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavior: the exact matching heuristics, the archived-record exclusion, that results come back as groups, and 'Free' (no credit cost) — a non-obvious operational fact. It doesn't mention ordering, pagination beyond the limit param, or how large a group can get, keeping it from a 5.

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?

Front-loaded with the core definition, then the matching rules, then the excluded case, then the recommended follow-up action — a logical order. It is dense and slightly run-on in the rule enumeration, but every clause conveys distinct matching logic that the agent would otherwise have to guess.

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?

With no output schema, the description does signal the return shape ('each group'), which is the key missing piece an agent needs. Combined with the readOnly annotations and the merge hand-off, an agent can call this correctly. The unaddressed limit semantics and absence of any note on group ordering/cost of large scans are the only remaining gaps.

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 0%, so the description carries the burden. It effectively explains the 'object' parameter by giving separate matching rules for contacts and companies, but the 'limit' parameter (default 20, max 100) is never mentioned, nor is what a result 'group' contains. Partial compensation earns a baseline 3.

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 ('Contacts or companies that are probably the same') and then defines exactly what counts as a duplicate for each object type, including the normalization rules (case-insensitive email, any phone format, suffix-stripped company names). This is clearly distinguishable from crm_find_contacts, crm_search, and crm_find_companies, which are lookup tools rather than dedupe detectors.

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?

Explicitly routes the agent to the follow-up action: 'Merge each group with crm_merge_contacts or crm_merge_companies,' which is the correct next step and names the sibling tools. It also notes archived records are excluded, which prevents wasted calls. It stops short of stating when NOT to use this (e.g., when looking up a specific known contact, use crm_find_contacts), so it falls just short of a 5.

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