Close Knit

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 job is added context — which it supplies: the assessment is built from recorded local evidence, it is explicitly not a valuation, and price comparison falls back to a bedroom-based ballpark when floor area is absent. It does not discuss provenance freshness or uncertainty, which would have pushed it higher.

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 core purpose is front-loaded in the first clause, which is good, but the remainder is a single sprawling 60+ word enumeration of roughly fifteen evidence categories. Much of that list duplicates what the output schema presumably documents, and the run-on structure makes it hard to scan.

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, read-only analysis tool with a dedicated output schema and full annotation coverage, the description is complete enough: it states the input trigger, the evidence computed, the non-valuation caveat, and the fallback logic. Return-value detail is legitimately delegated 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 coverage is 100%, so the baseline is 3; the description earns an extra point by explaining how parameters combine — floor area versus a bedroom-based ballpark for the £/m² comparison, stamp duty calculated on the asking price, and council tax taken by band. These are the levers that change the output, not restatements of 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 verb+resource are specific ('Check one listing ... against local evidence') and the scope (price vs £/m², HPI, crime, schools, planning, IMD) makes clear this is a per-listing evidence bundle, distinct from the area-level siblings like get_area_evidence_pack. It stops short of naming a sibling, so an agent must infer the boundary itself.

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?

'Check one listing the user found' implies the trigger (the user has a specific property in hand), and 'Not a valuation' sets one important expectation. But there is no explicit when-to-use/when-not guidance and no routing to alternatives (e.g. get_area_evidence_pack for area-only queries, get_home_prices for pure price checks).

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 declare readOnlyHint=true, and the description is consistent with that ('Stateless: nothing is stored on Close Knit'), resolving the apparent tension of a 'build' tool being read-only. It adds real behavioral context — the output is a de-duplication state file path plus a scheduled-task prompt reporting only new listings — though it doesn't cover rate limits, auth, or error 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?

Purpose is front-loaded in the opening clause, and the second sentence adds the important stateless fact. The first sentence is a dense run-on list of artifacts that could be broken up, but there is little wasted content.

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 moderately complex tool with an output schema present, the description conveys what gets produced and that nothing is persisted server-side. Input-to-output mapping is thin, but the presence of an output schema covers return values, making the description largely sufficient 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 57%, and the description mostly describes outputs (state file, prompt, per-district searches) rather than clarifying the inputs. It weakly maps 'filters' to must_haves/min_bedrooms/max_price and hints at area scope, but adds no concrete meaning beyond the schema, and 'postcode district' is loosely aligned with the finer-grained 'LSOA ids' parameter.

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 transformation ('Turn a finished search into a watch') and enumerates the artifacts produced (portal searches, filters, state file path, scheduled-task prompt). It is clearly distinguishable from the read-only query siblings, which makes a solid 4, though it never names an alternative explicitly.

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 phrase 'Turn a finished search into a watch' sets a clear precondition (a completed search) for when this tool applies. It gives clear context but offers no explicit when-not conditions or references to sibling tools, 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?

Adds real context beyond the readOnly/idempotent annotations: it discloses the refusal policy ('Places, never people: religion or who lives there is refused') and what the response contains (best/worst areas, counts, percentiles, legend, map layer). No rate limits or failure modes 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?

A single dense paragraph that front-loads the core purpose before examples and constraints. Nearly every clause carries weight, though the formula/output detail is somewhat packed and could have been left to the schema.

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 tool with an output schema and 100% param coverage, the description supplies the missing conceptual layer: what the tool computes, the refusal constraint, and the return contents. Nothing essential to correct invocation is absent.

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 fully documents top_n, area_ids, criterion, direction, preset_id and deeply explains the formula enum. The description only restates that a criterion is 'sets of OSM tag matchers and a formula', adding little beyond structured fields. Baseline 3 is appropriate.

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 (evaluate) and resource (a criterion counting places within neighbourhood boundaries) with concrete example queries and explicit scope of every London neighbourhood. An agent can distinguish this from rank_areas_by_metric or list_custom_presets 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?

