MarketCode

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

Annotations already declare a safe read (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: depth bounds 1–3, a 100-node cap, explicit truncation signalling on clipped networks, exclusion of individuals, credit cost, and the fact that an unpublished root is free. These are exactly the operational facts an agent cannot infer 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?

Telegraphic and front-loaded: purpose first, then access constraint, then operational limits, then caveats and cost — every clause carries information and none is redundant. The 'Costs 15 credits (15p)' phrasing is slightly compressed but still parseable.

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 graph-traversal tool with an output schema, the description covers the decisions an agent must make — auth, depth, node cap, truncation interpretation, cost, and the trap of reading absent links as negatives. The remaining hole is the meaning and output shape of each 'kind' value, which the schema leaves undocumented.

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%, so the description carries the burden and only partly meets it: it bounds 'depth' to 1–3 and implies the 100-node ceiling that binds 'limit'. It says nothing about the seven enum values of 'kind' (organizations, titles, agents, properties, buildings, land, listings) or the expected form of 'entity_id', which are the two required parameters.

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 ('Investigate') and resource scope ('recorded corporate ownership, title and agency relationships'), which is far more than a restatement of the name. It does not, however, distinguish itself from close siblings such as actor_path or entity_relationships, so an agent must infer the split.

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 a hard usage constraint ('Requires the customer's account; never use an anonymous preview key') and implicit scope limits ('Individuals are excluded'), which is genuine when-not guidance. It never names an alternative tool or explains when to prefer a path/reachability lookup over a network expansion, leaving the sibling choice to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds value beyond them: a 15-credit cost, the caveat that a clipped/truncated search yields incomplete results rather than proof of no relationship, and the shape of the return (ordered hops plus evidence). It does not explain what triggers clipping or how limits interact with cost.

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?

Purpose is front-loaded and every sentence carries information: scope, prerequisite, caveat, return shape, cost. Slightly dense but 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?

An output schema exists, so return details need not be spelled out, and the cost/account/clipping signals are helpful. But for a 6-parameter, 0%-coverage tool with a configurable depth that may exceed the stated three hops, the description leaves too much of the invocation surface unexplained.

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 6 parameters, so the description must compensate and largely does not. "Within three hops" loosely maps to depth, but source_kind/source_id/target_kind/target_id and especially limit are never explained (what limit bounds, whether depth is capped, how the enum kinds combine).

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 and resource: finds a recorded path between two corporate-network records, bounded by hop count. It is clear what the tool returns (ordered hops with source/publication evidence). It does not name the closest siblings (actor_network, entity_relationships), so differentiation is left to inference.

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?

"Requires the customer's account" gives a real prerequisite, and the note about clipped searches warns against over-reading results. However, there is no explicit when-to-use versus actor_network or entity_relationships, and no statement of when not to use this costly tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the description's added value is the pricing model (free vs priced OS AddressBase-backed siblings) and the UK-only geographic scope. These are genuinely useful behaviors not in the annotations, though pagination/rate behavior is left unstated.

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 purpose in the first sentence, then routing and pricing in short scannable blocks. Slightly padding with the closing 'UK only. Free.' fragments that restate earlier points, but nothing significant is wasted.

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 shape need not be described, and annotations cover safety. The description supplies scope, pricing, and sibling routing, leaving only parameter details thin — a minor gap for a low-complexity single-required-param search tool.

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% for three parameters, so the description must compensate. It only partially does: 'partial address or postcode' hints at the q input format and 'UK only' implicitly bounds country, but max_results is never explained and no value ranges or defaults are given.

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 and resource ('Returns ranked candidates for a partial address or postcode') and immediately distinguishes itself from address_resolve by naming what that sibling does instead. An agent can tell it apart from address_by_postcode/address_by_uprn without opening a 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?

Explicit routing: use address_resolve to canonicalize a candidate, and 'Prefer it for anything interactive, and resolve once at the end' gives a clear when-to-use pattern. It also names when competitors are preferred (priced lookups vs free narrowing).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the cost model (2 credits / 2p, free on marketcode.ai). It does not disclose any cap on the number of addresses returned for large postcodes, nor behavior when the postcode is unknown or non-UK.

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?

Two short sentences, each earning its place: the first defines the operation and scope, the second discloses cost. Front-loaded and free of 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?

An output schema exists and annotations cover the safety profile, so the description needn't restate return values. However, for a bulk-lookup tool it should mention practical limits (how many addresses are returned, whether there is pagination/truncation) and accepted postcode formatting, which are the main failure modes an agent would hit.

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%, so the description carries the burden for the single required parameter. It only asserts 'UK postcode', which essentially restates the parameter name 'Postcode' — no guidance on case, spacing, or whether outward codes alone are accepted. It does not compensate for the coverage gap.

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+scope: 'Return all addresses at a UK postcode.' The 'at a UK postcode' qualifier implicitly distinguishes it from address_by_uprn (addresses for one property) and address_autocomplete (partial string lookup), though no sibling is named.

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?

The usage is implied by the purpose statement — you call this when you already have a full postcode and want the addresses on it. But nothing states when to prefer address_by_uprn, when to use address_autocomplete to resolve a partial postcode first, or what to do if the postcode is invalid. Adequate but leaves routing to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful operational context beyond the annotations: cost (1 credit / 1p), free access on marketcode.ai, and the UK-only constraint.

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?

The description is short and front-loaded: purpose, scope, cost, then the key usage distinction/alternative workflow. There is no wasted text.

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 simple one-parameter read-only lookup with an output schema and rich annotations, the description covers the important missing context: cost, geography, UPRN keying, and the alternative lookup path.

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 coverage is 0%, so the description must carry the burden. It does add meaning by clarifying that the key is a UPRN rather than an address and by pointing to `address_resolve` as a way to obtain one, though it does not give an example format or range.

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?

The description states a specific verb and resource: look up an address by UPRN. It adds scope ('UK only') and distinguishes this from address-based lookup by saying it is 'Keyed on a UPRN, not an address.'

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?

It explicitly tells the agent what to do when it does not already have a UPRN: use `address_autocomplete` to narrow and then `address_resolve` to obtain one. It also names the relevant alternative tools directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral context about cost (2 credits / 2p, free on marketcode.ai), which is not in annotations, but it does not discuss return behavior or rate limits.

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?

The description is a single, front-loaded sentence with a compact cost note. Every clause carries useful information and there is 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?

An output schema exists, so return values need not be explained. However, for a three-parameter tool the description omits usage guidance and parameter semantics, especially the optional country and max_results fields, making it only minimally complete.

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%, so the description must compensate for undocumented parameters. It only implies the required query parameter via 'free-text address' and says nothing about the optional country or max_results parameters, leaving two of three parameters 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?

The description states a specific verb and resource: resolve free-text address to a canonical record, naming UPRN as the UK output. It is clear what the tool does, but it does not distinguish itself from close siblings like address_autocomplete or address_by_postcode.

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?

The description gives no explicit guidance on when to use this tool versus alternatives such as address_autocomplete or address_by_uprn. It mentions cost, but not decision context or prerequisites.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety bar is lower. The description adds a genuinely non-obvious behavioral trait — sale and rental are aggregated separately, so median_asking_price and median_monthly_rent answer different questions — plus UK-only scope. That is real context beyond the 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-loads the purpose in the first line, then adds the two nuances an agent would otherwise get wrong, then closes with scope constraints. No filler sentences.

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 no explanation, and the description pre-empts a likely misreading of the two median fields. It is nearly complete for a simple read-only lookup; the only gap is meaning for the limit/months controls.

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%, so the description carries the burden. It explains area_id's provenance well and the sale/rental distinction loosely maps to listing_type, but limit and months are left entirely undocumented. Partial compensation, so it lands at the minimum-viable baseline.

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 and resource: 'Which estate agents actually transact in an area, ranked by listing count.' The output ordering is even declared, which is unusual and helpful. This is distinguishable from siblings like market_ranking or actor_network without opening a 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?

It implies the prerequisite for area_id ('the marts area id from area_resolve') and scopes to 'UK only. Free.', which is useful context. But it never says when to reach for this versus alternatives (market_ranking, area_report), nor any exclusions — usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely useful context: UK-only scope, a 25-credit cost, and the degradation/`not_available` semantics. It stops short of describing section structure or output shape, but the output schema covers that.

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 one-document purpose, then the critical scope warning in caps, then operational notes. Slightly dense but each sentence carries non-obvious information; the caps warning earns its emphasis.

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?

Covers scopes, keying, degradation behavior, cost, and geography, and an output schema covers return structure. Nothing an agent needs to invoke it 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 0% schema coverage the description must carry the parameters, and it thoroughly explains `lad_code` (a GSS code, local-authority keyed) and `postcode_district` (live-listing keyed). `sector` (default ALL) is left unexplained, a minor gap against otherwise strong param guidance.

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 and resource: composes a single market document for one area, enumerating its sections (readiness, commercial capital/rent indices, planning record, live listings). It explicitly differentiates from `property_report` and points to `area_resolve` for keying, so an agent can tell it apart from single-lane siblings.

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?

Explicit about the two non-interchangeable scopes (LAD code vs postcode district), tells the agent to pass both to fill every section, and explains what happens when one is omitted (`not_available`). It also directs checking `sections_degraded` and names `area_resolve` as the way to obtain a `lad_code`.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds scope and cost context not present anywhere else: 'UK only. Free.' It also previews the return shape. No failure modes or rate limits are mentioned, so not a 5.

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?

Three short sentences, zero filler, with the core capability and the routing rule front-loaded before the scope/cost note. Every sentence carries information.

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?

The description covers purpose, routing, geography scope, cost, and an output preview, and an output schema exists so return values need not be restated. The remaining omission is guidance on the optional H3 parameters, which are undocumented in both schema and 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% and the description never addresses include_h3 or h3_resolution — an agent cannot tell what H3 output is or when to enable it. Only the required area_name is given indirect meaning via the examples 'Hackney' and 'E5'.

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 concrete verb (resolve) plus the resource and the exact outputs (area_id, centroid, hierarchy breadcrumbs), with an input example ('Hackney', 'E5'). This clearly separates it from address_resolve and area_reverse_geocode, which key off addresses or coordinates rather than names.

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?

'Call this first when a question is about a named area rather than a specific address' gives an explicit entry-point rule and implicitly contrasts with the address-based siblings. It does not name an alternative tool outright or state when-not to use it, so it falls short of a 5.

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

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). The description adds genuinely non-structured context: geographic coverage is UK only, the call is free, and it explains why type_id is required (one area per geography layer, otherwise ambiguous). That is meaningful beyond the 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?

Three short sentences, front-loaded with the core operation, then the required-parameter rationale, then scope/cost. 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description covers scope, cost, and the key required param; the only minor gap is that it doesn't hint where an agent obtains a valid type_id.

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%, so the description must carry the load. It thoroughly explains the non-obvious parameter, type_id (an area type UUID, required, and why), which is the one that would otherwise confuse an agent; lat/lng are conventional and need no elaboration.

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: it returns the area of a given type that contains a coordinate, which is a distinct operation from siblings like area_resolve or area_report. It is clear what the tool does, though it does not explicitly contrast itself against any named sibling.

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?

The description implies the use case (you have a lat/lng and want the containing area) and adds scope constraints (UK only, free), but it names no alternative tool and gives no explicit when-to-use/when-not guidance versus area_resolve or parcel_lookup.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine value beyond them: medians rather than means and why (skew from towers), whole-percentage output, and 'Free'. Return format is covered by the existing output schema.

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 metric list, then a short methodology note and scope flags; every sentence earns its place. The median aside is slightly conversational but justifies a real methodological choice, so waste is minimal.

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?

With annotations covering safety, an output schema covering return values, and the description covering metric content, methodology, parameter provenance, and geographic scope, an agent has everything needed to select and call this tool correctly.

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% for the single parameter, so the description must compensate, and it does: 'area_id is the marts area id from area_resolve' tells the agent both the identifier space and how to obtain a valid value. It could specify format more exactly, but the provenance is the key missing piece and is supplied.

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 (composition of built stock in an area) and enumerates the exact metrics returned: unit counts, HMO share, mixed-use share, median height/footprint, solar penetration. This enumeration is enough to distinguish it from siblings like area_report or market_profile without opening any 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?

The description gives clear prerequisites and scope: area_id comes from area_resolve, and the tool is UK-only. It does not, however, name an explicit alternative or state when not to use it (e.g., versus area_report or energy_profile), so it falls short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: unknown areas raise an error naming nearest matches (and should be read back), provenance.pub_freq reveals the grain the pipeline judged resolvable, and inc_se_pp carries the per-period standard error of the move. It also notes the series is smoothed toward the parent geography and is free to call.

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 definition, base period and source, then the routing contrast, then argument semantics, then the provenance caveat. Dense and largely waste-free, though the three-paragraph shape is longer than strictly necessary and the trailing 'Free.' adds little.

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?

With an output schema present, return values need no explanation, and the annotations cover the safety profile. The description supplies addressing rules, the sold-vs-asking distinction, and the provenance/frequency caveat; only the method parameter and date/limit semantics are left uncovered.

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%, so the description must carry parameter meaning, and it does so thoroughly for area_code/area_type ('W14'+district, 'Camden'+lad, or NATIONAL) and partially for frequency via provenance.pub_freq. However it says nothing about the method enum (hedonic_smoothed vs hedonic_raw), start, end, or limit, leaving four of seven parameters to be inferred.

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 (hedonic ASKING-PRICE index) with its scope (postcode district, local authority, or Great Britain), its source (portal listings, Rightmove ~95%), its base (2022M01 = 100), and its output semantics ('value' is an index level, never a price). It explicitly distinguishes itself from the sold-price sibling market_index_series and from the levels sibling listing_market_series.

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 a concrete use case ('how have asking prices in W14 moved since 2022') plus the rationale for choosing it over the alternative: asking LEADS sold by months and includes stock that never sells, so use market_index_series for sold prices and listing_market_series for levels. It even names the condition that selects quarterly over monthly frequency.

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

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 goes well beyond them with genuinely useful behavior: ONS Price Index validation each build, the ~few-points-a-year disagreement threshold, the rule that a missing recent month is a deliberate refusal rather than an outage ('say so'), and the caveat that `value` is an index level, never a rent. It stops short of describing pagination/limit behavior or smoothing effects, so not a full 5.

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?

Roughly 90 words, front-loaded with the identity and base period before the caveats and alternatives. Information-dense and mostly economical, though the em-dash clauses and semicolon fragments make it slightly harder to scan than it needs to be.

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-format explanation is unnecessary, and the description supplies the crucial interpretive context (index level not a rent, refusal-vs-outage semantics, source validation). The only real shortfall is the unaddressed `method` parameter, which an agent must guess at when the default is unsuitable.

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 description carries the burden. It partially compensates by enumerating the geography options ('one postcode district, local authority or Great Britain') which map onto the area_type enum, and it references shared 'area and frequency rules'. However, hedonic_smoothed vs hedonic_raw is never explained, and start/end/limit formats are undocumented, leaving meaningful gaps.

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 ('Hedonic ASKING-RENT index for one postcode district, local authority or Great Britain'), its source (portal lettings), base period (2022M01 = 100), and outputs (bands and SEs). It explicitly contrasts itself with commercial_rent_index_series and asking_price_index_series, so an agent can route correctly without opening any 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?

Names the alternatives and their selecting conditions: commercial_rent_index_series is the commercial VOA series, and listing_market_series is the tool for rent LEVELS and yields. It also frames the use case as the residential asking-rent index specifically, leaving nothing to inference.

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

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

Annotations already cover read-only/idempotent/closed-world safety, and the description adds real behavioral context beyond them: two-phase 'proposes execution' flow, no paid execution until a proposal is accepted, free to call, and the caution that routing catalogue IDs are not evidence publication IDs. The main omission is any note on latency, limits, or what a proposal response contains.

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 core routing purpose, but the prose is dense, jargon-heavy, and relies on unexplained domain terms ('published taxonomy', 'governed semantic query', 'bounded corporate network/path'), with semicolon-packed clauses that slow comprehension. The final 'Free.' fragment is efficient but the middle sentences do not fully earn their length.

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 described, and the proposal/acceptance model is covered. What is missing is enough parameter-level guidance to call it correctly (required question, optional place_slug) and any signal about how router results should be consumed or cited downstream.

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% for two parameters, so the description must carry their meaning and largely does not: 'question' is never discussed, and 'place_slug' is only obliquely gestured at by 'Route a place/kind'. It does not explain the required/optional split or how a place slug changes routing, which is exactly the gap the empty schema leaves.

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 role — routing a question ('place/kind', 'dated figure', 'exact references') to the right downstream handler, and explicitly distinguishes proposal from execution. The resource is somewhat abstract (a router rather than a data tool), but an agent can tell it is the entry-point dispatcher rather than one of the concrete lookup siblings.

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 category-level triggers (place/kind, dated figure, corporate reference) and notes that it does not execute paid work and requires acceptance of a proposal, which is useful usage context. However, it never tells the agent when to use this router versus calling query_semantic, query_sql, or property_lookup directly — the key selection decision against siblings is left implicit.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: the single shared snapshot date across all AVMs, the fact that the ratio is only a discount where sale and valuation are close in time, the drift of the series to ~0.44 in 2016-2019 being house-price growth rather than deeper discount, and the `min_lots` suppression behavior reported through `meta.sufficient`. This is unusually rich interpretive disclosure for a read-only tool.

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?

The headline and the interpretive warnings are front-loaded effectively, but the passage spends real estate on competitor positioning ('EIG covers 530+ auctioneers to our six and sells API data, but runs no AVM') that does not help an agent select or invoke the tool. Several interpretive sentences earn their place; the marketing framing does not.

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 described, and the description covers the key interpretive pitfalls (temporal alignment, sufficient-sample gating, series drift). It is nearly complete for a 5-param statistical tool, missing only an explanation of `is_commercial` and explicit sibling routing.

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%, so the description carries the full burden and largely delivers: `months` is bounded with a reason (~60), `min_lots` is explained as headline suppression, and `postcode_area`/`postcode_district` are clarified as postcode-based geography rather than area_id. Only `is_commercial` is left unexplained, so it falls short of a 5.

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?

The description states a specific verb+resource: an achieved hammer price against an AVM of the same property, yielding an auction-to-valuation discount ratio. It implicitly separates itself from the sibling auction tools (auction_comps, auction_stats, auction_lots) via the 'valuation join is the product' framing. The competitor comparison and headline stats dilute the core statement somewhat, but the purpose is unmistakable.

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?

It gives clear operational context: read `by_year` before quoting the headline, read `meta.sufficient`, and don't widen `months` past ~60 because that measures the market rather than the auction. However, it never names an alternative tool (e.g. auction_comps/auction_stats) or the condition that would route the agent elsewhere, which keeps it below a 5.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial extra context: the coverage constraint (~1/4 price, ~1/5 yield), the instruction to read meta.coverage so thin results read as thin, and the observation that most auctioneers publish only a guide. That is exactly the behavioural disclosure annotations cannot carry.

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 resource and payload, then unique value, use cases, alternatives, coverage caveat, and parameters. Each section earns its place, though the coverage paragraph is somewhat verbose and the whole definition runs long for a listing endpoint.

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 complex 11-parameter tool with no annotation gaps and an output schema present, the description supplies what the schema cannot: the enum values, the coverage caveat with meta.coverage guidance, and the sibling routing. An agent has enough to call it correctly on the first attempt.

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 coverage is 0%, so the description must compensate. It documents the high-value filters well: with_achieved_price, with_yield, and the actual auctioneer enum values (schema only declares an untyped string), plus ISO date format. It leaves limit, offset, sold_only, is_commercial, postcode_area and postcode_district unexplained, so several of the 11 parameters remain opaque.

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 (individual UK auction lots) and enumerates the payload fields: guide price, sold status, hammer price, net yield. It also distinguishes the dataset from listings portals and from asking-price/private-treaty siblings, so an agent can tell it apart from auction_comps, property_history, or market_volume_series.

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 explicit use cases (achieved outcomes, guide-price realism, yields, district auction behaviour) and an explicit when-not with named alternatives: 'For asking-price or private-treaty sales use market_volume_series or property_history instead'. It also tells the agent to route yield questions to the acuitus auctioneer.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds a substantial data-interpretation caveat not present in any structured field: n_guide and n_achieved are computed over different populations, so differencing them is meaningless. It also explains the `comparable` output flag and prescribes fallback reporting behavior when it is false.

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 one-line purpose, then usage routing, then the critical caveat. Sentences are dense but each carries non-obvious information; the warning block is long relative to the rest, though it is genuinely high-stakes context rather than padding.

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?

With an output schema present, return values need not be re-explained, and the description still adds the key output-semantics note about `comparable`. Scope, time formatting, and geographic limits are covered; the remaining gap is the unexplained is_commercial and limit parameters.

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 coverage is 0% across 5 params, so the description must carry the load. It documents quarter_from/quarter_to format precisely (first day of a quarter, e.g. 2024-01-01) and the geographic scope, but says nothing about is_commercial, limit (default 50), or postcode_district format — three params left entirely to the schema's bare types.

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+granularity: "Quarterly UK auction statistics by postcode district", and enumerates the metrics returned (lots offered, lots sold, sale rate, average guide/achieved/net yield). It explicitly distinguishes itself from auction_lots as the individual-comparables sibling.

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 an explicit positive condition ("the shape of a local auction market over time — is it clearing, are yields moving, is stock rising") and names the alternative tool with the condition that selects it ("For individual comparables use auction_lots"). Also states constraints: UK only, free.

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

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), and the description goes beyond them: it discloses that the £/m² benchmark leg returns `not_available` until a tender benchmark is loaded, that no rate is invented, that nothing is a modelled number, and that an invalid region raises an error enumerating loaded values. That is real behavioral disclosure about sentinels, errors, and provenance.

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, then the output legs, then the estimate mechanics, then the caveat. It is dense but almost every clause carries distinct, actionable information; the three short trailing sentences (not_available behavior, UK only, free) are each independently useful.

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 structure needn't be restated, and annotations cover safety. The description supplies the operative semantics, error/sentinel behavior, and rate provenance. The only real gap is the unexplained `basis` enum, which an agent would have to guess at.

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 schema description coverage at 0%, the description must carry the load, and it does for five of six parameters: sector (index selection), region (enum values plus error behavior), gia_m2, rate_gbp_m2 (BCIS or in-house base rate), and rate_period ("the series' own format, e.g. 2024Q1"). The `basis` parameter (tender/output enum) is never mentioned, leaving one documented enum 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?

