UK Data: England listed buildings

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

Annotations already declare readOnly, idempotent, open-world and non-destructive behavior, so the bar is lower. The description adds real context beyond them: the authoritative source (Historic England Register of Historic Battlefields), a coverage limitation (registered sites in England only), and a per-call cost of 1 credit.

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 compact paragraph that front-loads the verb and resource, then layers source, scope and cost. Every sentence carries information, though the audience clause is the weakest and could be trimmed without loss.

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 two-parameter read-only lookup with no output schema, the description is nearly sufficient: it names the dataset, enumerates returned fields, states the geographic/registration scope limit and the credit cost. Only pagination behavior and how name matching works are unstated, which are minor gaps.

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 100%, so both parameters (name substring, limit 1-100 default 25) are already fully documented. The description's field list describes return values rather than adding syntax or semantics for the inputs, so it contributes nothing beyond the schema; baseline 3 applies.

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 ('List or search England's registered historic battlefields') and enumerates the returned fields (name, battle year, date registered, area, grid reference, link). It also carves out scope against the many heritage siblings by noting it covers only registered battlefield sites in England, not every recorded battle.

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?

Offers audience-level context ('for history fans, schools and walkers asking where a battle was fought'), which implies when the tool is useful. It never names an alternative (e.g. scheduled_monument_search, protected_wreck_search, historic_park_garden_search) or states when not to use it, so routing between the similar heritage tools is left to inference.

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

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

Annotations already declare readOnly, idempotent and openWorld, so safety is covered; the description adds the data source (Historic England NHLE), the name-match-only retrieval constraint, the coverage boundary, and a cost of 1 credit. That is useful context beyond the annotations, though it says nothing about result ordering or truncation 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?

Front-loads the search action and returned fields in the first clause, then layers audience, caveats and provenance compactly. The trailing parenthetical credit note and source attribution are slightly scattered but each 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?

For a two-parameter read-only lookup with no output schema, the description supplies the returned field list, the source, and the key scope limitation. Minor gaps remain around result ordering and what happens on zero matches, but an agent has enough 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 100% and already documents the name substring with case-insensitivity, length bounds and an example, plus the limit range and default. The description only restates 'by name', adding no matching semantics beyond the schema, so baseline 3 applies.

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 (Search) and a precisely named resource (England's Register of Parks and Gardens of Special Historic Interest), plus the fields returned (grade, date registered, area, official link). The named register distinguishes it from the other heritage-listing siblings such as listed_building_search and scheduled_monument_search without needing to mention 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?

Gives clear context ('For garden visitors, estate owners and planners') and a genuine exclusion ('Name match only; covers registered landscapes, not every public park'), which tells an agent when not to use it. It stops short of naming an alternative tool for public parks or for spatial queries.

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), so the description's job is to add operational context and it does: a credit cost of 1, the authoritative source, and an explicit negative-result contract ('found: false' for scheduled monuments, parks, battlefields, wrecks) that tells the agent how failure looks rather than erroring. No mention of latency, rate limits, or whether found:false costs a credit, which keeps it off 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?

Effectively two dense sentences plus a source tag and a cost tag. The identifier format is front-loaded, the payload list follows, and the scope caveat lands last. Parenthetical cost and provenance are compact and 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?

For a single-record lookup with no output schema, the description covers everything the agent needs: what identifies the record, what fields return, which registry backs it, what happens on a wrong-domain number, and the credit price. No output schema exists, and the returned fields are enumerated inline, so there is no gap left for the agent to discover at call time.

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 100%, so the baseline is 3; the description earns an extra point by explaining what the number actually is — a 7-digit NHLE reference originating in conveyancing and planning papers — which helps the agent recognise a valid value in hand versus a name or address. It does not restate the example or the integer/string nuance the schema already documents, which is the right restraint.

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 one listed building'), names the exact identifier ('NHLE list entry number'), and enumerates what comes back (name, grade, listing and last-amended dates, grid reference, official link). It also names the source dataset, so the agent knows exactly which registry this hits.

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?

Makes the prerequisite explicit — you need a 7-digit NHLE number, the reference found in conveyancing and planning papers — and states the boundary condition that non-building designations return found: false, which effectively routes the agent to the monument/battlefield/wreck siblings. It stops short of naming the sibling tools (e.g. listed_building_search for query-based lookup when no number is known), so the alternative path is implied rather than spelled out.

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' read-only, idempotent, open-world safety profile, it discloses the Historic England source, a 1-credit cost, name-matching behavior, geographic and designation limits, and the principal returned fields. These details materially help an agent predict what a call will do and what it cannot establish.

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 action and outputs are front-loaded, followed by use case, source, matching constraints, exclusions, and cost in a logical order. Although the final scoping sentence is dense, each statement earns its place and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search, the definition covers provenance, outputs, search semantics, geographic coverage, important exclusions, and cost, while the schema covers input syntax and result limits. Listing the returned fields is especially valuable because there is no output schema; only explicit routing to sibling tools remains as a minor improvement.

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 100%, so the baseline is already adequate, but the description adds useful meaning for “name”: it is the list entry name as written at listing, often an address or building name, rather than a general street-address query. It adds nothing for “limit,” though the schema already documents that parameter sufficiently.

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?

“Search England's listed buildings by name” gives a specific verb, resource, geography, and search mode, followed by concrete outputs such as list entry number, grade, and grid reference. The by-name framing helps distinguish it from listed_building_lookup, while the heritage-scope exclusions distinguish it from other protected-site searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear use case—homebuyers, conveyancers, builders, and planners asking whether a building is listed—and explicit when-not boundaries: England only, list-entry-name matching rather than general street-address search, and no conservation areas or local lists. It would be stronger if it directed users with a known entry number to listed_building_lookup or named alternatives for other heritage designations.

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, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that: the credit cost, the upstream source (Historic England NHLE), the legal-offence context that motivates lookups, and an important data caveat that the position is a reference point and not the restricted-area boundary. It does not describe result ordering or pagination behaviour, which keeps it below 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-loads the resource and scope, then moves through returned fields, audience, source, caveats and cost in a logical order with no filler sentences. It is dense rather than bloated, though the trailing parenthetical cost note and the legal sentence sit awkwardly in one unbroken block that would read better split.

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 no output schema, the description carries the burden of describing return values and does so by naming the fields returned. For a two-parameter read-only lookup, the combination of scope limits, data source, positional caveat and credit cost leaves nothing an agent needs missing before calling 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 100% and both parameters are already documented there, including the 'omit to list all' behaviour for name and the 1-100 range with default 25 for limit. The description adds no matching semantics, spelling/tokenisation hints, or search behaviour for partial names, so baseline 3 applies.

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 pair ('List or search') and a precise resource ('wrecks designated under the Protection of Wrecks Act 1973 in English waters'), then enumerates the returned fields (name, designation date, restricted area hectares, position, official link). It also explicitly bounds the dataset against near-neighbours ('not all wrecks or military remains'), so an agent can separate it from sibling heritage tools like battlefield_search or scheduled_monument_search.

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 context ('divers and boat users check here') and an explicit exclusion ('covers designated wrecks only, not all wrecks or military remains'). What it lacks is any explicit routing to alternative tools for non-designated wrecks or military remains, so the agent must infer the alternative rather than being named one.

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, open-world behavior, and the description layers on genuinely additional context: the Historic England NHLE source, a credit cost, the name-match-only recall limitation, and the legal significance of scheduling. The negative-result warning is exactly the kind of behavior an agent cannot infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what is searched and returned, then adds source, limitation, and cost — all earning their place. The audience sentence ('For landowners, detectorists, developers and walkers') is the least essential and slightly pads the middle.

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 no output schema, the description compensates by listing the return fields (list entry number, date scheduled, area, grid reference, link) and by disclosing source, cost, and coverage limits. An agent has everything needed to call it and interpret empty results.

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 100%, and the schema itself documents case-insensitivity, the 2-100 char range, and the limit default. The description only reinforces 'name match only' rather than adding syntax or usage detail beyond the schema, so the baseline 3 applies.

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 ('Search England's scheduled monuments by name') and enumerates the returned fields, so an agent knows exactly what the tool retrieves. The 'by name / Name match only' phrasing implicitly separates it from the proximity-based sibling scheduled_monuments_near.

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 usage context through audience ('landowners, detectorists, developers and walkers') and a strong interpretation caveat: no match does not mean unprotected or unrecorded. It stops short of explicitly routing to scheduled_monuments_near for geographic queries, so alternatives are only implied.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive), so the description's added value is the geometry semantics: any monument whose mapped area overlaps the search square is included, and distance is measured to the monument's reference point rather than its edge — a distinction that materially affects result interpretation. It also discloses the upstream source and a 1-credit cost. It does not say what happens when results exceed the limit.

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 action and ordering, then layers use cases, provenance, geometric caveats and cost. Dense but largely earning its space; 'Takes lat/lon' is the weakest phrase since the schema already makes that obvious.

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 no output schema, the description compensates by naming the return fields, the sort order, and the distance metric. It is close to complete for a lookup tool, with the remaining gap being truncation behaviour when limit caps results and the required-vs-optional coordinate ambiguity.

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 100%, so lat, lon, limit and radius_m are already documented with ranges and defaults; the baseline of 3 applies. The description adds useful framing — that the coordinates define a search square and distances are to the reference point — but it does not resolve the discrepancy that the schema marks zero parameters as required while lat/lon are described as required, nor how radius_m shapes the search area.

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 ('List scheduled monuments'), the geography ('around a point in England'), the ordering ('nearest first'), and the returned fields (date scheduled, area, official link). It does not name or distinguish itself from the sibling 'scheduled_monument_search', though 'around a point' implicitly signals a spatial query versus a name-based one.

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 decision context by framing the question it answers ('are there any scheduled monuments on or near this land') and naming two use cases (development checks, metal-detecting permission). It stops short of excluding alternatives or telling the agent when to prefer scheduled_monument_search or listed_building_search instead.

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