Clearly states the two input modes (a preset_id from list_custom_presets or a user-built criterion) and gives example phrasings that select the tool. It stops short of explicitly naming alternatives to avoid or the conditions under which another ranking tool is better.

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 destructiveHint=false, so the safety burden is lifted. The description adds the refinement/exclusion behavior and the geography-id types accepted (LSOA, MSOA, borough), but most of its remaining text recites return fields that the output schema already provides, and it says nothing about cost, latency or result limits beyond top_n.

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 sentences, each load-bearing: purpose and inputs, return shape, then the refinement instruction. Front-loaded with the verb and resource, and the long factor list is contained inside the first sentence rather than sprawling.

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 19-parameter tool with an output schema and full annotation coverage, the description supplies the essentials: what it ranks, what comes back, and how to re-run after feedback. Nothing critical is missing, though the soft-vs-must weighting model and the station/borough ≤3 constraint are left entirely to the 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 coverage is 100%, so every parameter is already documented, which sets the baseline at 3. The description does contribute the factor vocabulary (crime, station access, price level, deprivation decile, noise, disorder, energy rating, leasehold share) that maps onto the priorities enum and the idea of 'weighted' priorities, but it adds no syntax or default guidance 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?

States a specific verb ('Shortlist') and resource ('London neighbourhoods') and scopes the inputs a household would supply (budget, bedrooms, weighted priorities, stations/boroughs). An agent can tell this is a ranked-shortlist tool rather than a single-metric ranker, though it never names the near siblings (match_areas, search_areas, rank_areas_by_metric) to sharpen 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?

Gives a concrete usage loop: pass rejected areas in exclude_area_ids 'when refining after the user's feedback', which tells the agent this is the iterative tool in a household flow. It stops short of explicit exclusions or a named alternative, so there is no when-not-to-use 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, closed-world behavior, so the description's main added value is disclosing the scoring dimensions behind 'similar' — crime, deprivation, income, price level, station access percentiles. That is genuine context an agent cannot get from the schema. It doesn't discuss result ordering or how ties are resolved, but the output schema covers the return shape.

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 that names the resource, the similarity dimensions, and the optional filter, with the user-intent quote last. The parenthetical list is dense but every element earns its place; nothing extraneous.

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 read-only, four-parameter similarity tool with 100% schema coverage, an output schema, and full annotation coverage, the description supplies the one missing piece — what 'similar' means. Nothing needed to invoke it correctly is absent.

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 all four parameters are already documented, and the description's 'cheaper ones' and 'neighbourhood the user liked' largely restate the cheaper and area_id parameter descriptions. It adds marginal framing by tying 'cheaper' to the price-level percentile dimension but says nothing about top_n or bedrooms. Baseline 3 applies when the schema does the heavy lifting.

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-less but clear operation: returning neighbourhoods similar to one the user already liked, and enumerates the dimensions of similarity (crime, deprivation, income, price level, station access). It implies but does not explicitly contrast with siblings like match_areas, search_areas, or find_areas, so the agent must infer the similarity-vs-search 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?

The quoted user intents ('like this but cheaper / elsewhere') and the 'optionally only cheaper ones' clause give real routing cues for when to enable the cheaper flag. However, no sibling tool is named and no exclusion ('do not use for X; use Y instead') is stated, so the usage guidance remains implied 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?

