MarketCode

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond that: credit cost (15, and an unpublished root is free), an authentication constraint, truncation signaling, a warning that missing links are not negative findings, and that individuals are excluded. This is exactly the extra behavioral detail 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?

Purpose is front-loaded, then caveats and costs follow in terse sentences with no filler. It is dense and slightly telegraphic, but each sentence carries information an agent needs.

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 explanation is unnecessary, and the description covers cost, auth, network limits, and interpretation caveats. The main gap is the undocumented kind enum and entity_id, which leaves the primary input under-specified.

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 clarifies depth (1–3) and the node cap tied to limit (≤100 nodes), but leaves the 7-value kind enum and entity_id entirely unexplained in both schema and description, so half the 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 verb and resource with scope: "Investigate recorded corporate ownership, title and agency relationships." Clear what the tool returns (a relationship network around an entity). However, it does not name the near-sibling actor_path or the ownership_by_* tools, so an agent must infer the boundary between this and other relationship tools.

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 operational conditions (authenticated account required, no anonymous preview key, depth 1–3, ≤100 nodes) but never states when to pick this tool over actor_path or entity_relationships. Usage is only implied from the ownership/agency framing.

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 closed-world, so the safety profile is covered. The description adds genuinely new behavior: a 15-credit cost and the important caveat that a clipped search yields incomplete results rather than a negative claim. It does not explain how depth/limit clipping actually works, which is the other half of that caveat.

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 sentences, each carrying distinct information: purpose, prerequisite, clipping caveat, return shape, cost. Constraint and purpose are front-loaded with 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, and cost/prerequisite/caveat are covered. The gap is parameter documentation: with 0% schema coverage, an agent has no guidance on what depth and limit do or how they interact with the stated three-hop bound.

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 six parameters (depth, limit, source_kind/id, target_kind/id) are defined. The only trace is 'within three hops', which loosely maps to the depth default of 3. For a zero-coverage schema the description should carry this burden and largely does not.

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?

Specific verb+resource+scope: 'Find a recorded path between two corporate-network records within three hops.' An agent can distinguish this from a generic graph query. However, it never names the closest siblings (actor_network, entity_relationships), so the boundary 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?

