OneGoodArea gives AI agents and developer tools access to sourced, dated and confidence-rated place intelligence across Great Britain. Resolve locations, analyse and compare neighbourhoods, discover similar areas, generate decision-focused briefs and monitor changes through 12 MCP tools backed by deterministic, explainable data.
Scored across 12 tools
Most tools target clearly distinct operations (score one place, compare several, write a brief, find peers, resolve an id). The closest pair is get_area_signals vs get_signals_by_category, but the descriptions state the all-vs-one-category distinction explicitly, and the cross-references ('for one named place use...', 'for a ranking filtered by named signals, find_areas') actively steer selection.
The dominant pattern is verb_noun (compare_postcodes, find_areas, get_area_signals, score_postcode, watch_portfolio). Three names break it (area_brief, engine_version, methodology_for), which is a minor deviation rather than a mixed-convention mess. All names are snake_case throughout, so readability is unaffected.
Twelve tools for an area-intelligence API with four distinct workflows (single place, multi-place comparison, discovery, monitoring) is well-scoped. No tool looks like filler: even the small ones (engine_version, methodology_for) map to a concrete model-risk or documentation need.
Analysis coverage is strong (score, compare, brief, peers, raw signals, methodology, resolution), but the portfolio lifecycle is half-built: watch_portfolio creates and get_portfolio_changes reads, yet there is no list-portfolios, update, add/remove place, or delete tool. Without a listing call an agent that loses the id has no recovery path, and no call, so monitoring is hard to manage.
Writes a brief on one place in England, Wales or Scotland for one audience: lender (residential mortgage origination), insurer (property risk underwriting), retailer (site selection) or investor (residential investment). Combines the full signals catalogue with the audience's scoring preset and returns a markdown document: verdict, the dimensions and signals that matter to that audience with provenance, recommendations and data sources, all composed from engine output. Counts as two API calls.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | A postcode (e.g. 'SW1A 1AA'), a place name (e.g. 'Manchester city centre') or a neighbourhood code (e.g. 'E01003920') in England, Wales or Scotland. Up to 100 characters. | |
| audience | Yes | Who the brief is for: lender, insurer, retailer or investor. |
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 covered. The description adds genuine non-obvious context beyond that: the return format (markdown document with verdict, provenance-tagged dimensions, recommendations, data sources) and the cost disclosure 'Counts as two API calls'.
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 and geography are front-loaded in the first clause, then audience enumeration, then return format and cost. Every element earns its place, though the audience list is repeated from the schema enum and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the document's contents (verdict, dimensions, signals, recommendations, sources), so an agent knows what to expect. Combined with the two-call cost notice and the audience semantics, this is nearly complete for a 2-parameter tool; only the relationship to sibling tools is 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% and the audience enum is fully documented in the schema, including the exact format examples for area (postcode, place name, neighbourhood code) and the 100-character limit. The description restates the four audience values without adding syntax or constraint detail beyond the schema. 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 ('Writes a brief'), a bounded resource ('one place in England, Wales or Scotland') and a discriminating parameter dimension (one of four named audiences). An agent can distinguish it from get_area_signals or score_postcode, which return raw signals/scores rather than a composed audience-specific document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the audience framing (lender/insurer/retailer/investor) and the mention that it combines the signals catalogue with a scoring preset, but the description never says when to prefer this over siblings like get_area_signals or score_postcode, nor when it is overkill. No explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scores 2 to 8 places in England, Wales or Scotland for the same decision preset and returns one table sorted by score: overall score, area type, strongest dimension and a one-line summary per place. Each place is scored independently, so a place that fails is reported in its row while the others still return. There is no data for places outside England, Wales and Scotland, such as Belfast; do not call it for them.
| Name | Required | Description | Default |
|---|---|---|---|
| areas | Yes | Postcodes, place names or neighbourhood codes in England, Wales or Scotland to compare. Between 2 and 8 entries. | |
| preset | Yes | The preset applied to every place: 'moving' for how liveable a place is for a household (safety, affordability and schools weigh most; choose it for a home move, lenders use it for residential mortgage origination), 'business' for site selection, 'investing' for yield and growth, 'research' for a neutral baseline. |
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 covered. The description adds genuinely useful behavior beyond them: places are scored independently and a failing place is reported in its own row while others still return, which tells the agent that partial failure is expected and not an error condition.
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, front-loaded with what it does and what comes back, then partial-failure semantics, then the coverage exclusion. No filler, no repetition of the schema's enum values, and every sentence carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by naming the returned columns (overall score, area type, strongest dimension, one-line summary) and their ordering. Combined with the coverage limit and partial-failure rule, nothing an agent needs to invoke and interpret this 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?
Schema description coverage is 100% and the preset enum already enumerates moving/business/investing/research with detailed explanations, so the schema is doing the heavy lifting. The description only adds that one preset is applied uniformly across all places ('the same decision preset'), which is a modest clarification rather than new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource pair ('Scores 2 to 8 places ... for the same decision preset') plus the output shape, so an agent immediately knows this is a multi-place comparison rather than a single lookup. It never names a sibling (e.g. score_postcode for one place, find_areas for discovery), so differentiation is implied by cardinality 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?
Explicit negative guidance is given: 'There is no data for places outside England, Wales and Scotland, such as Belfast; do not call it for them.' That is a real when-not rule with a concrete example. It stops short of naming the alternative to use for a single place or for out-of-coverage locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the engine version the API stamps on responses now, its release date and the most recent methodology releases, read live. Fits 'what version are we on' and model-risk documentation; the same version is stamped on every score_postcode and get_area_signals response.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: 'read live' signals no caching/staleness, and the note that the same version is stamped on other responses tells the agent the value is a cross-cutting global.
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, front-loaded with what is returned, followed by usage fit. Every clause earns its place and 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?
With no input parameters and no output schema, the description carries the return-value burden itself and does so: it names the version, release date, and methodology releases. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. There is nothing for the description to clarify about 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?
States a specific verb ('Returns') and a concrete resource (engine version, its release date, and recent methodology releases), and it distinguishes itself from siblings by noting the version is stamped on score_postcode and get_area_signals responses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use contexts ('what version are we on' and model-risk documentation) and links to the sibling tools whose responses carry the version. It stops short of naming a when-not condition or an alternative tool, but the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds and ranks the neighbourhoods in England, Wales or Scotland that match a plain-English question about their signals: price, price change, crime, schools, amenities, transport, flood risk or deprivation, with filters and a sort order. Returns the ranked rows with the typed query it ran, so the answer can be checked and run again. Deprivation questions need a nation or a district, because deciles are relative within a nation. Takes 20 to 40 seconds while the question is planned. For one named place use get_area_signals or score_postcode; to compare named places use compare_postcodes; for places like a known one use find_peers. Each call uses one plain-English question from the key's monthly allowance. The question goes to a third-party language model (Anthropic, or another provider at onegoodarea.com/privacy) to plan the query; it never sees account details or result rows. There is no data for places outside England, Wales and Scotland, such as Belfast; do not call it for them.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | A question that ranks or filters neighbourhoods in England, Wales or Scotland by their signals. Examples: 'neighbourhoods in Manchester with a median price under £250k and prices rising', 'the ten least deprived neighbourhoods in Wales', 'areas in Leeds with the most Outstanding schools within 1.5 km'. Max 500 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/destructive annotations, it discloses latency (20 to 40 seconds), the per-call cost against a monthly allowance, and that the question is sent to a third-party language model that never sees account details or result rows, with a privacy link. That is unusually rich disclosure. It stops short of describing pagination or row limits on the ranked output, which is the remaining gap and the main reason this is 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?
It is long but front-loaded and every sentence carries load: scope, return shape, prerequisite, latency, sibling routing, cost, privacy and the out-of-scope exclusion. No filler or repeated information, and the most decision-relevant facts come first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return: 'the ranked rows with the typed query it ran, so the answer can be checked and run again.' Combined with latency, cost and scope limits, nothing an agent needs in order to decide whether to call it and what it will get back is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already supplies examples and a 500-character limit, so the baseline would be 3. The description adds a real constraint the schema does not carry: deprivation questions must specify a nation or a district because deciles are relative within a nation. That is genuine added meaning 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 verb and resource ('Finds and ranks the neighbourhoods') plus the exact geographic scope (England, Wales or Scotland) and the signals it ranks on. It explicitly distinguishes itself from the siblings find_peers, compare_postcodes, get_area_signals and score_postcode, so an agent can route correctly without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing rules: 'For one named place use get_area_signals or score_postcode; to compare named places use compare_postcodes; for places like a known one use find_peers.' It also names exclusions — no data for places outside England, Wales and Scotland, 'do not call it for them' (e.g. Belfast) — and a precondition that deprivation questions need a nation or district. When-to-use, when-not-to-use and alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds the neighbourhoods most similar to one place in England, Wales or Scotland by nearest-neighbour distance over normalised signal values. Returns the target neighbourhood code, the signals used, and a ranked list of peers with distance (0 identical, 1 maximally distant) and the number of signals each comparison used. Fits 'areas like this one'; for a ranking filtered by named signals, find_areas.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | How many peers to return. Default 20, at most 200. | |
| area | Yes | A postcode (e.g. 'SW1A 1AA'), a place name (e.g. 'Manchester city centre') or a neighbourhood code (e.g. 'E01003920') in England, Wales or Scotland. Up to 100 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, non-destructive, and closed-world, so the safety burden is lifted. The description adds genuinely useful behavioral context by spelling out the return shape (target code, signals used, ranked peers) and the distance semantics (0 identical, 1 maximally distant) plus the per-comparison signal count.
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, front-loaded with the core action, then output semantics, then the sibling routing. Every clause carries information; nothing 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?
Despite no output schema, the description fully explains what is returned and how to interpret distances and signal counts. Combined with annotations and full param coverage, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (area formats, k default/min/max) are already fully documented in the schema. The description adds only the geographic constraint, which the schema also states, 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 (Finds), resource (neighbourhoods most similar to one place), geographic scope, and the method (nearest-neighbour distance over normalised signal values). It explicitly names the sibling find_areas as the different case, so an agent can separate the two without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly tells the agent when to use it ('areas like this one') and when to prefer the alternative ('for a ranking filtered by named signals, find_areas'). No inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every signal OneGoodArea holds for one place in England, Wales or Scotland, across crime, deprivation, property, schools, amenities, transport and environment: value with unit, percentile where the store has one, confidence with the engine's reason, source and observation period. Deprivation includes each nation's domain deciles (income, employment, health, education and more) with the published rank and score. This is the data behind every score; for one category only, get_signals_by_category.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | A postcode (e.g. 'SW1A 1AA'), a place name (e.g. 'Manchester city centre') or a neighbourhood code (e.g. 'E01003920') in England, Wales or Scotland. Up to 100 characters. | |
| sort | No | Optional. Order signals newest first by their period, by when OneGoodArea loaded them, or by the publisher's release date. Omit to keep catalogue order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: the per-signal payload shape (value with unit, percentile, confidence plus the engine's reason, source, observation period) and the depth of deprivation data with deciles, rank and score.
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 verb and resource, then uses the remaining space for payload detail and sibling routing. The long enumerations of categories and returned fields are dense but each clause carries information; no filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is responsible for conveying what comes back, and it does so in reasonable detail (value/unit, percentile, confidence, source, period, deprivation deciles). It stops short of describing volume, pagination or handling of sparse coverage, which an agent calling for 'every signal' might care about.
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 both the area formats and the sort enum are fully documented in the schema itself. The description adds nothing about parameter syntax or defaults beyond restating the geographic scope, 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 ('Returns every signal OneGoodArea holds for one place') plus the geographic scope (England, Wales or Scotland) and the full category coverage. It also explicitly names the sibling it is not (get_signals_by_category), so an agent can choose between them 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?
Provides a clear selection rule: use this for all data behind every score, and get_signals_by_category when only one category is needed. It lacks explicit exclusions (e.g. outside Great Britain, or when a targeted score lookup is preferable), but the named alternative is enough to route most calls correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports material signal changes across a portfolio between two periods: the baseline and threshold used, counts of places checked and changes found, and for each place every signal that moved with direction, from and to values, delta, percent change and the cause (the source data moved, or a OneGoodArea methodology release named by version). Needs a portfolio id from watch_portfolio. Reading does not fire the portfolio's webhooks.
| Name | Required | Description | Default |
|---|---|---|---|
| cause | No | List only changes with these causes: source (the source data moved it), method (a OneGoodArea methodology release did, same period), source_and_method (both). Default every cause. | |
| baseline | No | Compare the latest period with the previous period (default) or with the first period in range. | |
| portfolio_id | Yes | The portfolio id returned by watch_portfolio (e.g. 'pf_...'). | |
| threshold_pct | No | Smallest absolute percent change that counts as material. Default 5. Zero or more. | |
| min_transactions | No | Sample-size gate for price moves: both periods need at least this many sales. Whole number, zero or more; default 8. |
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 covered. The description adds a genuinely non-obvious side-effect fact ('Reading does not fire the portfolio's webhooks') and describes the shape of what comes back, which matters because no output schema exists. It stops short of pagination or rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then the return contents, then the prerequisite and side-effect note. It is one long dense sentence with no wasted clauses, though the packing of counts, per-signal fields and cause taxonomy into a single sentence is slightly heavy for scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining returns and does so thoroughly (counts of places checked/changes found, per-place signals with direction, from/to, delta, percent change, cause). The prerequisite id source and the webhook side-effect are also covered; only error behavior and large-portfolio handling are 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 description coverage is 100%, so the schema already documents all five parameters including enum meanings for cause and baseline and the defaults for threshold_pct and min_transactions. The description restates the cause semantics (source data moved vs. a named methodology release) and the baseline/threshold concept but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (reports) and resource (material signal changes across a portfolio between two periods), and enumerates the returned content (baseline/threshold used, counts, per-place signal movements). Combined with the portfolio-scoped framing and the reference to watch_portfolio, an agent can distinguish this from area-level siblings like get_area_signals 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?
The prerequisite is stated ('Needs a portfolio id from watch_portfolio'), which is real usage context, but there is no explicit when-to-use versus when-not, and no alternative is named for the case where an agent wants per-area rather than per-portfolio changes. Usage is implied rather than routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the signals of one category for a place in England, Wales or Scotland, in the same shape as get_area_signals: value with unit, percentile where the store has one, confidence with reason, source and observation period. Categories: crime (police.uk), deprivation (IMD, WIMD and SIMD with each nation's domain deciles, rank and score), property (HM Land Registry), schools (Ofsted, Estyn, Education Scotland), amenities and transport (OpenStreetMap), environment (flood risk from the Environment Agency, Natural Resources Wales and SEPA).
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | A postcode (e.g. 'SW1A 1AA'), a place name (e.g. 'Manchester city centre') or a neighbourhood code (e.g. 'E01003920') in England, Wales or Scotland. Up to 100 characters. | |
| sort | No | Optional. Order signals newest first by their period, by when OneGoodArea loaded them, or by the publisher's release date. Omit to keep catalogue order. | |
| category | Yes | The category to return: crime, deprivation, property, schools, amenities, transport or environment. |
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 covered. The description adds real value beyond that: the exact return fields (value with unit, percentile, confidence with reason, source, observation period) and the upstream publisher behind each category. It does not mention rate limits or coverage gaps within the three nations.
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 and output shape, then a single dense sentence mapping categories to sources. Every clause carries information, though the category list partially duplicates the schema enum and the sentence is long enough to be awkward 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?
With no output schema, the description compensates by describing the return shape and field set, and it bounds the service area to England, Wales and Scotland. Combined with annotation-covered safety and a fully-described schema, an agent has enough to call it correctly; pagination and result-size limits remain 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 coverage is 100%, so the baseline is 3. The description exceeds it by attaching provenance to each category value (crime = police.uk, deprivation = IMD/WIMD/SIMD with domain deciles/rank/score, property = HM Land Registry, environment = EA/NRW/SEPA), which meaningfully enriches the enum beyond the schema's bare list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the signals of one category for a place') with geographic scope, and explicitly anchors itself to the sibling get_area_signals by promising the same output shape. An agent can distinguish it from get_area_signals 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?
The description implies usage by naming the parent tool's shape ('same shape as get_area_signals') and enumerating the seven categories, but never states the selection rule — e.g. 'use this instead of get_area_signals when you need only one category' — nor any prerequisites or exclusions. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explains how one scoring dimension is computed: its data source, the scoring summary and its weight under each preset. Answers 'why did Crime score 80' and supports procurement or model-risk review. Static lookup, no API call. Recognised dimensions: Crime, Deprivation, Property, Schools, Amenities, Transport, Environment.
| Name | Required | Description | Default |
|---|---|---|---|
| dimension | Yes | The dimension name. Case does not matter and a partial match works (e.g. 'environ' matches 'Environment'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: this is a static local lookup requiring no API call, which tells the agent there is no latency or external dependency to manage.
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, front-loaded with the core purpose, then use cases, then the static-lookup note and valid values. No filler; every clause contributes information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with no output schema, the description adequately covers what the tool does and what it returns (data source, summary, weight). Minor gap: it doesn't describe the shape of the response or whether multiple presets are listed, but that is a small omission for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains case-insensitivity and partial matching. The description goes further by enumerating the recognised dimension names (Crime, Deprivation, Property, etc.), which the schema lacks since no enum is defined — this genuinely helps the agent construct a valid call.
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 ('Explains how one scoring dimension is computed') and enumerates the content returned: data source, scoring summary, and per-preset weight. It is clearly distinguishable from siblings like score_postcode or get_area_signals, which produce scores rather than explain them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use contexts ('answers why did Crime score 80', 'supports procurement or model-risk review') and clarifies it is a static lookup with no API call. It does not name an alternative sibling or state when not to use it, so it stops short of explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a postcode, place name, official neighbourhood code or OneGoodArea place id to the permanent place it names in England, Wales or Scotland. Returns the place id (oga_pl_...), its type and name, country and nation, how the input resolved, and for a postcode whether it is live or retired with the month it was retired; a retired postcode still resolves to the neighbourhood it was in. A name that could mean several places returns the candidates with their ids; an input that names nothing returns the reason. Call it first when an input may be retired or ambiguous, or to obtain an id that survives boundary changes before calling the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A postcode (e.g. 'SE15 5DP'), a place name (e.g. 'Peckham'), an official code (e.g. 'E01003920') or a place id (e.g. 'oga_pl_...'). Up to 100 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a non-destructive read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds substantial behavior beyond them: retired postcodes still resolve to their former neighbourhood, ambiguous names return candidates with ids, and unresolvable input returns a reason. Those are outcome-shaping behaviors an agent cannot infer 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 verb, resource and accepted inputs, then the return shape, then usage routing — a logical order. The middle clause listing every returned field is dense but each item is informative; the description is slightly long, which keeps it from a 5.
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?
There is no output schema, so the description carries the full burden of describing returns, and it does: place id (oga_pl_...), type, name, country, nation, resolution method, postcode liveness with retirement month, candidate lists, and failure reasons. Nothing needed to call it correctly or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required param, so the baseline is 3; the description earns an extra point by tying each accepted input form to its downstream result (postcode liveness/retirement month, candidate lists for ambiguous names, reason for non-matches). It does not add format or validation detail beyond the schema, so it falls short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (resolve) and resource (a place), and enumerates exactly which input forms it accepts: postcode, place name, official neighbourhood code, or OneGoodArea place id, scoped to England, Wales and Scotland. This is clearly distinguishable from siblings like find_areas or score_postcode, which operate on already-known areas.
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 instructs to 'call it first when an input may be retired or ambiguous, or to obtain an id that survives boundary changes before calling the other tools.' It gives both the triggering condition and the ordering relationship to the sibling toolset, which is exactly the routing guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scores one place in England, Wales or Scotland for a decision preset: an overall 0 to 100 score, seven weighted dimensions each with confidence and the engine's reasoning, a one-paragraph summary, recommendations drawn from low-scoring or low-confidence dimensions, and the public datasets used. Deterministic, with the methodology version stamped on the response. For the underlying numbers rather than a composite, get_area_signals; for several places at once, compare_postcodes.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | A postcode (e.g. 'SW1A 1AA'), a place name (e.g. 'Manchester city centre') or a neighbourhood code (e.g. 'E01003920') in England, Wales or Scotland. Up to 100 characters. | |
| preset | Yes | The decision the score is for. 'moving' = how liveable a place is for a household (safety, affordability and schools weigh most). Choose it for a home move; lenders use it for residential mortgage origination. 'business' = site selection (footfall, competition, commercial viability). 'investing' = investment scoring (yield, growth, regeneration). 'research' = reference scoring (neutral baseline across all seven dimensions). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds genuinely new behavioral context: results are deterministic and carry a methodology version stamp, and the response contains seven weighted dimensions, confidence values, reasoning, recommendations and dataset provenance. It stops short of stating latency, limits, or failure modes, which keeps it at a 4.
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, front-loaded with what the tool returns and closed with the sibling routing. The first sentence is a long enumerated list, but every item conveys real information about the response shape rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by enumerating the response contents and noting the stamped methodology version. Combined with geographic scope, determinism, and sibling routing, an agent has everything needed to invoke this two-parameter read-only tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'area' and 'preset' are already fully documented, including per-enum-value explanations. The description adds no further parameter meaning (e.g. what happens with an ambiguous place name), so the baseline of 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 ('Scores one place') plus the geographic scope (England, Wales or Scotland) and the preset-driven nature of the output. It explicitly distinguishes itself from get_area_signals (raw numbers) and compare_postcodes (multiple places), so an agent can select it without opening a sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names both alternatives with the exact condition that selects them: 'For the underlying numbers rather than a composite, get_area_signals; for several places at once, compare_postcodes.' The singular-vs-multiple and composite-vs-raw distinctions cover the realistic routing decisions an agent faces among these siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a named Monitor portfolio and adds the places to track, in one call. Returns the portfolio id and the tracked places. Every call creates a new portfolio, so call it once per portfolio and keep the id; get_portfolio_changes reads material changes for it afterwards. Places are postcodes, place names or neighbourhood codes in England, Wales or Scotland.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name for the portfolio. 1 to 200 characters. | |
| areas | Yes | Postcodes, place names or neighbourhood codes in England, Wales or Scotland to track. 1 to 100 entries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description corroborates and adds real context by warning that "Every call creates a new portfolio" (the practical consequence of non-idempotency) and naming the returned id. It also discloses geographic coverage limits (England, Wales, Scotland). It does not cover failure modes for unresolvable places, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all load-bearing: creation semantics first, id/retrieval workflow second, input domain third. No filler or repetition of schema constraints.
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?
No output schema exists, but the description compensates by stating what is returned (portfolio id and tracked places), which is exactly what an agent needs to chain into get_portfolio_changes. Coverage of error handling for invalid areas is absent, but nothing essential 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 both parameters (name, areas) are already documented in the schema, including the character and item limits. The description's geographic scope note on areas largely duplicates the schema text. 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?
Specific verb+resource: "Creates a named Monitor portfolio and adds the places to track, in one call." It distinguishes itself from the similarly named sibling get_portfolio_changes by stating that one reads changes while this one creates the portfolio.
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 call cadence and the follow-on tool: "call it once per portfolio and keep the id; get_portfolio_changes reads material changes for it afterwards." Both when-to-use and the alternative are named, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
compare_postcodes1 field changedInput schema / properties / preset / descriptionPrevious value: -"The preset applied to every place: 'moving' for residential mortgage origination, 'business' for site selection, 'investing' for yield and growth, 'research' for a neutral baseline."New value: +"The preset applied to every place: 'moving' for how liveable a place is for a household (safety, affordability and schools weigh most; choose it for a home move, lenders use it for residential mortgage origination), 'business' for site selection, 'investing' for yield and growth, 'research' for a neutral baseline."score_postcode1 field changedInput schema / properties / preset / descriptionPrevious value: -"The decision the score is for. 'moving' = residential mortgage origination (suitability, demand-side risk). 'business' = site selection (footfall, competition, commercial viability). 'investing' = investment scoring (yield, growth, regeneration). 'research' = reference scoring (neutral baseline across all seven dimensions)."New value: +"The decision the score is for. 'moving' = how liveable a place is for a household (safety, affordability and schools weigh most). Choose it for a home move; lenders use it for residential mortgage origination. 'business' = site selection (footfall, competition, commercial viability). 'investing' = investment scoring (yield, growth, regeneration). 'research' = reference scoring (neutral baseline across all seven dimensions)."
Add one secure layer between your agents and this server.