The description adds substantial behavioral context beyond annotations: data source (HM Land Registry Price Paid), currency (GBP), EPC floor area where matched, absence of per-sale GBP/m2, and precise link behavior (listingLinks open Rightmove/Zoopla/OnTheMarket, links only, no fetching or hosting of listings).

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 three tightly written sentences, front-loaded with the core purpose and data source, followed by key clarifications about data type and link behavior. Every sentence adds value without redundancy.

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 presence of an output schema (which handles return values) and rich annotations (read-only, idempotent, non-destructive), the description completes the picture by covering data provenance, limitations, and link semantics. An agent has all needed context 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 description coverage is 100%, so the single parameter is fully documented in the schema. The description only reiterates 'one address id' without adding syntax or format details beyond what the schema already provides.

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: returns recorded achieved sale prices for one address id. It clearly distinguishes the data from valuations or asking prices, though it does not explicitly name a sibling tool it replaces or complements.

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 provides clear context for use: for a single address id, and explicitly excludes valuations or asking prices. It does not, however, name an alternative tool or specify when to choose a different sibling for related tasks.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description focuses on content-level behavior: every block carries a source release, the optional address_id conditionally adds building and street sale aggregates, and the output is explicitly 'not advice and not a valuation'. It does not describe what happens when address_id falls outside area_id or whether the pack is expensive to build.

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 introduces the pack before listing its blocks, with no filler. The enumeration is dense and takes effort to scan, and the 'as get_market_depth' phrasing is slightly awkward, but every clause carries substantive 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 explain return shapes, and it usefully pre-summarizes the blocks an agent will receive. The main gap is unspecified behavior for an address_id outside the given area and any latency or cost expectations for a multi-block pack.

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, but the description adds real meaning: address_id must be inside the area and its presence adds building and street sale aggregates, which is a conditional effect the schema only hints at. area_id's geography semantics remain schema-driven.

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 (an area evidence pack) and enumerates its constituent blocks: market depth, crime rate, noise shares, state schools with Ofsted grades, and address-level sale aggregates. The parenthetical 'as get_market_depth' explicitly ties one block to a sibling tool, letting an agent distinguish this composite from the single-metric 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?

Usage is only implied: the enumerated blocks suggest this is a bundled alternative to calling get_market_depth, get_home_prices, get_flood_risk and peers separately, and the address_id clause hints at when to pass it. There is no explicit 'use this when…' routing or exclusion against siblings such as get_area_overview.

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 readOnly/idempotent annotations, the description discloses unusually rich behavior: units follow the metric (per 1,000 residents, GBP/m2), confidence semantics (high only for observed, not modelled values), a fallback mechanism with quality='fallback' and carrierGeographyId for wider-published metrics, and that period is ignored for the find_areas factors. These are exactly the non-obvious traits an agent would otherwise get wrong.

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 value proposition is front-loaded in the first clause and nearly every sentence carries distinct information (units, confidence, fallback, default period, find_areas caveat). It is a single dense paragraph, though, so the fallback and find_areas caveats are buried mid-block rather than separated, which slightly hurts scanability.

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

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

This is a complex tool with fallback geography logic, modelled-vs-observed confidence, and multi-month evidence rows, and the description covers all of those along with units and period defaults. An output schema exists, yet the description's return-format detail serves the purpose statement rather than duplicating schema burden; nothing essential to a correct call 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 100%, so the baseline is 3; the description earns an extra point by adding meaning not in the schema, namely that period is ignored for the find_areas factor metrics and that fallback geography can override the requested area. The area_id and metric_id semantics are already fully covered by the schema, so no further credit there.

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 ('Evidence-backed value of one metric for one area in one month') and immediately enumerates what the value includes (regional/England percentiles, quality, sample size, category breakdown, up to 12 prior months). This scope ('one metric, one area, one month') distinguishes it implicitly from ranking tools like rank_areas_by_metric and aggregate tools like get_area_overview, and the find_areas cross-reference further separates its role.

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 usage conditions: period defaults to the metric's latest, and it explicitly describes how the find_areas factors (disorder, epc-share, leasehold-share, schools) are read via this tool 'to verify or explain a find_areas result'. What is missing is an explicit exclusion or named alternative for the other siblings (e.g., when to prefer get_area_overview or rank_areas_by_metric instead).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful provenance context (borough-level 'official UK HPI' vs local market aggregates, a 'busy-centre note' caveat on crime), but says nothing about response size, latency, or cost of a payload that spans a dozen domains.

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?