The opening clause states a specific verb+resource ("Build cost for a scheme") and enumerates the outputs: sector cost index with 1- and 5-year movement, regional factor, on-cost percentages, and a rate-derived estimate. This is clearly distinguishable from narrower siblings like cost_index or valuation_estimate, which an agent can infer without opening a 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?

It conveys context (UK only, free) and the conditional that triggers the estimate leg ("given gia_m2 and rate_gbp_m2 ..."), which is genuinely useful. However, it never names when to prefer this over cost_index, site_appraisal, or valuation_estimate, so sibling routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, consistent with 'UK only'. The description adds real value beyond that: cost, null-handling for `year_built` and `num_floors`, 0.5 m simplification of the outline, attribution preservation, and the caveat that extrusion is massing-only. However, one important behavioral trait is missing: the description never states any limit on how many UPRNs may be batched per call, so an agent cannot predict the cost or failure mode of a large request.

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?

Three short paragraphs, front-loaded with the resource and its fields, then data-quality caveats, then usage rules. Every sentence is informative, though the extrusion caveats (no facades, no internal boundaries) sit at the tail and could be tighter for a description that is already long.

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; the description instead supplies the operational context an agent needs — geography, cost, prerequisite resolution chain, null semantics, and how to consume the GeoJSON correctly (use building_height_m, not altitude). Nothing material is missing for a single-parameter read tool.

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 coverage is 0% and the sole parameter is a bare integer array with no description, so the description must carry the load. It does much of that: 'a set of UPRNs' conveys batch semantics, 'keyed on a UPRN, not an address' rules out the wrong identifier type, and it points to the tools that produce valid values. It stops short of stating per-call caps or ordering, which is the remaining gap.

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 (physical form of the buildings a set of UPRNs sit in) and enumerates exactly what comes back: height, volume, footprint area, floor count, materials, basement, green roof, solar, unit mix. This clearly separates it from siblings such as energy_profile, solar_potential or property_summary without needing their schemas.

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?

