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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral context: the data comes from active public asking prices, each figure carries activeCount and sampleCount, and statistics are withheld below 10 sampled listings. That withholding rule and the sample/active distinction are exactly the kind of operational detail an agent cannot infer from 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?

Dense and front-loaded: provenance first, then the parameter-to-output-shape mapping, then the sample-count caveat, ending with the locale instruction. Every sentence 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?

Given an output schema exists, return formatting need not be explained, yet the description still clarifies the two counters on each figure and the below-10 withholding threshold. With five optional parameters and two enum constraints, all scoping and language concerns an agent needs are covered.

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 100%, so the baseline is 3. The description restates the combinatorial city behavior ('one city = its districts; several = side by side') and the sale/rent separation, but these are largely already documented in the parameter descriptions, and it adds no syntax or format detail beyond them.

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 resource (market statistics) and dataset provenance (asking prices of active public listings), and explicitly excludes adjacent interpretations: 'not sales, valuations or forecasts'. This clearly separates it from sibling tools such as search_listings or compare_listings, which deal in individual listings rather than aggregates.

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?

Gives unusually explicit routing rules for the scoping parameters: no city means island-by-city, one city means districts, several means side-by-side, city plus district means a district profile. It also states that sale and rent are reported separately and never mixed, plus 'Pass locale.' It stops short of naming sibling alternatives (e.g. when to prefer compare_listings over this tool), so it lands at a strong 4 rather than 5.

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