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

Annotations only declare read-safe/open-world flags, so the description carries the rest and delivers: never bills, purchase: 0, never returns property rows/RadarIDs/addresses/criteria catalog/applet handoff, and a 25-result privacy floor that empties facets below it. These are non-obvious operational traits an agent could not infer from annotations or schema.

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?

Purpose, required param, and return-shape facts are front-loaded before the routing advice. It is dense and slightly run-on in the return/edge-case sentences, but essentially every clause carries distinct operational information with no filler.

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 2-param, no-output-schema tool, the description covers inputs (criteria source, includeFacets), guaranteed returns (total_result_count, criteria echo, purchase: 0, related_tools), suppression rules, and downstream tool routing. Nothing an agent needs to invoke it correctly is omitted.

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 100%, so the baseline is 3, but the description adds value beyond it: criteria is explicitly a JSON-encoded {"name","value"} array sourced from get_criteria (session state the schema alone can't convey), and includeFacets triggers Limit=0 with privacy-floor semantics. Only minor added meaning missing (no value-shape examples, deliberately).

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 opening sentence states a specific scope (non-billable property set characterization, all 50 states + DC), and the name/behavior pairing makes the search operation unambiguous. It doesn't sharply contrast against get_properties_details or get_properties_insights in the first line, but later sentences do that work.

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?

It names prerequisites (call get_criteria first), alternatives and their conditions (get_properties_insights for grouped/tab-depth characterization at 25–100,000 results; get_properties_details with count_only before purchasing billable rows), and an explicit prohibition (marketing flows must not default to get_properties_details). This is textbook when/when-not/alternatives routing.

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