Explicit routing: UK only, keyed on UPRN rather than address, and a named two-step path (free `address_autocomplete` to narrow, then `address_resolve` to obtain the identifier). It also states the cost (15 credits / 15p), letting the agent weigh the call before making it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive context: the cursor is an event id (so late rows never slip behind the watermark), a 14.6M-row feed rejects unbounded reads, cost is 5 credits, and the delisted event type is effectively invisible. Only the return shape of a page (besides event_date/observed_at) is left implicit.

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 core instruction, then layers cursor semantics, coverage caveats, price-field caveats, and cost/prerequisites in a logical order. It is longer than typical but nearly every sentence carries non-obvious information; the bolded delisted warning is worth its 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?

With an output schema present, return values need not be explained, yet the description still clarifies event_date vs. observed_at and price.old_price_source — exactly the fields an agent would misread. Combined with the scope rules and prerequisites, nothing needed to call it 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?

Schema description coverage is 0%, so the description must compensate. It explains cursor (event id, not timestamp), since, postcode_districts, uprns, and even names the event_types values (added, price_reduced, price_increased, status_changed, delisted) — but leaves `limit` and `channel` (with its residential_sale/residential_rent enum) entirely undocumented.

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 and resource — the portal change feed returning what changed since a cursor — and its scope (UK, UPRN-keyed) distinguishes it from siblings like listing_history or property_history. An agent can identify it 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?