Compact two-sentence form that opens with the one-line purpose and then enumerates contents, using the parenthetical field names as compact pointers to the output schema rather than 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, and it still signals domain coverage, data provenance, and the bedroom-price option. The main remaining gap is routing guidance against the many sibling area tools, which the description leaves entirely to the agent.

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 applies: area_id's LSOA/MSOA/borough pattern is fully documented and the description only echoes that bedroom count yields 'a ballpark price'. It is notable that area_id accepts three geography levels but the description's body text does not discuss how output differs by level.

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 scope ('One neighbourhood in detail for a decision') and then enumerates the domains returned (market, HPI, crime, schools, planning, council tax, IMD), so an agent knows exactly what the resource covers. It does not name the sibling it is not (get_area_evidence_pack, get_area_metric), so differentiation is inferred from content rather than stated.

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: 'for a decision' and the inline instruction 'quote this for how prices moved' hint at when to reach for the HPI figures, but there is no explicit when-to-use/when-not and no mention of the obvious alternatives like get_area_metric for a single figure or get_area_evidence_pack for a deeper pack.

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

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

Annotations already establish read-only, idempotent safety, and the description adds substantial context on top: hub-based routing within 1.5 km, straight-line estimation flagged with estimate: true, null minutes with reason codes 'outside-london'/'outside-coverage', and capping at 120 minutes with capped: true. These are exactly the non-obvious behaviors an agent needs before interpreting 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 core fact is front-loaded, and nearly every clause carries real information. But it is delivered as one sprawling sentence with nested parentheticals and an ellipsis, making the edge-case rules hard to parse rather than separating them into scannable statements.

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 exists, the description needn't explain return shapes, yet it still documents the sentinel fields (estimate, capped, reason) that the schema won't convey semantically. Combined with the London-only routing constraint, an agent has everything needed to call this correctly and read the results honestly.

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 the schema already documents area_id, places, and every mode/category nuance. The description adds only that results are per-place with a range and that car means typical morning traffic with no parking — a point the schema also makes. Baseline 3 is appropriate.

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 precise scope: door-to-door minutes from one neighbourhood to a set of places, on a weekday morning, across four modes. This is unmistakably different from metric-reading siblings like get_area_metric or find_areas, which the agent can rule out 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?

The description gives useful operating conditions (hub routing, straight-line fallback, outside-London and outside-coverage cases, 120-minute cap), effectively telling the agent when results will be degraded. However, it never names an alternative tool or states when to prefer a different call, so guidance is implied 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's job is interpretive context — and it delivers the critical caveat that bands describe an area's likelihood, not a particular property. It adds a real usage hazard the agent would otherwise misreport. It doesn't discuss data coverage gaps (e.g. England-only) or missing-band cases.

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, no filler, with the primary output described first and the UPRN variant second. The caution lands last where it will be read before the agent responds to the user.

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 schema descriptions, the description needn't explain return values, and it correctly focuses on interpretation. What's missing is edge-case behavior — what happens when no flood data exists for the area, or geographic limits on the dataset. Adequate but not exhaustive.

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 uprn parameter already documents 'A home's UPRN for its own bands; without it, only the area's land bands,' so the description largely restates structured data. The one marginal addition is framing UPRN results as still not property-specific, which changes how results should be presented. 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 names the concrete resource (flood bands for land, split into rivers/sea and surface water) and the second mode activated by a UPRN. That is specific enough that an agent can distinguish it from metrics siblings like get_area_metric or get_area_overview. It stops short of explicitly contrasting itself with any sibling, which keeps it at 4.

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 routing logic: use this for area-level bands, and if the user wants one specific address, send them to the Environment Agency check. That is an explicit 'do not use for this' condition. It doesn't state when to prefer this over other area-evidence tools (get_area_evidence_pack, get_area_metric), so it isn't 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 establish that this is a safe, read-only, idempotent operation. The description adds substantial behavioral detail beyond annotations: how area statistics are computed, fallback geography, sample-size thresholds, null UPRN handling, withheld facts, and candidate behavior for ambiguous fragments.

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

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

The description is front-loaded with the main output, but it is a dense wall of text with long semicolon-separated clauses and parentheticals. Most details earn their place, yet the lack of structure makes it 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?

