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

Annotations already mark the tool read-only and idempotent; the description adds important behavioral caveats: the network is mostly sample data, demo entries are named [DEMO] and flagged is_demo, and the agent should verify before acting. The schema further discloses that radius_miles and availability_window are accepted but not applied, providing additional transparency beyond the annotations.

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 description is compact and front-loaded: it states the purpose first, then the critical demo-data warning, then the access note. Every sentence earns its place, and the warning is prominently capitalized without being verbose.

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 6-parameter search tool with no output schema, the description covers the criteria, the ranking nature of results, the demo-data limitation, and key non-applied filter caveats. It does not explain the ranking order or exact return fields beyond is_demo and radius_miles_applied, but the information provided is sufficient for an agent to call the tool correctly.

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?

The description enumerates the parameter categories but adds little meaning beyond their names. Schema description coverage is 50%, and the schema itself carries the important semantics about location matching and non-applied filters. Undocumented parameters like price_band and max_results are mostly self-explanatory, but the description does not compensate for the coverage 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?

The description states a specific action: 'return ranked candidate businesses from our supply network' given explicit criteria, which clearly defines what the tool does. It also distinguishes itself from sibling tools like get_status, check_compliance, and send_message by being the business-search/resource tool.

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 makes the use case clear: use it when you need candidate businesses matching vertical, location, capability, price band, or availability window. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it over the listed siblings.

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