It gives one prerequisite ('Requires the customer's account') but no when-to-use guidance or alternatives. With actor_network and entity_relationships in the sibling set, the description should say when a between-two-nodes path query is preferred over a network expansion.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description's only incremental disclosure is pricing ('Free'), which is genuinely useful but thin; no rate limits, result caps, or pagination behaviour are mentioned.

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, both front-loaded and information-bearing, with zero filler. Nothing could be cut without losing meaning.

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 single-parameter lookup with an output schema present, the description need not explain return shape. It is adequate, though it omits postcode formatting expectations and any result-volume caveats that would matter for a bulk address lookup.

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 parameter has no description, so the burden falls on the prose. The description adds only the qualifier 'UK postcode', which is useful format context but nothing about normalisation, spacing, or partial-postcode behaviour.

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 ('Return all addresses at a UK postcode'), so the operation is unambiguous. It does not, however, differentiate itself from close siblings like address_by_uprn, address_autocomplete, or address_resolve, so an agent must infer the boundary.

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?

Beyond the cost signal 'Free', there is no when-to-use guidance, no mention of when to prefer address_by_uprn or address_resolve, and no prerequisite (e.g. postcode format or coverage limits). The agent gets no routing help.

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 marginal value is the "UK only" coverage boundary, the "Free" cost signal, and the crucial warning that the key is a UPRN rather than a free-text address. It doesn't discuss return shape or error behavior, but output schema exists so that is largely covered elsewhere.

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 fragments, zero filler: purpose, cost/scope, then input semantics and escalation path. The routing instruction is front-loaded in the same breath as the key constraint.

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 single-parameter, read-only lookup with a published output schema, the description supplies everything an agent needs: scope, cost, what the key is, and how to obtain it. 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 coverage is 0% and the only property is a bare integer named "uprn", so the description carries the burden — it clarifies that the value must be a UPRN identifier and points to address_resolve as the way to procure one. It stops short of describing the UPRN's format or numeric range, 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 verb and resource ("Look up an address by UPRN") plus a geographic scope constraint ("UK only"). It also explicitly distinguishes its input from address-based siblings, so an agent can tell it apart from address_autocomplete and address_resolve 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?

Gives an explicit routing recipe: use address_autocomplete to narrow, then address_resolve to obtain the UPRN this tool requires. This names the alternatives and the condition that selects them, 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the 'Free' cost note and 'canonical record' framing; it does not disclose match-count behavior, region coverage limits, or what happens on no-match/ambiguous input. Adequate but thin against the annotation baseline.

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?

A single front-loaded sentence with no filler; the core action and canonical output are stated first. It is terse rather than padded, though the terseness comes at the cost of the missing details noted elsewhere.

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 annotations cover safety. Still, for a resolver that can return multiple candidates (max_results defaults to 5) and is UK-scoped by default, the description should say something about multiple matches and whether non-UK addresses are supported.

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 three parameters. The description covers 'free-text address' (query) and implies a UK scope for country, but max_results is entirely unexplained and no format/default behavior for country is given. For a 0%-coverage schema the description should compensate, and it largely does not.

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') and resource ('free-text address to canonical record (UPRN)'), and the 'free-text' qualifier meaningfully separates it from address_by_postcode and address_by_uprn. It does not, however, mention address_autocomplete, the closest sibling, so sibling disambiguation is incomplete.

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?

'Resolve free-text address' implies the input situation (raw text with no postcode/UPRN yet), and 'Free' hints at cost considerations, which is why one would prefer it over a paid lookup. But there is no explicit when-to-use/when-not statement or named alternative such as address_autocomplete or address_by_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 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 cover safety (readOnly, idempotent, non-destructive), and the description adds non-obvious behavior on top: the per-call credit cost, UK-only scope, and the exact degradation semantics (unsupplied half reads `not_available` with a reason rather than empty, plus the sections_degraded signal). This is context the 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?

Front-loaded purpose sentence, then a clearly emphasized scope warning, then operational notes (degradation check, region, cost). Structure is excellent and nearly every sentence earns its place; the description is a touch long, but the complexity of a multi-source composite report justifies most of it.

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 composite report tool with an output schema already documenting return shape, the description supplies the missing pieces: region constraints, cost, scope keying, and the interpretation guidance for sections_degraded. Nothing needed to invoke it correctly is absent aside from the sector value set.

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 explain parameters, and it does so for the two critical keys: lad_code is a GSS local-authority code (with a resolver pointer) and postcode_district drives the listing lane, and it stresses they are not interchangeable. The `sector` parameter (default 'ALL') receives no explanation of accepted values, leaving one of three params 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 composed artifact and enumerates exactly what it contains (sourcing readiness, commercial capital and rent indices, planning decision record, live listing stock). An agent can distinguish this composite document tool from siblings like market_profile or commercial_market 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?

Gives strong operational context: UK only, 25 credits, use area_resolve to obtain a lad_code, pass both scopes to fill every section, and check sections_degraded before calling the document complete. It references property_report for shared behavior but does not explicitly state when to prefer this tool over a narrower sibling, keeping it short of a full 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, 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds substantial context: credit cost, null-rather-than-estimated semantics for year_built/num_floors, which height field to use, attribution preservation, and explicit limits of what the extrusion shows. That is behavior well 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?

Front-loaded with what is returned, then caveats, then the boundary/cost/input-key rules. Every sentence carries a distinct, actionable constraint; nothing is restated from the schema or annotations.

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 single-param, read-only lookup the description covers inputs, cost, coverage, null handling, field-selection pitfalls, and rendering caveats. An output schema exists, yet the field enumeration still usefully frames the response; 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% and there is 1 required param, so the description must carry the meaning — and it does, clarifying that the key is a UPRN (integer identifiers for buildings) and not an address, plus how to obtain valid values. It stops short of stating format/plurality expectations for the array itself.

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 buildings a set of UPRNs sit in) and enumerates the exact attributes returned (height, volume, footprint, floors, materials, basement, green roof, solar, unit mix). An agent can distinguish this from near-neighbours like property_summary or 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?

Explicitly says it is UK-only, costs 15 credits, and is keyed on a UPRN not an address, then names the exact pipeline: address_autocomplete (marked free) to narrow, then address_resolve to obtain the UPRN. This is when-to-use, prerequisite, and alternative in one passage.

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 (readOnly, idempotent, non-destructive) cover the safety profile, and the description adds substantial non-obvious behavior: the cursor is an event id not a timestamp, late rows take higher ids, empty pages must be checked against coverage.event_types, delisted effectively has no coverage, price change source semantics, and that null means unknown rather than zero. It also gives cost (5 credits) and UK-only scope. The only reason it isn't a 5 is that a couple of behavioral edges (pagination/limit behavior) are 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-loaded with the core mechanism, then layers caveats in a logical order. It is on the long side and uses emphasis/bold for the delisted warning, but nearly every sentence carries decision-relevant information 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?