Despite the tool's complexity and the presence of an output schema, the description covers the key behavioral edges an agent needs: area-only valuation stance, sample thresholds, hidden homes, null and withheld facts, and ambiguous-fragment handling. Nothing critical appears to be missing 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 100%, so the schema already documents property_ref, but the description adds useful semantics about fragment ambiguity, asking which home, and passing its addressId. It also clarifies that homes without a linked UPRN are reachable and will carry uprn null.

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: recorded sales for one London home plus today's area price statistics. It distinguishes the scope from sibling area tools by emphasizing 'Area statistics only: never say what the home is worth; describe the area.'

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 invocation context: accepts a UPRN, an address id from search_places, or a fragment, and explains that ambiguous fragments return candidates rather than choosing a home. It also states key exclusions such as below-five-sales suppression and hidden homes, though it does not explicitly route agents to sibling alternatives like get_nearby_sales_summary or get_area_metric.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structural context: the tool returns links only, Close Knit never fetches or stores listings, and OpenRent is included for rentals — all useful for an agent deciding whether the output is usable directly.

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, zero filler. The resource and portal scope are front-loaded and the 'links only / never fetches or stores' caveat follows immediately after — nothing redundant with 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?

An output schema exists, so return-value structure need not be described, and the description usefully says the result is links to open externally. It is nearly complete; only the relationship between outcodes_per_area and the emitted link count/wording is left implicit.

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 all five parameters are already documented in the schema, which sets the baseline at 3. The description adds only marginal detail (postcode districts, all-portal coverage, rental inclusion for OpenRent) without explaining area_ids, max_price units, or outcodes_per_area ordering beyond what the schema already says.

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 — pre-filtered search links on Rightmove, Zoopla, OnTheMarket (plus OpenRent for rentals) for postcode districts of shortlisted areas. That is concrete and distinct from siblings like evaluate_custom_criterion or get_area_evidence_pack, but no sibling is named as an alternative, so the differentiation is implicit rather than explicit.

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 context ('for the postcode districts of shortlisted areas') plus 'open them on the user's behalf to read listings' implies when to reach for this tool: after areas have been shortlisted you want external portal results. But it never states when NOT to use it or names sibling tools that would serve the same need, leaving usage 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 read-only/idempotent/no open world, so the safety profile is covered. The description adds genuine behavioral context beyond that: data source and filter (HM Land Registry Price Paid, standard category A sales only), minimum-sample thresholds (10 sales per median, both for the premium), and the leasehold-share-of-sales caveat that resolves a likely misreading.

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 purpose, then the metric list and caveats. It is dense and long for one sentence, but nearly every clause carries distinct information (thresholds, sales-vs-homes distinction, exclusions); only the parenthetical threshold restatement feels heavy.

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. The description covers scope, source, filter, every metric definition, sample-size thresholds, and explicit non-uses, which is everything an agent needs to invoke and interpret this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single area_id parameter is fully documented with a pattern and example. The description only restates that the area is LSOA or MSOA; the borough exclusion is already in the schema, so the description adds little beyond the structured fields. 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 and then enumerates exactly which metrics it returns (12-month sales, turnover, leasehold share of sales, new-build/resale median £/m2 over 36 months, new-build premium, £/m2 growth). The scope 'one LSOA or MSOA' plus 'aggregates only' distinguishes it from siblings like get_area_metric, get_home_prices and get_nearby_sales_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?

Scope is implied clearly (one area, aggregates only, Price Paid standard category A), and 'never a valuation, a listing or addresses' usefully fences off misuse. However, it never names an alternative tool or states a condition that would route the agent to get_area_metric or get_home_prices instead, so routing must be inferred.

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, the description discloses important behavioral details: the 10-year window, grouping by building and street, suppression of medians under 5 sales with an EPC floor area, exclusion of privacy-objection homes, and confirmation that no sale rows or addresses are returned. These are exactly the caveats an agent needs to interpret results correctly.

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

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

The description is dense and front-loaded: it starts with what is computed and for what geography, then adds time range and limitations. Every clause contributes useful scope or caveat 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 the output schema, read-only annotations, single required parameter, and 100% schema coverage, the description supplies all remaining context: aggregation method, geographic grouping, time window, suppression rules, and privacy exclusions. Nothing needed to call or interpret the tool 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 one parameter and 100% schema description coverage, the schema already defines address_id, its pattern, and that it comes from search_areas. The description reinforces that a single address id drives the lookup but adds no syntax or format 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 operation and scope: counts and median GBP/m2 of nearby recorded sales for one address over the last 10 years. It clearly distinguishes itself as a summary-only tool with no sale rows or addresses, though it does not explicitly name a sibling alternative for detailed sales 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?

