Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@statsmapped-mcp Rank Irish counties by median house price"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server exposing StatsMapped's public API as tools for AI agents (Claude Desktop, Cursor, and any other MCP client).
StatsMapped tracks public data for Ireland (by county) and the UK (by local authority) — housing,
crime, health, the economy and social welfare — from official publishers (CSO, PSRA, Central Bank
of Ireland, DHLGH, NTPF, the Office of Government Procurement, EU Publications Office for Ireland;
ONS/HM Land Registry/Nomis/DfE/DfT for the UK), each figure carrying its own caveats. This
package lets an agent query that data directly as tool calls instead of crawling and parsing
web pages. Every tool below takes a country argument ("ireland" or "united-kingdom",
default "ireland") — the two countries track genuinely different datasets and geography levels,
so call list_datasets/list_areas for the country you actually want rather than assume
Ireland's defaults apply.
This is a thin client. It calls StatsMapped's already-public, unauthenticated HTTPS API
(documented at statsmapped.com/openapi.json); no API key
is needed for anything below. Runs on your own machine over stdio by default (the recommended way
to use it today) -- see Why stdio for a hosted
streamable-http mode this package also supports, and the real tradeoff that comes with it.
Not yet published to PyPI. Once it is, install will be:
pip install statsmapped-mcpRelated MCP server: UK ONS MCP Server
Add to your MCP client's config (for Claude Desktop, claude_desktop_config.json; Cursor uses an
equivalent mcp.json):
{
"mcpServers": {
"statsmapped": {
"command": "statsmapped-mcp"
}
}
}Every tool takes a country argument ("ireland" or "united-kingdom", default "ireland") —
Ireland and the UK track different datasets and geography levels, so call list_datasets/
list_areas for the country you want rather than assume Ireland's defaults apply.
list_datasets(country="ireland") — every stat StatsMapped tracks for one country, with its
key, label, and which geography levels it's published at. Start here.
list_areas(level="county", country="ireland") — every geography at one boundary level.
level defaults to Ireland's 26 counties; the UK's own primary level is "lad" (local
authority districts), not "county" — other levels exist per country too (Ireland's
local_authority/garda_division among them).
list_area_datasets(area_id, country="ireland") — every dataset available for one area
(e.g. "county:kerry" for Ireland, "uk:lad:e09000033" for the UK), with its latest figure
and year-on-year change. Caveats are projected to label + severity only, not full text — the
point is deciding which datasets matter before paying for the full detail on any one of them.
get_dataset_for_area(area_id, dataset, history_months=0, country="ireland") — full detail
on one dataset in one area: a written summary, full caveat text, and (optionally) recent
history.
rank_areas(stat_key, level="county", country="ireland") — every area at one level, ranked
by its latest figure for one stat, highest first.
list_comparisons(country="ireland") — every registered cross-dataset comparison pair for
one country (e.g. "median sale price vs new dwelling completions per 1,000 residents"). A
small, hand-curated set, not an arbitrary-pair engine.
get_comparison(pair_key, country="ireland") — full detail for one registered pair: each
axis's label/unit/publisher, the correlation stats (r, rho, a leave-one-out sensitivity range),
and caveats. pair_key comes from list_comparisons(country=...) for the same country.
check_comparability(stat_key_a, stat_key_b, country="ireland") — does StatsMapped have a
registered, hand-vetted comparison between these two stats? Registry-backed only — never
computes a fresh correlation for an arbitrary pair; comparable: false is a normal result for
most pairs, not an error.
explain_metric(stat_key, country="ireland") — definition, methodology and standing caveats
for one stat, never a current figure. Use this when the question is about what a metric means or
how it's measured, not about one area's value.
StatsMapped runs on a single free-tier instance. A remote MCP endpoint hosted there would let an agent's own multi-area query pattern (calling the same tool once per area, in a loop) reproduce exactly the load pattern that has already caused timeouts on that instance under a large geography fan-out. Running over stdio means every call goes through your own network connection to the same public HTTPS API this package's tools call directly, with no shared bottleneck -- each user's own machine makes the HTTP calls, so N users' traffic is naturally spread across N source IPs, not funnelled through one.
server.py also supports a real hosted streamable-http mode (MCP_TRANSPORT=streamable-http)
for a deployment that accepts that tradeoff -- StatsMapped's public API is itself rate-limited
per source IP (600 requests/hour), but a hosted MCP endpoint proxies every remote user's calls
through ONE shared egress IP, so all remote users of a hosted endpoint would share that one
bucket rather than each getting their own. A StatsMapped-hosted endpoint is live at https://mcp.statsmapped.com
(Streamable HTTP) -- confirmed responding correctly, no separate install needed for a client
that speaks Streamable HTTP directly.
pip install -e .
python tests/test_client.pyThe test suite runs against the real live API (https://statsmapped.com by default, or
STATSMAPPED_MCP_BASE_URL if set) — read-only GETs only, nothing here writes any data or needs
a key.
Publishing to PyPI happens automatically via .github/workflows/publish.yml on creating a
GitHub Release — no API token is stored anywhere. It uses
PyPI's Trusted Publishing (OIDC): PyPI is told,
once, to trust this exact repo + workflow file + GitHub environment (pypi) combination, via
PyPI's own "Publishing" settings page under this project. To release: bump version in
pyproject.toml, commit, then draft a GitHub Release with a matching tag (e.g. v0.2.0).
MIT for this package. The underlying data keeps each publisher's own licence — see
statsmapped.com/ireland/sources for Ireland's own
publisher/licence detail before reusing any figure outside of querying it through an agent (a UK
equivalent page doesn't exist yet — check each UK tool response's own caveats/sources fields
in the meantime).
Does StatsMapped have a registered, hand-vetted comparison between these
two stats ('ireland' or 'united-kingdom')? Registry-backed only -- never
computes a fresh correlation for an arbitrary pair. Both stat_keys come from
list_datasets(country=...) for the SAME country. A comparable: false
result is normal and expected for most pairs (the registry is small and
hand-curated) -- treat it as StatsMapped saying it has not vetted a
relationship between these two stats, not as an error to route around.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland | |
| stat_key_a | Yes | ||
| stat_key_b | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the behavioral burden. It clearly discloses that the tool is registry-backed only, hand-curated, does not compute correlations, and returns false as an expected outcome rather than a failure. This is strong transparency, though it doesn't mention side effects or auth needs (which appear irrelevant for a lookup).
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 with no wasted content: purpose, restrictions, and result interpretation are all present. The first sentence is a question rather than a declarative, and the parenthetical creates mild confusion, but overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives all necessary preconditions for invocation and explains how to interpret a false result. Since an output schema exists, return-value details are not needed. It could mention what to do when comparable is true, but that is not essential 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 description coverage is 0%, so the description must compensate. It adds that stat_keys must come from list_datasets for the same country and hints at country values ('ireland' or 'united-kingdom'). However, the parenthetical placement is ambiguous (it appears after 'stats', not country) and it never defines what a stat_key looks like. Partial compensation for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (checks existence of a registered, hand-vetted comparison), names the resource (StatsMapped registry), and distinguishes itself from computing fresh correlations with 'never computes a fresh correlation'. This makes it distinct from siblings like list_comparisons or get_comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-not-to-use guidance ('never computes a fresh correlation for an arbitrary pair') and a hard prerequisite: both stat_keys must come from list_datasets(country=...) for the SAME country. It also pre-empts misinterpretation by stating that a 'comparable: false' result is normal and should not be routed around as an error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Definition, methodology and standing caveats for ONE stat ('ireland' or
'united-kingdom') -- never a current figure. Call this when the question is
about what a metric MEANS or how it's measured ("how is the claimant count
defined", "is this a mean or a median"), not about a specific area's value --
get_dataset_for_area/rank_areas already answer that. stat_key comes
from list_datasets(country=...) for the SAME country.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland | |
| stat_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it explicitly states the tool never returns a current figure and is limited to one stat at a time. It also communicates the dependency between stat_key and country via list_datasets. This is clear behavioral disclosure beyond what the schema provides.
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 dense sentences with no filler. The core definition is front-loaded, the when-to-use guidance follows, and the parameter provenance is stated at the end. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description is complete: it explains what the tool returns, what it never returns, when to use it, and how to obtain the required stat_key. Nothing essential is missing for an agent to invoke 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 0%, so the description must compensate. It partially does: it indicates the country values ('ireland' or 'united-kingdom') and explains that stat_key comes from list_datasets(country=...) for the same country. It stops short of listing possible stat_key values or formats, but the source guidance is strong.
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 clearly states the tool's purpose: provide definition, methodology, and caveats for one metric, not current values. It also distinguishes itself from get_dataset_for_area and rank_areas, which answer area-value questions. This makes the tool's role 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?
It explicitly says when to call: when the question is about what a metric means or how it is measured, and when not to call by naming the siblings that already answer value queries. It also tells the agent where to source stat_key from, list_datasets(country=...) for the same country.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one registered comparison pair: each axis's label, unit
and publisher, the correlation stats (r, rho, and a leave-one-out
sensitivity range naming the single most influential area), and caveats.
pair_key comes from list_comparisons(country=...) for the SAME country.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland | |
| pair_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the tool returns detailed axis labels/units/publishers, correlation statistics (r, rho), a leave-one-out sensitivity range naming the most influential area, and caveats. It also reveals the important constraint that the pair_key must come from the same country. It does not explicitly state that the operation is read-only, but 'full detail' clearly implies retrieval.
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 compact and front-loaded: the main purpose is stated first, followed by a tight enumeration of return contents and a single sentence about the required source of pair_key. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool has only two parameters, the description covers what the tool returns, where the key parameter comes from, and the country-consistency requirement. An agent has enough information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add real semantics for pair_key by specifying it comes from list_comparisons(country=...) for the same country, and it indirectly ties the country parameter to that call. However, it does not define valid country values, pair_key format, or the optional/default behavior beyond what the schema already shows.
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: 'Full detail for one registered comparison pair,' and then enumerates exactly what is returned (axis metadata, correlation stats, sensitivity range, caveats). This clearly distinguishes it from list_comparisons, which lists pairs rather than giving full detail.
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 context for when to use the tool: after obtaining a pair_key from list_comparisons(country=...), and it stresses that the pair_key must come from the SAME country. It does not explicitly list exclusions or alternatives beyond that prerequisite, 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.
Full detail for one dataset in one area: the latest figure, a written
summary, full caveat text, and (if history_months is set) recent history.
dataset is a series_key from list_area_datasets' own response.
history_months means actual months of history (0 = everything) -- e.g. 24
returns 2 years of an annual series, not 24 years. country must match
area_id's own country.
| Name | Required | Description | Default |
|---|---|---|---|
| area_id | Yes | ||
| country | No | ireland | |
| dataset | Yes | ||
| history_months | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the returned components, explains the subtle `history_months` semantics with a concrete example, and states the `country` matching requirement. It stops short of explicitly saying the operation is read-only, but the 'get' framing makes that reasonably clear.
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 dense sentences with no filler: the primary purpose is front-loaded, followed by parameter semantics that add real value. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return contents, parameter constraints, and the relationship to `list_area_datasets`, while the existing output schema handles return-shape details. It could be slightly more explicit about `area_id` format or error conditions, but nothing material is 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 description coverage is 0%, so the description must compensate. It meaningfully explains `dataset`, `history_months`, and `country`, including the non-obvious 'actual months' behavior. `area_id` is only indirectly defined via its relationship to `country`, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Full detail for one dataset in one area' and specifies exactly what that includes (latest figure, written summary, caveat text, optional history). It also references `list_area_datasets`, distinguishing this retrieval tool from the listing sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit invocation context: `dataset` must be a `series_key` from `list_area_datasets`' own response, and `country` must match the area's country. It does not explicitly enumerate when not to use this tool or name alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every dataset available for one area (e.g. "county:kerry" for
Ireland, "uk:lad:e09000033" for the UK), with its latest figure, year-on-
year change, and caveat labels only (not full caveat text -- call
get_dataset_for_area for the full detail on any one dataset that
matters). Area ids come from list_areas -- country must match whichever
country that call used, or this simply 404s ("unknown geography").
| Name | Required | Description | Default |
|---|---|---|---|
| area_id | Yes | ||
| country | No | ireland |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden and does so well: it states what is returned (latest figure, year-on-year change, caveat labels only) and the failure mode (404 'unknown geography' when country doesn't match). This gives an agent concrete expectations beyond the bare tool name.
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?
Every sentence earns its place: purpose, output contents, the alternative for full detail, and the prerequisite/error condition. The description is compact, front-loaded, and easy for an agent to parse quickly.
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 an output schema, the description covers purpose, parameter semantics, error behavior, and the appropriate sibling for deeper detail. Nothing critical is missing for an agent to invoke 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 0%, but the description compensates by giving concrete area_id formats ('county:kerry', 'uk:lad:e09000033'), explaining that area ids come from list_areas, and clarifying that country must match the originating call. It doesn't enumerate all country values, but country has a default and a clear dependency, which is sufficient.
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 action ('List every dataset available for one area') and identifies the resource clearly, so an agent immediately knows what this tool does. It also distinguishes itself from get_dataset_for_area by noting that it returns caveat labels only, not full caveat text.
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 explicitly routes to get_dataset_for_area when full caveat detail is needed, and gives prerequisites: area ids come from list_areas and country must match the originating call. It doesn't explicitly contrast with list_datasets, but the 'one area' scope implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every geography at one boundary level, for one country ('ireland'
or 'united-kingdom'). level defaults to "county" (Ireland's 26 counties);
the UK's own primary level is "lad" (local authority districts), not
"county". Other levels exist per country (e.g. Ireland's "local_authority",
"garda_division") -- see a dataset's own compatible_levels from
list_datasets for which levels a given stat is actually published at.
Returns each area's id (used by list_area_datasets/get_dataset_for_area,
always paired with the SAME country) and name.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | county | |
| country | No | ireland |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does meaningful work: it says the tool returns every geography at a single boundary level, only `id` and `name`, and that `id` must always be paired with the same `country`. It does not cover pagination or error behavior, but the core behavioral contract is clear.
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 main action is front-loaded in the first clause, and every subsequent sentence adds needed context: level defaults, country-specific differences, how to discover valid levels, and how the returned `id` is used downstream. The length is justified because the content is dense and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter enumeration tool with an output schema, the description covers the essential operational context: valid countries, level defaults, the UK exception, and downstream consumers of the returned `id`. It omits details like pagination or whether zero results are possible, but these are minor given the output schema and the explicit scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the parameters, and it does: it names the two allowed `country` values and explains `level` with defaults, a UK-specific exception, and examples of other valid levels. It also connects `level` selection to a dataset's `compatible_levels`, adding meaning far beyond the bare 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-resource pair: 'List every geography at one boundary level, for one country,' which unambiguously identifies the tool's job. It also distinguishes the tool from siblings by noting the returned `id` is consumed by `list_area_datasets`/`get_dataset_for_area`, so an agent can tell it apart from dataset-listing or ranking 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?
It gives concrete selection guidance: `level` defaults to 'county' for Ireland, the UK's primary level is 'lad' rather than 'county', and other per-country levels exist. It also directs users to `list_datasets`' `compatible_levels` to see which levels a stat is published at, but it does not explicitly state when not to use this tool versus each sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every registered cross-dataset comparison pair for one country
('ireland' or 'united-kingdom') -- e.g. "median sale price vs new dwelling
completions per 1,000 residents". A small, hand-curated set, not an
arbitrary-pair engine: pass one of the returned pair_key values to
get_comparison for the real correlation and axis detail.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the set is small and hand-curated, not an arbitrary-pair engine, and that the output provides pair_key values for get_comparison. It doesn't mention side effects or edge cases, but for a listing tool this is sufficient and adds meaningful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. The purpose is front-loaded, the example clarifies instantly, and every sentence adds value. It is concise without being under-specified.
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 that an output schema exists (as indicated by context signals), the return format is likely documented elsewhere. The description covers the essential elements: what it lists, valid country values, and how to proceed with get_comparison. It doesn't mention error handling or ordering, but these are minor given the tool's simplicity and the presence of an 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?
The schema coverage is 0% and the only parameter (country) has no enum, only a default. The description explicitly enumerates the valid values ('ireland' or 'united-kingdom'), which is critical information that the schema does not provide. This goes well beyond what the input schema alone conveys, though it doesn't elaborate on the meaning of the parameter beyond its allowed values.
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 uses a specific verb ('List') and a clear resource ('cross-dataset comparison pair'), provides a concrete example, and explicitly contrasts itself with an 'arbitrary-pair engine.' It also names the sibling tool get_comparison for the next step, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use it (to list curated pairs for a country) and instructs passing a returned pair_key to get_comparison for details. It doesn't explicitly exclude other siblings like check_comparability, but the hand-curated vs arbitrary distinction implies a specific role. This is clear context with no exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every dataset (stat) StatsMapped tracks for one country ('ireland'
or 'united-kingdom'), with its key, human label, and which geography levels
it can be shown at. Ireland and the UK track genuinely different datasets --
call this for the right country before assuming a stat_key exists there.
Call this first to find the right stat_key for rank_areas -- for
get_dataset_for_area, use list_area_datasets instead, which returns
the series_key that call actually needs.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | ireland |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that Ireland and the UK track genuinely different datasets, warns to call for the right country, and clarifies that this returns stat_key for rank_areas. It does not mention pagination, access permissions, or error behavior, but for a read-only listing operation the key behavioral caveat is present. Slightly more detail could lift it to 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with the purpose front-loaded in the first line. Each sentence earns its place: the first states the core action, the second adds the country-specific caveat, and the third routes to sibling tools. It is slightly verbose but efficient and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single optional parameter, an output schema present, and no annotations, the description covers the allowed parameter values, the key behavioral caveat (country specificity), and routing to sibling tools. No critical information needed to invoke 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 input schema has zero parameter descriptions (0% coverage) and only a default value for 'country'. The description compensates fully by explicitly enumerating the two allowed values ('ireland' or 'united-kingdom') and explaining the country-dependent dataset variation, which is essential semantic information not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List every dataset') and the resource (datasets/stat stats StatsMapped tracks for a country), including the output fields (key, human label, geography levels). It explicitly differentiates from sibling list_area_datasets by noting that get_dataset_for_area requires list_area_datasets instead, so an agent can tell tools apart 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?
It provides explicit when-to-use guidance: 'Call this first to find the right stat_key for rank_areas' and when-not-to-use guidance: 'for get_dataset_for_area, use list_area_datasets instead'. It also warns to call for the correct country before assuming a stat_key exists, covering the main conditional use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank every area at one geography level by its latest figure for one stat,
for one country -- e.g. "which counties have the highest median sale price"
(country="ireland") or "which local authorities award the most single-bid
contracts" (country="united-kingdom"). stat_key comes from
list_datasets(country=...) for the SAME country -- Ireland and the UK
track different stats. level omitted uses this ranking's own default
level; pass one of that dataset's own compatible_levels for a different
one -- a level this ranking doesn't have registered returns an empty list
rather than an error.
Where the underlying stat has no honest per-area denominator (crime,
homelessness, live_register and similar -- StatsMapped's own
RANKING_NO_DENOMINATOR_STATS), each row's rate_per_1000 is the real
figure to rank/compare by, not latest_value, which is a raw count
dominated by area population size. Always carry forward every entry in
caveats when using a row in an answer -- the same caveats StatsMapped's
own ranking pages and chat both attach to these figures.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| country | No | ireland | |
| stat_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does substantial work: it discloses that an unregistered level returns an empty list rather than an error, that rate_per_1000 is the correct ranking value for denominator-less stats, and that caveats must be carried forward. It does not mention sort order, but the output schema covers 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?
The description is long but every sentence earns its place: core purpose first, then parameter sourcing, then level behavior, then the critical denominator caveat and caveat-propagation rule. There is no filler or repetition of schema defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the zero annotations, and the low schema coverage, the description covers the non-obvious edge cases an agent needs: country-specific stat keys, invalid level behavior, denominator-less stat handling, and caveat propagation. An output schema exists for return shape, so the description is complete enough to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates. It explains how to source stat_key, clarifies that country must match the stat_key's country, and gives detailed semantics for level, including default behavior and compatible_levels. Even the special rate_per_1000-vs-latest_value distinction adds meaning beyond the raw 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 precise verb-resource-scope statement: 'Rank every area at one geography level by its latest figure for one stat, for one country.' Concrete examples ('which counties have the highest median sale price') make the operation unmistakable and clearly distinct from sibling tools like list_areas or list_datasets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives strong contextual guidance: stat_key must come from list_datasets for the same country, level must be omitted or come from compatible_levels, and country-specific stat differences are called out. It does not explicitly state 'use this instead of X' versus siblings, but the usage context is clear enough to route an agent correctly.
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.
v0.1.0check_comparabilityexplain_metricget_comparisonget_dataset_for_arealist_area_datasetslist_areaslist_comparisonslist_datasetsrank_areasScored across 9 tools
Each tool targets a distinct resource/action: global dataset listing, area listing, per-area dataset listing, detailed dataset retrieval, ranking, comparison listing, comparison details, comparability check, and metric explanation. The descriptions explicitly call out differences (e.g., stat_key vs series_key, list_datasets vs list_area_datasets), eliminating ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case: list_datasets, list_areas, list_area_datasets, get_dataset_for_area, rank_areas, list_comparisons, get_comparison, check_comparability, explain_metric. No mixed conventions or vague verbs.
9 tools is well within the ideal 3-15 range. Each tool serves a distinct purpose in the domain of querying Irish/UK statistical data, and none feel redundant or unnecessary.
The tool set covers the full lifecycle of data exploration: discovery (list_datasets, list_areas, list_area_datasets, list_comparisons), retrieval (get_dataset_for_area, get_comparison), ranking, comparability checking, and metric explanation. There are no obvious gaps; even history and caveats are handled.
Query UK Parliament, elections, crime stats, ONS census data, and national archives
UK property research tools - crime stats, schools, demographics, valuations for AI.
UK area & property intelligence for AI agents: reports, EPC, comparables, with source provenance.
Official UK, US and Australia public datasets as filtered CSV, REST API and MCP for AI agents.