Given a read-only feed with 7 params, zero schema coverage, and an output schema already present, the description supplies the missing piece: coverage limitations an agent must respect before trusting results, plus the scoping precondition and sibling routing. Nothing essential for correct invocation 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 description coverage, the description carries the load and largely succeeds: it defines the meaning of cursor (event id, from previous call), since, uprns, and postcode_districts. However it references the cursor as 'next_cursor' while the schema field is 'cursor', and it never explains the limit or channel parameters, so compensation is thorough but not complete for all 7 params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'What changed since you last looked — the portal change feed.' It names the cursor-driven feed precisely, and the surrounding text makes clear this is a change/event feed rather than a static history tool (property_history, listing_history). An agent can place it against siblings 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?

Explicit when-to-use mechanics: pass next_cursor for incremental reads, or supply a scope (postcode_districts/uprns) or since date on a first call because unbounded reads are refused. It also routes to siblings ('call address_autocomplete (free) to narrow, then address_resolve to get one') and states the cannot-answer cases, which is genuine when-not 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 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds cost (10 credits), UK-only scope, `not_available` behavior for underivable blocks with reasons, and an interpretation caveat that RV is a rating measure at the antecedent valuation date, not passing rent. These are valuable behavioral disclosures beyond 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 appropriately sized for a complex multi-block report and every sentence carries information, but the first sentence is a long run-on enumerating report blocks, and the critical routing instructions (keyed on UPRN, call address_autocomplete) are placed at the end 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 a rich output schema, the description needn't detail return values, yet it still outlines report blocks and not_available reasons. It covers scope, cost, keying, and interpretation, though the parameter requiredness/selection ambiguity remains a gap for correct invocation.

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 neither parameter has a schema description. The description names 'UPRN' and 'VOA UARN' and explains that the tool is keyed on UPRN and how to obtain one, but does not state whether one or both are required, what happens if both are supplied, or define UARN beyond the acronym. It adds partial meaning but leaves invocation ambiguity.

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 report keyed on UPRN/UARN and enumerates the report blocks (RV, sector indexes, income-basis value, auction history, owner, lease), so the agent knows what the tool produces. However, it does not explicitly distinguish this report from sibling tools that also expose commercial indexes or market data (e.g., commercial_index_series, commercial_market), leaving sibling selection partly implicit.

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 states UK-only scope, 10-credit cost, and the prerequisite workflow: call address_autocomplete (free) then address_resolve to obtain a UPRN, because the tool is keyed on UPRN not an address. It does not say when not to use this report or name alternative report tools, so it has 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 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 already cover the read-only/idempotent safety profile, and the description adds material context beyond them: the 10-credit cost, UK-only coverage, the repeat-sales index fallback chain (district → local authority → national), the `index_unavailable` carry-receipt behavior, and an explicit disclosure that the -10% relisting penalty is an assumption rather than a measured discount.

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 outcome ('The evidence behind a valuation, itemised') and every clause earns its place, but the return-value, penalty, fence, cost, coverage and prerequisite facts are compressed into one dense paragraph of nested parentheticals that is 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?

For a 3-param read-only tool with an output schema, the definition supplies everything an agent needs to call it correctly: identity key, optional-param semantics, range limits, cost, geographic scope and the prerequisite lookup path. The output schema handles the return shape, and the description still usefully previews it.

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 does: uprn is 'keyed on a UPRN, not an address' with the route to obtain one; relisted_uprns gets meaning, the condition to pass it and its assumption status; lookback_months gets an explicit 12–120 range not present in the 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?

States a specific verb+resource ('same-building comparable sales ... itemised' with time adjustments) and explicitly distinguishes itself from the sibling `valuation_full` ('gives the value itself'). An agent can tell this apart from valuation_comparables, property_comps and time_adjustment 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 ('show WHY a value is what it is') with the named alternative ('valuation_full gives the value itself'), plus a prerequisite workflow (address_autocomplete → address_resolve to obtain a UPRN) and a conditional rule for when to pass relisted_uprns. Nothing 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 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 cover read-only/idempotent/non-destructive safety, and the description adds substantial extra context: 10-credit cost, UK-only scope, the buffered adjacency definition (strict touch finds nothing), the semantic caveat that 'no owner' means no linked title rather than nobody owns it, and the UPRN keying 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?