It implies the tool is for summary-level nearby sales information, but gives no explicit when-to-use guidance and does not compare itself with sibling tools such as get_home_prices or get_address_history. The agent must infer the usage context.

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 safety, so the description's job is edge-case disclosure and it delivers: it warns that LSOA-level values are borough averages (a provenance/fallback caveat) and that results are empty for studios or before rents are loaded. These are non-obvious behaviors an agent would otherwise misreport as real data.

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 with the metric front-loaded and caveats after. 'Borough averages per LSOA' is compressed to the point of ambiguity but no sentence is padding.

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

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

An output schema exists so return shape needn't be described, and the edge cases are covered. However, for a two-required-param lookup embedded among many similar metric tools, the absence of any routing guidance and of currency/timeframe context leaves real 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 the schema already documents both area_ids and bedrooms; baseline 3 applies. The description adds only an edge case ('empty for a studio'), and it slightly muddies things since bedrooms has a minimum of 1 — it does not clarify units, currency, or whether area_ids must all be the same geography level.

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+resource: median monthly rent by bedroom count for given areas, with the parenthetical '(the figure the site shows)' tying it to a known quantity. It does not name or distinguish itself from siblings like get_home_prices or get_area_metric, but the metric itself is unambiguous.

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?

There is no statement of when to use this instead of get_home_prices, get_area_metric, or rank_areas_by_metric. The agent must infer that this is the rent-specific lookup from the name alone; no exclusions, prerequisites, or alternatives are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds the return shape per entry (id, mapUrl, one-line definition) and the neutral-naming convention, which annotations do not convey. Pagination or count are not discussed, but with a fully enumerated preset catalog that 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?

The middle of the description is a long run-on enumeration of ~20 preset examples that largely duplicates what the output schema already delivers. The genuinely useful guidance — the id/mapUrl/definition fields and the 'use names as given' rule — sits at the end rather than being front-loaded, and the opening sentence starts with content rather than with the action.

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, zero parameters and full annotations, the description only needs to frame what the catalog is and how to use it — both are covered, including downstream tool references and naming conventions. Nothing an agent needs in order 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly adds no parameter talk and instead spends its words on 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?

The description makes clear these are ready-made, pre-built custom criteria derived from OpenStreetMap places, and that each carries an id, mapUrl and one-line definition — so an agent knows what the tool returns. It also names the sibling consumers (evaluate_custom_criterion, find_areas(custom=[...])). It does not lead with an explicit verb like 'Lists all available presets', so the listing action is inferred from the name rather than stated.

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 ties the output to concrete downstream calls — the id feeds evaluate_custom_criterion and find_areas(custom=[...]) — which tells the agent when this tool is the entry point. It also gives a usage constraint on how to surface the names (no brand names or value words like 'good'/'cheap'). There is no explicit when-not or a statement that this is the discovery step to run before the two consumer tools.

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 safety, and the description adds real context beyond them: the reply is scoped to 'the active release', compact mode shrinks the payload, and factor metrics are included alongside area metrics. It stops short of describing pagination or size limits for the full (non-compact) response.

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, followed by the calling sequence and then the compact caveat — every sentence carries information. The parenthetical field lists and the trailing 'Sources carry licence and methodology links' make it a dense block rather than cleanly separated beats, but nothing is padded.

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 exists, the description need not explain return shapes, yet it still flags the catalogue's structure (area vs. factor metrics), release scoping, and provenance/licence caveats. An agent has everything needed to call it and use the result to drive get_area_metric and rank_areas_by_metric.

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 still adds purpose for the one flag, explaining that compact=true returns 'only id, unit, direction and defaultPeriod' for callers who 'just need valid metric_id/period values'. That is a use-case framing the schema's own one-line description does not fully supply.

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 and resource ('List every area metric the active release serves'), then enumerates the returned fields (id, unit, direction, periods, legend, provenance, caveats) plus the 'factor' kind. It also names the siblings that consume this data (get_area_metric, rank_areas_by_metric), so an agent can tell the catalog tool apart from the query tools 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?