Explicitly prescribes the two call patterns (pass next_cursor vs. first call with scope or since), states that unbounded reads are refused, and routes the agent through address_autocomplete (free) then address_resolve to obtain a UPRN. It also names what cannot be answered via coverage.not_yet_fed.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, but the description adds substantial behavioral context beyond them: provenance.method meanings (repeat_sales vs repeat_sales_shrunk), n_pairs as straddle count, thin-quarter blending, empty-series-with-available_sectors semantics, error behavior naming nearest matches for unknown areas, and free/UK-only scope.

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?

Well front-loaded with the core definition and structured with backticked parameter names. It is somewhat long and carries minor filler ('each is real', parenthetical justification about yields moving), but nearly every sentence conveys actionable constraint rather than restating structured data.

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 5-param, output-schema-backed tool, the description covers the series taxonomy, per-param semantics, the local-x-sector gap and its workaround, provenance edge cases, and error/empty-result behavior. An agent has everything needed to call and interpret it correctly without the output schema explaining returns.

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%, so the description carries the burden and does so well for four of five params: area (omit for national, LA name), sector (omit for ALL, accepted values), start/end with concrete accepted formats ('2015', '2015Q1', '2015-Q1', '2015-06') and inclusive end. The `limit` parameter is never mentioned, leaving one gap.

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 and scope: 'Repeat-sales CAPITAL index for UK commercial property, quarterly, 1995Q1 = 100.' It enumerates exactly which series families exist (national ALL, national x sector, LA x ALL), so an agent knows what this returns, and it explicitly contrasts with the rent index sibling. This is not a tautology of the title.

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 explicit when-to-use ('office values in Manchester' → call twice with sector=OFFICE and area=Manchester) and when-not-to-use ('For RENTS use commercial_rent_index_series; the two are not interchangeable'). It names the alternative and the condition that selects it, leaving nothing to inference.

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

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

Far beyond the readOnly/idempotent annotations, it discloses thinness (n_pairs per point, thin_periods), the frequency mismatch (quarterly vs four points in sixteen years), the silent national fallback with the area.index_scope label to check, the 2026-only snapshot nature of rated stock, and non-derivability of RV change on appeal.

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?

Purpose is front-loaded and every paragraph carries distinct information (comparability warning, thinness, fallback behaviour, snapshot caveat). It runs long with heavy capitalization emphasis, but nearly every sentence is load-bearing rather than 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?

For a tool combining three datasets across two incompatible index methodologies, the description covers the caveats an agent needs to interpret results correctly, and the output schema already covers return-shape detail. UK-only and free-to-use scope are stated outright.

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 coverage is 0% and none of the three parameters is described in the schema, so the description must carry the load. It references sector, place and local authority conceptually, but never disambiguates area_key from lad_code, states mutual exclusivity, or gives any expected format.

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?

The description names a specific verb+resource bundle: the repeat-sales capital index, the VOA rating-list rent index, and rated stock standing for a sector and place. It is clearly distinguishable from siblings like commercial_index_series and commercial_rent_index_series because it explicitly says it returns all three together.

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?

It gives strong operational guidance — the two indices must never be plotted on one axis, don't quote a move from thin_periods, and only 19 authorities have a capital series so a missing request silently returns the national series. It does not, however, name sibling tools to use when only one index is wanted, so the routing guidance is implicit rather than explicit.

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

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

Beyond the annotations, it discloses that the tool is UK only, costs 10 credits (10p), returns `not_available` with reasons for underivable blocks, and that the income-basis value capitalises RV at the district's commercial auction net yield with `not_available` where no yield was published. It also warns that RV is a rating measure at the antecedent valuation date, not passing rent — valuable behavioral context that annotations cannot provide.

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?

The description is dense and front-loaded, opening with the report identity and key inputs before detailing outputs and caveats. It is relatively long and packed into a single paragraph with nested parentheticals, so structure could be improved, but most content earns its place for a complex report tool.

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 the tool's complexity, the description is complete enough: it covers scope, geographic limitation, cost, keying requirements, output block behavior including `not_available` reasons, and an important interpretation caveat. An output schema exists, so it does not need to enumerate return fields.

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 coverage is 0%, so the description must carry parameter meaning. It identifies the two lookup keys as UPRN and VOA UARN and emphasizes that the tool is keyed on a UPRN, not an address, with a concrete workflow via address_autocomplete and address_resolve. It does not specify that at least one key is required or explain how to obtain a UARN, but it adds substantial semantics beyond the bare schema.

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?

