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 description is free to add real operational context: index_method repeat_sales_area vs repeat_sales_national (a correctness trap), last_settled_period and is_forecast with lo/hi bands, tx_n being a cube sample not a registry count, quarterly returning an empty series with a note, UK-only, free, and unknown-area error behavior that must be read back to the user.

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 purpose and routing, then parameters, then the provenance warning, and it uses emphasis ('READ provenance BEFORE QUOTING A MOVE') to surface the highest-risk step. It is long and dense, but nearly every sentence carries actionable information rather than restating the name or title.

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 7-parameter tool with zero schema descriptions, an output schema, and rich annotations, the description covers what an agent must know: valid formats, filtering scope, default series range, the provenance/index_method interpretation rule, forecast flags, and failure behavior. Nothing needed for correct invocation or correct quoting of results 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?

Schema description coverage is 0%, and the description compensates thoroughly: area_code is a postcode district (full postcodes truncated) with area_type='district', or a local authority NAME (not a GSS code) with area_type='lad'; start/end accept '2015', '2015-06', '2015-Q2' with end inclusive; limit keeps the most recent N periods, default whole series 1995-present. Only include_forecast is left implicit, conveyed via 'the forecast tail flagged'.

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: the published house-price index for one district or local authority, with level per month, base period, forecast tail and provenance. It explicitly differentiates from siblings by naming the exact boundary: 'For PRICES by cohort use market_facts; for sale COUNTS use market_volume_series' and clarifies its relationship to valuation_full's back-series via provenance.series_basis.

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 triggering questions ('how has W14 moved since 2015', 'what is the trend in Camden'), the carry-forward formula for pricing, and explicit exclusions routing to market_facts and market_volume_series. It also tells the agent when the output is not local (thin areas publishing the national index) and how to report that.

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