Explicitly states the ordering rule: 'Call first to learn valid metric_id/period values for the other area tools,' which tells the agent both when to use it and which alternatives it feeds. The compact=true variant adds a second decision point (cheap discovery vs. full metadata).

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 annotations: it discloses that must criteria act as filters with no weight while others weigh by list position, that coverage counts (scored/unscored/excluded/excludedBy) span every area while value/fit/in-edge-out components are returned for listed areas only, and that mapUrl opens the full map because the list is only top-N. It also surfaces a consent requirement for analyticsConsent and states explicitly that the tool behaves identically with false, which is exactly the kind of 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?

Purpose is front-loaded in the first clause and returns/consent follow in a logical order, with no filler sentences. The second sentence is a long multi-clause run-on that would read better split, which keeps it out of the top band.

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 tool with nested criteria and an output schema, the description covers the semantics an agent actually needs (must-as-filter, top-N vs whole-map coverage, consent). Return-value detail is partly redundant given the output schema exists, and the undeclared analyticsConsent parameter is handled in prose rather than the schema, leaving a small structural 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%, so the baseline is 3; the description nevertheless adds real meaning by documenting analyticsConsent, a parameter that does not appear in the input schema at all, including its consent semantics and the fact that it does not change results. Its top_n explanation largely restates the schema, so the added value is real but partial.

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

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