Dense but front-loaded, starting with what it returns before the mechanics and caveats. Every sentence adds information, though the definition runs long and the workflow sentence packs the cost/UK/keying facts together.

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 eight-parameter aggregation tool, the description is complete: it covers identifier options, adjacency math, the high-level return shape (per-neighbour fields plus the combined block), caveats, cost and jurisdiction. An output schema exists, yet the description still orients the agent on what the combined block contains.

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 compensates well, explaining parcel_id/inspire_id/title_number/uprn as mutually exclusive subject identifiers, tolerance_m semantics (0.5 m default, why it exists) and ring_m control. However, limit and same_owner_only are never explained, leaving two of eight parameters 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+resource: returns the parcels adjacent to one subject and who owns each, plus a combined assembly block. An agent can immediately tell this apart from parcel_lookup or owner_profile, and the description even routes to address_autocomplete/address_resolve for keying.

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 frames the tool as 'the first question of a site assembly' and gives a concrete pre-workflow (address_autocomplete free, then address_resolve to obtain a UPRN). It also tells the agent how to widen scope with ring_m and how to address the subject via four alternative identifiers.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds materially more: a cost of 15 credits, the UK-only constraint, the conditional emission rule for `price_trajectory` (only with two-plus priced snapshots), and the semantic that an empty result is a valid answer rather than an error. None of this is recoverable 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 resource and its contents, then constraints, then the routing instruction. Every sentence carries distinct information (scope, cost, conditional field, empty-result semantics, acquisition path) with 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?

For a single-parameter lookup with an output schema present, the description supplies everything an agent needs: what the resource is, the geographic limit, the credit cost, the key format and how to derive it, and how to interpret a null 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% and the single parameter has no description in the schema, so the description must carry the load — and it does, explaining that the key is a UPRN rather than an address and how to obtain one via address_autocomplete/address_resolve. It stops short of describing the UPRN's format or integer type, so it is not fully exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Every marketing snapshot for a property') and then enumerates exactly what is returned — asking price over time, reductions, days listed, status changes, agent, image count, floor plan. This is clearly distinguishable from siblings like property_history, property_media or 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 explicit prerequisites and a workflow: 'Keyed on a UPRN, not an address: call address_autocomplete (free) to narrow, then address_resolve to get one.' It also pre-empts a false-negative by stating no listing is a real answer, and scopes the tool geographically (UK only).

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: a credit cost, a UK-only constraint, and the gain-based ordering. It doesn't disclose pagination or result-size behavior, which limits it to a solid 3.

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 cohort definition and ordering rule, then a concrete output illustration, then the prerequisite/constraint/cost facts. Every sentence carries distinct 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?

An output schema exists, so return values need not be described, and the behavioral facts (cost, geography, prerequisite, ordering) are present. However, with 0% schema coverage and three undocumented parameters, an agent still lacks the meaning of min_years, min_gain_pct, and 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% across four parameters, so the description carries the full burden. It only clarifies area_id (its source is area_resolve); limit, min_years, and min_gain_pct are left entirely unexplained in both schema and prose, even though their concepts underpin the tool.

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 precise cohort (long-held properties in an area carrying a large paper gain), a specific ordering rule ('ordered by gain rather than by value'), and frames it as the 'classic off-market cohort.' An agent can distinguish this from siblings like equity_estimate or sourcing_offmarket_owners from the text alone.

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 names the prerequisite (area_id comes from area_resolve), scopes geography ('UK only'), and discloses cost ('40 credits'). It never explicitly names an alternative tool or a when-not-to-use condition, 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 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.

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context beyond them: the need to report the `window` block, why `lag_months` exists (registration lag), which metrics are exact vs. weighted means, that `min_stock` guards against tiny-stock distortion, and that gross_yield/days_on_market are 0% populated so sorting on them yields arbitrary order.

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 sibling routing before the caveats, and every paragraph carries non-redundant information (window reporting, metric caveats, sort warnings). It runs long and leans on capitalization for emphasis, but the density earns the 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-shape explanation is not needed, and the description instead covers the behavioral traps an agent would otherwise hit (lag, min_stock, unpopulated metrics, indicative vs. exact metrics). The gap is undocumented parameters like `hmo`, `limit`, and `order`, but for this complexity the description is nearly 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 coverage is 0% across 13 parameters, so the description must carry the load. It meaningfully documents `sort` (defaults to turnover_rate), `min_stock` (default 50), `lag_months` (default 3), `area_type`, and the parent_area_code/area_codes scoping choice, but leaves `hmo`, `limit`, `order`, `metrics`, `asset_class`, and `bedroom_band` entirely unexplained. Partial compensation on a wide-param tool justifies a 3.

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 states a specific verb and resource with scope: 'Rank areas AGAINST EACH OTHER on a market metric — one row per area, AGGREGATED over a trailing window of whole months.' It then names the siblings it differs from (`market_facts`, `market_volume_ranking`), so an agent can distinguish it 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 with worked examples ('which districts in Greater Manchester turn over fastest'), an explicit alternative and why (`market_facts` in a loop is slower, costs more, mixes periods), and an explicit exclusion ('Distinct from `market_volume_ranking`, which ranks on raw transaction COUNT'). Nothing 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.