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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's added value is the return shape: a total count plus a page of contacts with ids, and the side effect that an unfiltered call also returns most-used tags. That is useful behavior not derivable from the schema, though rate limits or empty-result handling are not mentioned.

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 tight sentences: capability first, return shape second, usage guidance last. No filler, no repetition of the title, and the routing hint is placed where it will be read.

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 correctly compensates by describing the return (total + page of contacts with ids). For a six-parameter, all-optional read tool this is close to complete, though pagination defaults and behavior on empty results are left to the schema.

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 83%, so parameters are largely self-documenting; the description still adds framing by grouping the filters into text, tag, channel reachability, and membership/listing status, which helps an agent map intent to parameters. It does not add syntax details beyond what the schema already provides.

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 (search/filter) and resource (ShearQuery CRM contacts) plus the filterable dimensions (text, tag, reachability, member vs listing). It clearly separates this from mutation siblings like crm_save_contact or crm_delete_contacts by naming itself as the source of contact ids.

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 tells the agent when to reach for it: answering 'how many…' questions and obtaining contact ids for the other crm_ tools. It does not, however, distinguish itself from near-neighbors such as ghl_find_contacts, find_client, or find_prospects, which an agent could easily confuse with this one.

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