The description clearly states a specific resource and report scope: a commercial property report keyed by UPRN or VOA UARN, covering rateable value, rent/capital indexes, income-basis value, auction history, owner, and lease. It does not explicitly distinguish this report from sibling tools such as property_report, property_summary, commercial_market, or commercial_index_series, so it falls short of the top score.

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?

It gives clear operational guidance: UK only, keyed on UPRN rather than address, and instructs the agent to use address_autocomplete then address_resolve to obtain a UPRN. It does not explicitly say when to choose this tool over sibling report or market tools, but the prerequisite workflow and cost are well stated.

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

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

Annotations already carry the safe-read profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds material behavior: the index derives from VOA rateable values, not advertised rents or capital values; it moves in four discrete steps; points must be dated by `avd_date` not `list_year`; and it defines error/empty semantics (unknown area is an error, empty `series` with `available_sectors` means the sector is unpublished). That is well beyond the 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-loads the subject (rent index, four points, base year) and then sequences provenance, usage, and per-parameter notes efficiently. It is dense and slightly over-emphatic (all-caps warnings, a repeated 'NOT from advertised rents'), but nearly every sentence earns its place for a tool with a non-obvious index construction.

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 four optional parameters, an output schema (so return shape needn't be explained), and the closed-world read-only annotations, the description supplies everything an agent needs: scope, granularity, date semantics, provenance caveats, and empty/error handling. Nothing material 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 there are no enums, so the description carries the full burden — and it does: `sector` (omit for ALL or a named VOA sector with examples), `area` (omit for national, GSS code 'E08000003' or name 'Manchester' bridged to code), and `start`/`end` (rating-list years, e.g. '2017'). It also adds value beyond the schema for `link_ratio`/`n_constant` output semantics.

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: a commercial RENT index built from VOA rating lists, with exactly four points tied to list antecedent valuation dates and a 2010=100 base. This is sharply distinguished from the advertised-rent and capital-value siblings (asking_rent_index_series, commercial_index_series) without needing to open any 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 strong context for when to reach for it: it covers sectors the repeat-sales capital index cannot (INDUSTRIAL_WAREHOUSE portfolio trades), spans all VOA sectors and 320 local authorities, and is 'UK only. Free.' It warns against monthly interpolation and against quoting without `basis`, but never names a specific alternative sibling to use instead, so it stops short of explicit alternatives/exclusions.

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

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

Annotations cover the read-only/idempotent profile, but the description adds substantial context beyond them: index fallback order (district → local authority →national), the `index_unavailable` carry receipt and no-adjustment outcome, UK-only scope, and a concrete cost of 10 credits (10p). It also flags that the -10% relisting penalty is an assumption, not a measured discount — exactly the kind of caveat 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?

It is front-loaded with the payload and every sentence earns its place, but the central sentence is a ~60-word run-on with stacked parentheticals (index fallback, `index_unavailable`, relisting caveat) that take effort to parse. Splitting that block would cost nothing in content and improve scanability.

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 shape needs no explanation, yet the description still summarises what each comp carries. Combined with cost, jurisdiction, keying, and index-fallback behaviour, an agent has everything needed to call this correctly and interpret the result.

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 coverage is 0%, so the description carries the full burden and does: `relisted_uprns` is reframed as an explicit sensitivity switch with a stated -10% magnitude, `lookback_months` gets an enforced 12–120 range, and `uprn` is qualified as a UPRN rather than an address with the resolution path spelled out.

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?

It names a specific resource (same-building comparable sales with registered price, date, time adjustment, relisting penalty, IQR fence) and explicitly contrasts with `valuation_full`, which 'gives the value itself'. The distinction from `property_comps`/`valuation_comparables` is not drawn by name, but the 'evidence behind a valuation' framing is precise enough to separate it from every other comps sibling.

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?

It tells the agent when to reach for it ('Use it to show WHY a value is what it is'), names the alternative for the value itself, warns to pass `relisted_uprns` only for a deliberate sensitivity rather than a default, and spells out the prerequisite chain (`address_autocomplete` free → `address_resolve` → UPRN).

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, so the description's added value is the period-window inclusivity rule, the series' own date format, and the fact that each series carries its base period and method. Those are genuine behavioral details beyond the annotations, though coverage scope (which years exist) is unstated.

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?

Purpose is front-loaded and the parameter notes are dense but each earns its place. The trailing fragments ('UK-wide; ... UK only. Free.') are slightly choppy but still informative rather than padding.

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?

With an output schema present, return values needn't be detailed, and the description still mentions base period and method. Required parameter, date formats, frequency, and geographic limits are all covered; the only soft spot is the open-ended sector list.

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%, so the description must carry the load, and it does: it enumerates all four basis values matching the enum, gives sector examples, the freq options, and the exact period token formats (2014Q1, 2014M01, 2014) for from_period/to_period that the schema titles alone do not convey.

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?

The description gives a specific resource (construction cost index series) and its domain role ('for a development appraisal's cost side'), and it indirectly distinguishes itself from site_appraisal by noting regional factors are handled there. It does not explicitly differentiate from the closest sibling, build_cost, so it falls short of a 5.

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?

Usage context is clear (cost side of a development appraisal) and constraints are stated: UK-wide, UK only, free. It routes regional work elsewhere ('regional factors come with the site appraisal'), but never states when to prefer build_cost or the other index series siblings.

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

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

With annotations already covering read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral context: declared versus inferred bands, band_source semantics, three intentionally null fields, not_found matching-gap behavior, and coverage limits. These are exactly the details an agent could otherwise misinterpret.

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?

The purpose is front-loaded and most content is high-value warning material. It is longer than average, with several paragraphs and bullets, but nearly every sentence earns its place by preventing misuse or misinterpretation of returned fields.

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 the tool's simplicity, one required UPRN parameter, and an existing output schema, the description is more than complete. It explains geography, workflow, null-field semantics, status behavior, and output meaning without needing to restate the output schema itself.

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%, so the description must carry parameter meaning. It does so by stating the tool is keyed on a UPRN rather than an address and describing how to obtain one via address_autocomplete and address_resolve. It does not specify UPRN format constraints, but it covers the essential meaning beyond the schema's integer type.

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?

The description states a specific verb and resource: retrieves the VOA council tax band for a property from the official list. It clearly distinguishes itself from address-resolution siblings by instructing callers to use address_autocomplete and address_resolve to obtain the required UPRN.

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?

It explicitly defines the geographic scope (England and Wales only, excluding Scotland and Northern Ireland), notes that the tool is free, and explains the correct workflow: use address_autocomplete to narrow and address_resolve to get a UPRN. It also warns not to treat a band as a bill and explains the not_found matching-gap semantics.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds genuinely new operational context: UK-only availability, zero cost, and a full inventory of what the register reports. It does not describe failure modes for invalid area identifiers, which is a minor gap.

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 tool's identity and the 'read before the data' directive, followed by the content inventory. The parenthetical field list is long but each item conveys what the register measures; a small amount of trimming is possible but nothing is truly wasted.

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-format details are unnecessary. Given a one-parameter read-only tool, the description covers purpose, usage timing, input formats, geographic scope, and cost — everything an agent needs to call it correctly.

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 coverage is 0% and the single `area` parameter has no description, so the description carries the full burden. It fully compensates by spelling out three accepted formats: a GSS code (E09000032), a local authority name (Wandsworth), or a warehouse area id, with a concrete example.

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 (read) and resource (data-coverage register for a local authority), then enumerates exactly what it reports: per-field non-null/source shares, designation flags, lease/hereditament counts, planning coverage, and dated listing stock. This is clearly distinguishable from sibling tools like area_stock_profile or area_report, which return the data itself rather than coverage metadata.

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 explicit when-to-use direction: 'read it before the data' and 'State the coverage before quoting a share from a thin field.' It also states scope limits (UK only) and cost (Free). It stops short of naming an alternative tool for when coverage is adequate, but the usage condition is unambiguous.

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

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

Goes well beyond the safety annotations (readOnly, idempotent, closed-world) with behavior the agent could not otherwise know: rows are grouped by ADDRESS not UPRN because flat-level UPRN collapses units, the returned uprn may name a neighbouring unit, and max_guide_to_avm EXCLUDES lots with missing guide/AVM. These disclose non-obvious counting and filtering semantics and the UK-only, free scope.

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 headline and the headline constraint, then the interpretation ladder as a scannable bullet list. The opening line 'both on the public record' is slightly rhetorical and the guide-section is long, but every block carries decision-relevant content rather than 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?

An output schema exists, so return values need no prose, and the description covers counting unit, geography, and the exclusion trap. The remaining gap is the undocumented pagination/scope parameters (limit, offset, years), which an agent must guess at defaults for.

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%, so the description carries the full burden. It explains max_guide_to_avm (with a worked 0.8 example) and pins geography to postcode_area/postcode_district rather than area_id, but leave limit, offset, years, min_auctions and is_commercial undocumented — five of eight parameters have no semantics anywhere.

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 and resource with scope: 'Properties that keep going to auction and NEVER SELL — the distress screen.' This is clearly distinguishable from siblings like auction_lots (all lots) and auction_discount (price fall), and the ranking logic ('failed auctions, then time on circuit') further pins down what the tool returns.

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?

Strong domain guidance: read guide_to_avm first, and an explicit interpretation ladder (above 1.0 = repricing conversation, 0.5-1.0 = worth a call, below ~0.5 = check the lease) that tells the agent both when the output is actionable and when it is a trap. It does not, however, name sibling tools or say when a different auction tool would be the better pick, so routing to alternatives is left to inference.

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

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: percentages are of EPC-holding properties only, whole numbers 0-100, EPCs are lodged on sale/let so long-held and social housing are under-represented and the figure should be caveated, plus 'UK only. Free.' That is exactly the kind of bias/cost disclosure annotations cannot carry.

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 content summary, then the critical parameter routing rule, then the data caveat and scope/cost. Short paragraphs, no filler; every sentence changes how the agent calls or reports the tool.

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?

With an output schema present, return values need no explanation. The description supplies the remaining gaps an agent needs: input provenance, unit semantics, known coverage bias to caveat in reporting, and geographic/cost scope.

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 single parameter is undocumented in the schema, so the description must carry it — and it does, explaining the provenance (marts area id from area_resolve) and the exact disambiguation rule (pass analytics_area_id, not area_id, when both exist). No ambiguity remains.

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?

Names a specific resource (energy composition of an area) and enumerates the exact outputs: EPC band mix, mains gas/electric/oil split, heat-pump penetration. That metric list differentiates it from neighbours like area_stock_profile or property_energy_retrofit without needing to name them.

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?

Tells the agent where the required input comes from ('area_id is the marts area id from area_resolve') and which field to pass when both are returned, plus the UK-only scope. It does not, however, name an alternative tool or state when this should be preferred over the other area/energy siblings.

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

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

Beyond the annotations (which already declare a safe read-only, idempotent operation), the description adds real behavioral context: bounded and eventually consistent results, the caveat that missing links do not imply absence/ownership/off-market status, that no private ownership payloads are returned, and that calls are free. It stops short of describing traversal cost at higher depth or pagination behavior.

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?

Five short, telegraphic sentences that are front-loaded with the purpose statement and each carry distinct information (routing, provenance, consistency caveats, payload limits, cost). No filler, though the clipped style makes a few claims (e.g. 'derived graph') harder to parse than an explicit sentence would.

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 format needn't be covered, and the annotations carry the safety profile. The description usefully adds consistency and provenance caveats, but for a traversal tool with 0% parameter documentation it leaves depth/limit semantics and the choice against sibling traversal tools unaddressed, so an agent still lacks enough to call it confidently.

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%, so the description must carry parameter meaning, and it only partially does: it clarifies entity_id semantics ('canonical ids from search') and hints that results are bounded (relevant to depth/limit). The meaning of 'depth' (default 1, presumably traversal hops) and 'limit' (default 25, presumably max results) is never explained, which are the two parameters that most affect how the tool is invoked.

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?

The description states the resource ('relationship evidence from the derived graph'), which maps to a relationship-traversal tool, but it never says plainly what the tool returns or does — e.g. 'returns entities related to entity_id of a given kind up to depth'. It also does not differentiate itself from siblings like actor_network, actor_path, ownership_by_company or lookup_entities, so an agent must infer the distinction.

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?

'Use canonical ids from search' is an implicit prerequisite routing the agent to the entity-search siblings, and 'Cite path provenance and publication dates' hints at how results should be used. However, there is no explicit when-to-use/when-not versus the numerous relationship-adjacent siblings, leaving selection largely to inference.

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

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

Annotations already declare the full safety profile (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description adds value beyond them by disclosing that the call is "Free" (no cost/rate-limit concern), which affects agent planning.

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?

Two terse sentences with the resource scope first and the call-to-action second. No filler; every clause earns its place.

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-value detail is unnecessary, and annotations cover the safety profile. For a zero-param discovery tool the description is nearly complete, lacking only explicit linkage to the search tools it is meant to precede.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already conveys.

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?

The description states the resource it exposes (governed entity families, criteria, coverage, query limits) and its role as a pre-flight discovery tool. It is clear what you get, though it does not explicitly differentiate itself from overlapping siblings like data_coverage or search_entities.

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?

"Call before building searches" gives explicit, actionable timing guidance that an agent can follow. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without exclusions.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description adds substantial context beyond them: result-count caps, the meaning of a null `retrofit_gap` versus zero, interpretation caveats (habitable rooms are not bedrooms, changes don't prove works), UK-only scope, and that the tool is free and keyed on UPRN.

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 return shape before the caveats, and every sentence carries interpretive value. It is dense and slightly long for a single-parameter tool, but there is little genuine 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?

For a one-param read tool with an output schema and full safety annotations, the description covers the remaining burden: how to supply the key, what a null gap means, how to read the results, and the geographic/scope limits. Nothing needed to call it 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?

Schema coverage is 0% for the single `uprn` parameter, but the description compensates by explaining that the key is a UPRN rather than an address and narrating exactly how to obtain one via `address_autocomplete`/`address_resolve`.

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 (Energy Performance Certificates) for a specific key (a property/UPRN) and the exact return shape ('newest first: up to five mart certificates and up to five raw certificates'). This clearly separates it from siblings like energy_profile, property_energy_retrofit, or property_summary.

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 an explicit prerequisite workflow — call `address_autocomplete` then `address_resolve` to obtain the UPRN — and clarifies that an empty result is a valid answer rather than a failure. It lacks explicit when-not guidance versus other energy/retrofit siblings, so it stops short of a 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description layers on genuinely useful behavioral context: a null gain means no recorded sale rather than zero, the gain is nominal not inflation-adjusted, coverage is UK-only and free. This directly shapes how the result should be interpreted and reported.

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?

Well front-loaded: the positive definition comes first, then the negation, caveat, and routing. The 'saying so is part of reporting it honestly' aside is slightly editorial, but every sentence carries a distinct constraint and nothing is redundant.

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?

With an output schema present, return structure needn't be restated, and the description fills the remaining gaps an agent needs: null semantics, nominal-vs-real framing, geographic scope, cost, and the UPRN acquisition path. Nothing required to call it 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?

Schema coverage is 0% for the lone 'uprns' parameter, so the description must carry the meaning — and it does, clarifying the key is a UPRN rather than an address and pointing to the resolver tools. Minor gap: the schema types the field as an array while the prose speaks of 'a UPRN', leaving batch semantics unstated.

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 computed output: current estimated value against the last recorded sale, expressed as gain in pounds and percent plus holding period. It explicitly negates the nearest misinterpretation (loan-to-value / equity net of debt), which separates it from valuation_estimate and related siblings at a glance.

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 the exact precondition and workflow: keyed on a UPRN, so call address_autocomplete to narrow then address_resolve to obtain one. Also supplies a reporting guideline (call it NOMINAL, don't imply inflation-adjusted real return), which is when-to-use guidance beyond mere invocation.

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

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

Annotations already declare the read-only, idempotent, non-destructive, non-open-world profile, yet the description adds material context those annotations cannot convey: which columns are populated (~2% price coverage, empty rental/EPC/per-m2), the meaning of tx_n and tx_value, and the UK-only, free constraints. This is exactly the data-quality disclosure an agent needs before building a downstream offering.

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?

The critical warning 'DENSITY ONLY' is front-loaded and the sentences are short and skimmable. Minor redundancy between the header warning and the body, but no wasted prose.

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?

With an output schema present the description needn't restate return shapes, yet it still flags the exact data-availability caveat that matters. The main gap is the undocumented area_id/limit inputs, but UK-only, free, and the density-only constraint round out the picture well.

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 neither area_id nor limit is explained in the description. The description's clarifications (tx_n, tx_value) describe response fields, not the input parameters, so it does not compensate for the schema gap.

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 (hex-binned stock and transaction density for map layers) with a precise scope qualifier (H3 resolution 8). Crucially, it differentiates itself from the price-heatmap use case an agent might otherwise assume, so it is distinguishable from siblings like market_yields or valuation_full.

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?

Explicitly warns 'do not offer a price heatmap from this' and leads with 'DENSITY ONLY', which is strong when-not guidance. It stops short of naming a concrete alternative tool for price data, leaving the agent to infer the substitute from the sibling list.

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

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

Annotations already establish that this is a safe, idempotent read, and the description adds substantial behavioral context: returned neighbour fields, the combined block contents, tolerance-based adjacency, ring widening, UK scope, credit cost, and the important distinction that an unowned neighbour means no linked registered title rather than no owner. Nothing conflicts with the 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?

The description is front-loaded with the core purpose, then moves cleanly through return content, addressing, adjacency semantics, caveats, and cost/workflow. Despite being relatively long, every sentence contributes useful operational context.

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?

The tool is complex with eight parameters and no schema descriptions, but the description covers the main identifiers, adjacency controls, output shape, scope, cost, and key semantic caveat. It is nearly complete, with the notable remaining gap being same_owner_only and, to a lesser extent, limit.

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%, so the description must carry parameter meaning, and it does explain the four subject identifiers plus tolerance_m and ring_m. However, it leaves limit and same_owner_only unexplained, and same_owner_only is behaviorally important enough that this is only a partial compensation for the schema gap.

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?

The description states a specific verb/resource: adjacent parcels and their owners, with the combined-site output explicitly named. It distinguishes this from a simple parcel lookup by emphasizing adjacency analysis and aggregate owner/constraint results, so an agent can tell what this tool is for 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?

It clearly frames the tool as the first step in a site assembly, explains how to address the subject parcel, and gives the address workflow via address_autocomplete and address_resolve. It also notes UK-only availability and credit cost, though it does not explicitly state when to choose sibling tools such as parcel_lookup or area_report instead.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavioral context: the rate is weekly and must be converted with 52/12, resolution happens via BRMA rather than local authority, a separate lower shared-accommodation rate applies to under-35 claimants, and three distinct rate-setting bodies exist. This is exactly the beyond-structured-data context an agent needs.

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?

Content is front-loaded with the core meaning and then ordered by importance (unit trap, geography, postcode/room limits, providers). It is longer than strictly necessary — the 52/12 vs 4x arithmetic aside borders on over-explanation — but nearly every sentence carries decision-relevant information.

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 a two-required-param tool with an output schema, the description is complete: it explains input constraints (full postcode, bedroom cap), the meaning of returned fields (rate_unit, brma, shared_accommodation_rate), and the free/no-auth nature. Nothing an agent needs to call it 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it requires a FULL postcode because a district cannot place a BRMA, and notes there is no category above 4 bedrooms, matching the enum values. It doesn't explain the enum labels individually, but the key semantics for both parameters are covered.

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 (retrieve Local Housing Allowance for a postcode/bedroom category) and frames its role concretely: the ceiling on housing benefit and effective rent floor. It also contrasts itself against siblings that provide rent figures (market_facts rental_value, listing monthly_rent), so an agent can place it without opening a 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 clear context for when the figure matters (benefit-funded tenancies, comparing against rent sources) and names the alternatives it should be used alongside. It stops short of explicit when-not-to-use guidance or naming a sibling tool by name, so it is strong but not fully prescriptive.

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

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 still adds non-obvious behavior: cost of 15 credits (15p), a geographic restriction (UK only), and a conditional output rule (`price_trajectory` appears only with at least two priced snapshots). The empty-result semantics are exactly the kind of context annotations cannot express.

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?

Three short blocks front-loaded with what you get, then output caveats, then cost/region/input workflow. No sentence is filler; each carries a distinct, actionable fact.

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?

With an output schema present, return values need not be described, yet the description still flags the one conditional output field and the legitimate empty case. Combined with cost, region, and UPRN acquisition path, an agent has everything needed to call this correctly.

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 coverage is 0% for the single `uprn` parameter, so the description carries the burden and does so well: it states the tool is keyed on a UPRN rather than an address and routes the agent to `address_autocomplete` and `address_resolve` to obtain one. It omits the accepted numeric format, which is only implied by the schema type.

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?

The description names a specific resource (every marketing snapshot for a property) and enumerates exactly what it contains: asking price over time, price reductions, days listed, status changes, agent, image count, floor plan. That content list distinguishes it from generic siblings like property_history or property_lookup without the agent needing to open any 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?

It gives a clear usage context: UK only, keyed on a UPRN not an address, and an explicit two-step prerequisite workflow (`address_autocomplete` then `address_resolve`). It also pre-empts a false-negative interpretation ('no listing at all is a real answer'). It stops short of naming when to prefer a sibling such as property_history or listing_market_series instead.

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

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.

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's real contribution is the data-availability caveat: no exit dates are kept, stock cannot be backfilled, and the series grows one point per day. That is valuable non-obvious context, though it says nothing about the limit/pagination behavior.

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?

Two short paragraphs, front-loaded with the resource and filters, followed only by the caveats that materially affect interpretation. Every sentence earns its place.

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 described, and the temporal caveat is handled thoroughly. The gaps are the undocumented limit and area_type parameters against 0% schema coverage, which leaves the definition slightly short for a 7-parameter tool.

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%, so the description must carry the burden. It clarifies that start/end are YYYY-MM-DD dates and that the series is sliced by area, channel and bedroom band, but leaves limit (default 90 points) and area_type granularity completely unexplained, so several parameters remain opaque.

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 and scope: a daily stock-on-market series for one area, channel and bedroom band, naming the exact measures returned (median age of dated live stock, median asking price/rent, new-build count). This distinguishes it from sibling series tools such as asking_price_index_series or market_volume_series without needing 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 clear context for legitimate use: the series starts 2026-09-05 and a short series is expected rather than missing data, which pre-empts a common misreading. It does not name alternative tools or state explicit exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: result ordering by gain, the commercial cost (40 credits / 40p) and the UK-only scope. It says nothing about pagination or the effect of the limit parameter, which keeps it short of a 5.

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 cohort definition, then a concrete illustrative output line, then the parameter note and hard constraints. Every sentence contributes something an agent would otherwise have to guess, with no padding.

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 shape needs no prose (the example is a bonus, not a substitute), and annotations cover safety. What remains thin is the tuning of `limit` and the thresholds behind min_years/min_gain_pct — for a 4-parameter query tool with 0% schema coverage, that keeps it at a 4 rather than a 5.

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 four parameters, so the description carries the burden. It does resolve the most error-prone one — `area_id` is the marts area id from `area_resolve` — and the cohort framing implicitly explains min_years (long-held) and min_gain_pct (high equity). `limit` and the actual defaults (10 years, 50%) are never mentioned, so compensation is partial.

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?

The description defines a precise cohort (long-held properties carrying a large paper gain, i.e. the off-market segment) and states the ordering rule explicitly: 'ordered by gain rather than by value.' That ordering detail alone separates it from the many sourcing_* and valuation_* siblings, so an agent can pick it 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?

It gives clear context signals — UK only, 40 credits, and that `area_id` must come from `area_resolve` — which is prerequisite guidance an agent needs. However, it never states when to prefer this over overlapping siblings such as sourcing_offmarket_owners or sourcing_owners, nor any exclusion beyond geography, so usage is implied rather than directed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral detail beyond them: exact/lexical lookup with no model or embeddings, token-prefix support, bounded typo tolerance, and the coverage caveat about unsearched families. The 'Free' note is a useful cost signal. Slight overlap with the output schema on return structure keeps it from a 5.

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 accepted inputs, then alternatives, then caveats; no filler sentences. It is dense and runs long, but nearly every clause carries routing or behavioral information.

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?

With an output schema present, return values need not be described, and the description covers routing, lookup semantics, coverage limits, and cost. The only real gap is the limit parameter's behavior and whether it applies per-family or overall.

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 coverage is 0%, so the description carries the burden. It does clarify what q accepts (title/address text, postcode, UUID, prefixes, typo tolerance), which is genuinely useful. However, 'limit' is never mentioned, and its interaction with the 'separate families' result structure is left 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 and resource (find public records) plus the accepted key types (title/address text, postcode, public UUID). It also names the sibling tools it is not (address_autocomplete, address_by_uprn, search_entities), so an agent can route without opening any 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?

Explicit when-to-use-this and when-to-use-an-alternative: full address matching goes to address_autocomplete, a UPRN goes to address_by_uprn, attribute criteria go to search_entities. It also states the negative case (an unlisted family was not searched, no match does not prove nonexistence).

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

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

Annotations already cover the safety profile (readOnly/idempotent/destructive=false), but the description goes far beyond them: it names the null metrics, warns that imputed rows are borrowed priors that look real, gives the tx_decision distribution, and cites the repeating-353,909 tell. This is exactly the kind of behavioral context annotations cannot carry.

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 one-line purpose and grain before the caveats, and each paragraph covers a distinct failure mode (null metrics, imputation, geography grain, rollup absence, truncation). It is long and repeats the 'don't rank on nulls / aggregate instead' idea, but the length is largely justified by 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?

For an 11-parameter cube reader with an output schema present, the description supplies everything needed to call and interpret it: grain, valid geographies, the tx_decision evidence ladder, and the response fields (period_frequency, periods_returned, truncated, metrics_with_no_data). Only h3_cell is left unexplained, which is minor.

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 0% schema description coverage the description must carry the params, and it does: postcode resolves to district (no sector/unit grain), lad_code is a NAME not a GSS code, max_periods defaults to 3 and bounds monthly periods, and period semantics are explained. Gaps remain — h3_cell is never mentioned and the accepted values of `metrics` are only implied by the populated/null list.

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 precise verb+resource+grain: what it returns (sales_price, price_psm, turnover_rate) and the exact cube grain (geography × asset class × bedroom band × period). It also names the sibling tools it is not (market_ranking for area comparison, market_volume_series for counts), so an agent can route without opening another 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?

Explicit when-to-use and when-not: 'To compare AREAS against each other use market_ranking, not repeated calls here' and 'For "how many sales" use market_volume_series'. It further states that LSOA/ward selectors return 422 and that there is no rollup row, removing the most likely mis-invocations.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond them: the hard horizon ceiling of seven periods, the settled-index anchor, the method (smoothed repeat-sales index), and the explicit disclaimer that this is not a property valuation, which guards against misuse as an appraisal tool.

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 what is returned, then constraints and caveats; roughly 70 words with no filler sentences, and the terse 'UK only. Free.' is efficient. The phrase about the smoothed repeat-sales index is slightly ornamental but earns its place as a misuse guard. Minor redundancy between 'the horizon the index publishes' and 'nothing beyond it is offered'.

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 described, and the bands, anchor and horizon limit are all covered for a read-only forecast tool. The remaining shortfall is on the input side: with 0% schema coverage, the description should specify the area_code format and what monthly vs quarterly changes about the series. Otherwise an agent has everything needed to call the tool correctly.

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%, so the description carries the load. It partially compensates: 'postcode district or local authority' maps to the area_type enum, and 'up to seven forecast periods' documents the horizon cap, while 'publication grain' loosely gestures at frequency. It says nothing about the expected format of area_code (GSS code vs postcode) or the distinction between monthly and quarterly frequency, leaving two of four parameters ambiguous.

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+output shape: a published house-price index forecast for a postcode district or local authority, anchored on the last settled index point with up to seven banded periods. It also implicitly separates itself from valuation tools by noting the forecast is a projection of the smoothed repeat-sales index, not a property valuation. It never names the closest sibling (market_index_series / asking_price_index_series) explicitly, so it stops short of full sibling differentiation.

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?

The description states hard constraints — UK only, free, horizon capped at seven with nothing beyond offered — which effectively tells the agent when the tool is in scope. However, it gives no explicit guidance on when to prefer this over the historical index tools (market_index_series, asking_price_index_series) or what to do if a forecast is unavailable for an area. Usage is implied by 'forecast' rather than directed.

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

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.

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral value beyond that: unpublished measures are returned as null with the reason, never zero, and there is no cohort HPI (only whole-area, explicitly labelled). That null-vs-zero contract is exactly the kind of disclosure that prevents misreading results.

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?

The bulk of this single run-on sentence enumerates return fields — indexes, agent concentration, days to completion, SearchQuery links — which an output schema already provides, so many tokens do not earn their place. The input-relevant facts (window default, id sourcing, null semantics) are buried mid-stream rather than front-loaded.

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 is present, the description need not restate returns, yet it ensures the agent understands the result contract (nulls with reason, no cohort HPI, index coverage) plus how to obtain the required id. Nothing an agent needs to call this 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?

Schema description coverage is 0%, so the description carries the full burden — and it largely meets it: `window` is defined as the number of months the series is sliced to (default 60), and `profile_id` is sourced from search_entities with entity market_profiles. Neither parameter is left to guesswork, though no format or validity constraints are given.

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?

The description states a specific resource — a single market profile for an area × bedroom cohort — and enumerates the categories of measures it returns, so the purpose is unambiguous. However, it never names or contrasts itself against close siblings such as area_report, market_facts, or market_yields, leaving the agent to infer differentiation.

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?

It provides one genuinely useful usage fact: profile_id comes from `search_entities` with entity `market_profiles`, and it notes the call is 'Free'. But there is no guidance on when to choose this over the many related market siblings, nor any exclusion criteria.

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