Homedex

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

Annotations already declare read-only, idempotent, closed-world, non-destructive, and the description is consistent with all of them while adding behaviour the annotations cannot express: multi-outcode towns return a list of options rather than data, and uncovered areas return the list of covered ones instead of failing. That disambiguation-then-retry behaviour is exactly the operational 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?

Front-loaded with the resource and payload, then constraints, then the input contract, then the 'sold prices not valuations' caveat — a sensible ordering with no filler sentences. Slightly dense in the mid-section where coverage and multi-outcode handling interleave, but 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?

A single-parameter read-only aggregate with an output schema, and the description still covers the three things that schema and annotations cannot: what the numbers mean, the input ambiguity case, and the uncovered-area fallback. Nothing an agent needs to call this correctly is left to inference.

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% for the single 'area' parameter, so the baseline is 3; the description earns above that by spelling out the accepted forms (outcode, full postcode, or single-outcode town) and by explaining the consequence of passing an ambiguous town name. It adds the 'why' behind the parameter shape rather than restating the 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?

Opens with a specific verb-and-resource statement (sold-price figures for a UK postcode area from HM Land Registry) and enumerates exactly which statistics come back: median/quartile prices, breakdowns by property type, yearly medians, sector medians, and energy-rating counts. What's missing for a 5 is differentiation from the sibling 'nearby_sold', which an agent could easily confuse with this area-level aggregate.

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-case phrasings ('what do flats sell for in CT20?', 'how have prices changed in Canterbury CT1?') and clear preconditions on the input — outcode, full postcode, or single-outcode town, with Folkestone given as the multi-outcode failure case. It also scopes what the tool is not (sold prices, not asking prices or valuations). It stops short of naming an alternative tool for out-of-scope questions.

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, closed-world behavior. The description adds the important behavioral caveat that the figure is an estimate rather than exact, and explains the two coverage components; return format is left to the 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?

The description front-loads the definition, then provides a usage example and an estimate caveat in compact form. The parenthetical local-authority note is useful but makes the first sentence dense.

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-parameter read-only tool with an output schema and rich annotations, the description supplies the conceptual meaning of coverage and the necessary estimate caveat. It leaves sibling routing implicit, which is a minor gap.

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 already documents the area parameter with town, outcode, and postcode examples. The description adds only that the area is also resolved to its local authority; it does not add syntax or validation detail beyond 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?

The description states a specific metric: an estimate of homes-for-sale coverage plus estate-agent participation, for a town, outcode, postcode, and local authority. That clearly distinguishes it from a generic area-statistics tool, but it does not explicitly name or contrast with siblings such as area_stats.

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 an explicit use case — communicating how complete answers are—and a required framing rule to always call the figure an estimate. It does not state when to choose this over area_stats or other siblings, so alternative routing is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds context beyond them: the result is text rather than structured data, it enumerates what the record contains (price, rooms, description, agent, last-verified timestamp, viewing link), and it warns that viewings and enquiries go to the agent rather than Homedex.

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?

One dense, front-loaded sentence sequence: resource and key first, then payload contents, then the sibling relationship. The id example is repeated from the schema, which is mild redundancy, but no sentence is otherwise 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?

