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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the data comes from ShearQuery's own directory (not a live external scrape), the call is free, results carry a data-as-of date, and email addresses are never returned. Ranking criteria are disclosed, though it doesn't explain result freshness limits or how stale data can get.

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?

Key information — the agency gate, the target resource, the ranking basis — is front-loaded in the first sentence, and the trailing sentence usefully summarizes the returned fields. The middle clause is a long parenthetical stack that a reader must unpack, so it is efficient but not maximally crisp.

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 tool with no output schema, five parameters and read-only annotations, the description covers everything an agent needs: eligibility, search inputs, ranking logic, the shape of each result (id, phone, website, links, date), the follow-up tools for that id, and the explicit absence of emails.

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 80%, so the baseline is 3, and the description genuinely adds meaning: it explains what each 'needs' signal means (few Google reviews for their city, a low rating, stalled reviews, no website, plus open booths) and that they are combined cumulatively, matching the schema's 'ALL of these' semantics. The required business_type and the city/ZIP pairing are also made explicit.

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 concrete verb plus a precisely scoped resource: businesses of four named types in a city/ZIP that are 'not on ShearQuery yet,' ranked by need. This clearly separates it from find_client, find_pros_to_book and my_prospects, which operate on existing relationships rather than net-new leads.

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 'For an APPROVED agency' gate gives an explicit precondition, and the description names follow-up siblings (prospect_details, save_prospect) for the id it returns. It stops short of saying when *not* to use it (e.g. to review already-saved leads — that's my_prospects), so it is clear but not exclusion-complete.

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