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

Annotations only establish read-only, idempotent, non-destructive safety; the description layers on genuinely non-obvious behavior: radius widening at 8/16/32/50 km steps, the wider_search envelope with deduplicated results, city-specific statuses (matched/none_in_city/unrecognized), data_coverage and gaps semantics, and the guarantee that suggested actions are never executed by Onhand. Nothing here contradicts the annotations, and no other field carries this information.

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?

The purpose is front-loaded, but the body is a dense wall of internal jargon (wider_search, matchedOn, data_coverage, gaps, release gates) with several telegraphic fragments such as 'Preserve request_area, public listing-request links and contact next steps.' Most sentences carry real information, but the lack of grouping or formatting makes it harder to parse than its content warrants.

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 an 8-parameter, nested-object tool with no output schema, the description covers widening behavior, result envelopes, coverage fields, city fallbacks, and non-claims (no stock/price/slot assertions) in substantial depth. The main omission is sibling routing; return-shape explanation is unnecessary since no output schema exists.

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% across 8 parameters, so the description must carry the load, and it largely does: q is defined as the shopper's want, category as business type, attributes as offering-only narrowing, city as a name/slug/neighborhood that replaces the radius, and research_fact_types as shopper-relevant facts with a capped URL yield. It stops short of stating radius_m's units/default explicitly (only the widening steps are given), leaving one gap.

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?

Opens with a specific verb and dual resource: 'Searches matching offerings and nearby directory businesses together', which implicitly separates it from the offerings-only and businesses-only siblings. However, it never names search_local_offerings or find_nearby_businesses, so the agent must infer the boundary rather than being told 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?

Usage is implied by the combined-search scope and by scattered conditions ('City searches do not widen', 'Never treat directory alternatives as confirmed item or requirement matches'), but there is no explicit when-to-use/when-not statement and no routing against the many sibling search tools. The agent is left to infer selection criteria.

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