For a single-parameter read tool with an output schema and full annotations, the description covers the call site, the source of the id, the nature of the response (text) and the sibling alternative. Nothing material is missing for an agent to select and 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 description coverage is 100% and the single id parameter's meaning and example format are already documented in the schema. The description restates the provenance of the id from search but adds no syntax or validation detail beyond that, 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 — fetch the full details of one home — and pins the key as the id returned by search, with the Homedex number format shown. It also distinguishes itself from siblings: search produces the id, and get_listing returns the same record as structured data.

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 (use it after search, with the id search returned) and names the alternative, get_listing, for callers that want structured data, plus the intended consumer (standard search-and-fetch clients like ChatGPT deep research). It stops short of an explicit 'do not use when' instruction or guidance on an invalid/unknown id.

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 bar is lower. The description still adds real value by naming the freshness field (last_checked, which reflects when Homedex verified the listing was live on the agent's site) and by pointing to agent_url as the booking path, though it omits what happens on a missing/delisted record.

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 in the opening clause, followed by a field inventory and one short actionable sentence. The field list is long, but each item tells the agent something it can surface to a user, so little of it 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, yet the description still gives the agent enough of a payload map to answer 'what can I tell the user?' without a trial call, and it covers the booking hand-off. For a one-parameter read tool with full annotation coverage, nothing material is missing beyond error-case behaviour.

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 the single parameter already documents itself with the same example (HX-CT20-00084), so the description is largely restating structured data. Baseline 3 applies; it adds no constraint such as format validation or accepted identifier variants.

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 concrete retrieval action ('Everything about one listing by its Homedex number') and enumerates the payload (price, rooms, tenure, photos, agent, last_checked, nearby sold data), so the agent knows exactly what resource it gets. It never names a sibling, though, and its 'recent sales within 500 m' content overlaps with the nearby_sold tool without clarifying 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?

Usage is only implied: the required Homedex number signals this is for when an ID is already known, and the closing line directs the user to agent_url for bookings. There is no explicit 'use this instead of search_listings when...' guidance and no stated behaviour for an unknown or stale Homedex number.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the notion that the call is cheap and non-essential, and says nothing about failure behavior (e.g., what is returned if the service is degraded).

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 sentences, zero filler, with the return contract first and the usage caveat second. Nothing could be removed without losing 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, the description need not enumerate return values, and with zero parameters and full annotation coverage the definition is nearly complete. The only gap is the absence of any note about what a non-ok result looks like.

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. The description correctly implies a parameterless ping and does not need to explain inputs.

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 concrete behavior: it returns an 'ok' status plus the running version. That is specific enough to distinguish it from the data-retrieval siblings (search, fetch, coverage, area_stats), though it never explicitly contrasts itself with 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?

It states both a positive use case ('for monitoring') and an explicit exclusion ('not needed for answers'), which is more routing guidance than most tools in this set provide. It stops short of naming a sibling alternative, but the intended use 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?

Annotations already cover read-only, idempotent and non-destructive status, so the bar is lower. The description adds two operationally important facts the annotations cannot convey: HM Land Registry records usually appear 1–3 months after completion, and results are limited to areas Homedex has loaded. It does not mention response size, pagination, or what happens when the postcode falls outside loaded coverage.

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 tight sentences: what it returns, when to use it, then the caveats. Nothing is wasted apart from slight overlap between the title and the opening clause, but the caveats are correctly placed after the core definition.

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 and full annotation coverage, the description need only supply the non-structured operational context, and it does: data lag, geographic coverage limits, ordering, and field set. An agent has everything required to decide whether to call this tool and how to interpret a sparse 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 description coverage is 100%, and every parameter including defaults and the 3 km radius cap is documented in the schema itself. The description only implies postcode-based filtering and ordering, adding no syntax, format or default detail 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?

The description states a specific verb+resource (recent standard sales from HM Land Registry near a postcode), the ordering (newest first), and the returned fields (price, date, address, property type, tenure, distance). That scope clearly separates it from aggregate siblings like area_stats and single-property tools like get_listing or search_listings.

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 an explicit use case in the user's own words ('what have houses on this street / near this postcode sold for?'), which tells an agent exactly what intent should route here rather than to area_stats. It stops short of naming sibling tools or stating when not to use it (e.g. for rental or listing data).

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 behavior, so the bar is lower. The description still adds real context not present in the structured fields: the result cap (up to 20), the fact that each result carries an id intended to be passed to fetch, and the UK/participating-agent scope. It stops short of describing ranking, pagination beyond the cap, or behavior when no results match.

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?

Four short sentences, front-loaded with the core action, then the input shape with examples, then the return contract and the fetch chaining, then the sibling disambiguation. Every sentence carries distinct information and none is redundant with 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?

An output schema exists, so return values need not be spelled out, and the description still covers the result count and the id-to-fetch handoff. With a single fully described parameter, full annotation coverage, and explicit sibling routing, an agent has everything needed to call this 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 100% and there is only one parameter, so the baseline is 3. The description exceeds that by explaining the query's expected syntax and content (plain English including a place, with example phrasings like "flats to rent CT20"), which meaningfully constrains how an agent should phrase the string. Only the 200-character limit is left to 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?

The description states a specific verb and resource ("Searches homes for sale or to let from participating UK estate agents"), defines the input shape ("one plain-English query"), and gives concrete examples. It also explicitly contrasts with the sibling search_listings, which accepts the same filters separately, so an agent can pick between the two 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 names the alternative (search_listings) and gives the selecting condition: this tool is "made for apps that use standard search and fetch tools (ChatGPT deep research)." It also states a coverage constraint (name a town, outcode or postcode). There is no explicit "do not use this when..." clause, but the routing information is clear enough for an agent to choose correctly.

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 read-only/idempotent annotations, it discloses result ordering (most detailed first, then newest, with agents taking turns), a cap of 20 results, the one-line more_matches overflow with the next 30, and listing freshness ('when Homedex last checked it was still listed'). That is substantive behavior an agent could not get from 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 the resource and scope, then usage example, then ordering and pagination behaviour. It is dense but nearly every sentence carries information; the sort explanation slightly restates the schema enum description.

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 supplies the ordering, cap, and pagination model needed to drive a 14-parameter search correctly. Nothing critical 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 64% schema coverage, the description adds real meaning: it explains what sort does including the round-robin agent behaviour, clarifies area can be town/outcode/postcode, and points at cursor as next_cursor from a prior answer. Minor params like within_miles/near_postcode and bed bounds are left to the schema, which is adequate.

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 ('live homes for sale or to let from participating UK estate agents'), the geographic granularity (town, outcode, postcode area) and the fields returned (price, bedrooms, type, photo, agent link, last-checked date). An agent can distinguish this from get_listing or nearby_sold 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 a concrete when-to-use example ('find me a 3-bed flat in Folkestone under £300k') and explains the conditional use of sort for plain price or date order versus the default fair-rotation ordering. It stops short of naming when to prefer get_listing or the generic search sibling instead.

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