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

Goes far beyond the readOnly/openWorld annotations: discloses the county coverage boundary, that Snohomish has no size/beds and month-level dates, that King condos may lack size and location, that statistics are not an appraisal, that a miss is not charged, and that attributions and a disclaimer must be passed through. That is exactly the operational context an agent needs before calling.

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-loads the search modes and the result contents before the caveats and pass-through instructions, so the essentials come first. It is dense and semi-colon heavy, with mild redundancy between the '(chart.points, chart.monthly_median) and chart.image_url' listing and the later 'draw it from the series, or link chart.image_url' instruction, but nearly every sentence carries information given the tool's complexity.

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, yet the description still summarizes what comes back (sales, medians/quartiles, half-over-half trend, price band, chart series and image URL), and it covers the data-quality caveats and attribution obligations the schema cannot express. Nothing an agent needs to call and present results correctly is missing.

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?

With only 33% schema coverage across 21 params, the description compensates well: it defines the four area modes (address+radius, latitude/longitude point, polygon of [lat, lon], ZIP), the 1-36 month window, the filter set (beds, baths, sq ft, year built, price, property type) and the purpose of subjectSqft for the price band. It leaves limit, county and the radiusMiles default to the schema, which already documents 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?

Opens with a specific verb+resource (find recorded home sales) and enumerates the three ways to define the search area. It clearly distinguishes itself from siblings like wa_sale_history or wa_market_snapshot by centering on comps around a subject property plus a chart for a pricing conversation.

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 concrete use cases ('what did 3 bed homes near this street sell for in the last year', 'what should we list at') and instructs the agent to show the chart and quote numbers exactly. It does not explicitly name a sibling tool to use instead when the agent wants raw history or a market-wide trend, so routing is implied rather than stated.

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