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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, yet the description adds substantial context beyond them: the achieved_to_avm interpretation and typical 0.45–0.95 spread, the single-snapshot AVM caveat on auction_date, UPRN-derived bedrooms/property_type with catalogue coverage figures, UK-only scope, and cost ('free').

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 core distinction in the first line, and the dense paragraphs on achieved_to_avm provenance each carry real signal. It runs longer than typical, but nothing is filler; the caveats are the value.

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 comps tool with an output schema present, the description covers everything an agent needs: what is measured, provenance and reliability caveats, geographic constraint, and scope/cost. Return-format detail is correctly left to the output schema.

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 params, so the description must carry the load. It does explain postcode_district/postcode_area and where bedrooms/property_type come from, but limit, months, max_beds, min_beds, and is_commercial are never defined semantically — the 24-month window and paging behaviour are left for the agent to infer.

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 (auction comparables on ACHIEVED prices, benchmarked against an AVM) and explicitly contrasts it with a plain listing, which separates it from siblings like property_comps, valuation_comparables, and auction_lots. An agent knows exactly what this returns without opening the schema.

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 (judge whether a guide price is realistic, estimate what a lot will fetch) and a hard input rule (supply postcode_district or postcode_area, there is no area_id path). It stops short of naming which sibling to pick instead for adjacent questions (e.g. auction_discount, auction_lots), so it's clear but not fully routing.

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