States a specific verb and object ('Score every area against a household's ordered criteria') and names the concrete input format (preference-profile.v2) and output artifact (match-pack.v2), so an agent knows exactly what the tool produces. It does not explicitly name a sibling it is not (e.g. rank_areas_by_metric or find_areas), so differentiation is by inference from the criteria-scoring framing.

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 implied by the phrasing – this is the tool for scoring a whole market against a ranked preference profile rather than filtering (find_areas/search_areas) or ranking by a single metric. There is no explicit when-to-use/when-not statement and no named alternative, and the only real guidance given ('Set analyticsConsent true only if the user agreed') is a consent rule for a parameter, not a tool-selection rule.

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 readOnly, idempotent, non-destructive, closed-world safety. The description adds meaningful behavioral context beyond that: it discloses what data is exposed (including private notes), the accepted link formats, and that results are re-ranked to match find_areas' shortlist. Return shape 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?

Front-loads the core action and purpose, then the trigger condition. The parenthetical content list is long but informative; overall size is reasonable with little waste.

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 rich annotations, 100% schema coverage, and an output schema, the description is largely complete for correct invocation. It could be marginally stronger by noting what the response contains, but the output schema carries that burden.

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 are fully documented in the schema, establishing baseline 3. The description explains what the link contains but adds no syntax or constraints beyond the schema, and top_n is not addressed.

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 (open) and resource (a search the user shared), enumerates what the search contains (budget, priorities, places, liked/ruled-out areas, private notes), and ties the result to the same shortlist as find_areas. An agent can distinguish it from find_areas and search_areas without opening either 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 explicit trigger conditions: when the user pastes a #profile=v1/v2/v3 link or says 'discuss my search'. It clarifies the parallel to find_areas but does not state an explicit exclusion or when NOT to use it, keeping it just 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?

Beyond the read-only, idempotent annotations, it discloses competition ranking for ties, the `tiedCount` field, suppression behavior, and that census layers are refused. It also explains that `find_areas` factor ranking uses latest value and ignores period.

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

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

The description is dense but front-loaded, starting with the core operation and scope before tie behavior, use cases and exclusions. Every sentence carries actionable information for selecting or invoking 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, the description still usefully names returned fields, scope, exclusions, tie handling and metric-specific caveats. Nothing material is missing for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds useful metric semantics not in the schema: IMD decile meaning and direction, income units, social-renting neutrality, and a region example. This meaningfully improves correct parameter selection beyond the structured fields.

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: rank every served area or one region's areas by a metric for a month, returning top N with rank, value, unit and quality. It also distinguishes this from sibling `find_areas` by noting which factors `find_areas` can rank.

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 explicit usage examples such as 'lowest crime', 'highest GBP/m2', 'least deprived', 'highest household income' and 'most social renting', including the correct `order` for deprivation. It also states exclusions clearly: census layers are refused and suppressed values are excluded.

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-open-world, non-destructive, so the safety profile needs no restating. The description adds one genuine behavioral nuance beyond the schema: address ids only appear 'where recorded sales exist,' meaning results are conditionally partial. It says nothing about result ordering, relevance ranking, or behavior when nothing matches.

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, and the id format is front-loaded so the agent knows what comes back before reading the follow-up tool list. The compressed id pattern (uk:lsoa|msoa|borough:…) is dense but readable in context.

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

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

Good coverage for a 2-parameter, read-only lookup: annotations carry safety, an output schema exists so return shape needn't be explained, and params are fully documented in the schema. The one real omission is disambiguation from the other area-search siblings (find_areas, match_areas, search_places).

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 q and limit are already documented in the schema. The description restates the same input types (area name, ONS code, postcode, street) without adding format, matching, or precedence rules. 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: resolve free text (area name, ONS code, postcode, street) to geography ids and, conditionally, address ids. That is a clear, concrete purpose. It does not distinguish itself from siblings like find_areas, match_areas, or search_places, which appear to do overlapping resolution work.

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

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

It tells the agent what to do with results (pass ids to get_area_metric, rank_areas_by_metric, get_address_history), which implies usage but never states when to pick this tool over find_areas or match_areas. There are no exclusions or prerequisites, only downstream 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 establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new behavioral detail: fuzzy station matching, recognition of London codes and nicknames (KX, TCR, E&C, ally pally), and the fact that twin stations like Hammersmith are returned separately. It stops short of describing ranking or ordering of results, but the matching behavior described goes 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?

The purpose and input types are front-loaded, followed by the routing information. The parenthetical examples and the list of return types make the two sentences dense, but each clause adds useful information rather than restating the name.

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 two parameters, full schema coverage, and an output schema, the description supplies everything an agent needs: what inputs are resolvable, how forgiving the matching is, what identifier formats come back (osm:…, uk:borough:…), and which sibling tools consume each result type. No behavioral gap remains for this tool's complexity.

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, but the description adds real parameter-level meaning by showing that 'q' accepts informal inputs such as codes and nicknames, not just formal names, and by giving concrete examples of accepted place types. The 'limit' parameter (results per kind) 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 opens with a specific verb and resource ('Resolve a place ... to ids') and enumerates the place kinds covered (station, borough, neighbourhood, postcode, street). It is clearly distinguishable from siblings like search_areas and find_areas because it states that the output is identifiers.

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 routes results to downstream tools ('for find_areas.near_stations', 'for find_areas.boroughs', 'for get_area_overview and assess_listing'), which tells the agent when this tool is the right precursor. It does not, however, state when to prefer search_areas or match_areas instead, so the alternative comparison 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 declare a non-read-only, non-idempotent, non-destructive write, and the description adds the meaningful context those annotations cannot express: user consent is required and the payload is sent to the team with hard privacy constraints. It does not say whether submissions are editable/retractable or whether any follow-up occurs, so it falls just short of full disclosure.

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, purpose first, then the consent gate, then the content policy. Minor redundancy: the no-personal-details rule is stated in both the description and the message field's schema description, and 'never the person' is restated twice.

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

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

Covers when to call, what to put in the payload, and the privacy boundary; an output schema exists so return values need no explanation. Only the post-send consequence for the user (confirmation, whether it can be undone) is left unstated.

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 the baseline is 3; the description still adds value by governing what belongs in 'message' (describe the product, never the person, no names/contact/addresses/family/budget). That privacy rule meaningfully constrains how to fill the largest parameter.

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 ('Send feedback about Close Knit to the team') and enumerates the accepted kinds of feedback. It is unmistakably distinct from every sibling tool, all of which are read-only search/metric 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 an explicit precondition for invocation: 'Call it only after the user agrees: show them the message first.' This is a concrete when-to-use rule with an ordering constraint, not a vague hint.

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