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

Annotations only declare it a safe read (readOnlyHint, idempotent, non-destructive); the description goes well beyond that, disclosing that listings_added_n is a never-reduced cohort that undercounts by reduction_share, that sold_matched_n is match-rate limited, that no exit dates exist, and that the call is free. These cohort caveats are exactly the kind of behavioral context an agent cannot get from structured fields.

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?

Front-loaded with the purpose and metric list, then a clearly labelled caveat block. The metric enumeration is dense and long, but each item maps to a real returned field and the numbered warnings earn their space.

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?

An output schema exists, so return values need not be explained, and the caveats give the agent enough to interpret the numbers responsibly. The main gap is that 7 input parameters with zero schema coverage are only partially addressed by prose.

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 7 parameters, so the burden shifts to prose. The description covers the semantics of channel and bedroom_band ('one area, channel and bedroom band') but says nothing about start, end, limit, area_code or area_type, leaving the temporal window and area-key conventions unexplained.

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 verb+resource (monthly supply-side statistics from portal listings) scoped by area, channel and bedroom band, and enumerates the exact metrics returned (listings added/reduced, reduction share, price/rent median and quartiles, HHI, yields, asking-to-sold ratio). It explicitly distinguishes itself from the sibling listing_stock_series ('what is on the market NOW').

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?

Names a concrete alternative and the condition that selects it: 'Use listing_stock_series for what is on the market NOW.' It also warns against two misuse patterns (dividing sold_matched_n by listings_added_n; expecting days-on-market). However it gives no guidance on when this tool is the right choice versus other index/market series siblings.

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