StatsMapped Public Data

compare

Use when the question is how areas rank or compare on a stat, or whether two stats can be compared fairly. For one area's own figures use query_data.

Four modes, depending on which arguments are given -- consolidates what
were four separate tools (rank_areas, list_comparisons, get_comparison,
check_comparability) behind one, since they are all really "how does this
stat compare" at different scopes. Exactly one mode's arguments should be
given; mixing arguments from different modes (e.g. both `stat_key` and
`pair_key`, or only one of `stat_key_a`/`stat_key_b`) raises an error
rather than silently guessing which mode was meant.

1. `stat_key` alone (no `pair_key`, no `stat_key_a`/`stat_key_b`): ranks
   every area at one geography level by its latest figure for that stat,
   for one country -- e.g. "which counties have the highest median sale
   price" (country="ireland"). `stat_key` comes from `query_data`'s
   dataset-listing mode, for the SAME country. `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.
2. `pair_key` alone: 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 mode 4's own
   response, for the SAME country.
3. Both `stat_key_a` and `stat_key_b` given: does StatsMapped have a
   registered, hand-vetted comparison between these two stats? Registry-
   backed only -- never computes a fresh correlation for an arbitrary
   pair. Both stat_keys come from `query_data`'s dataset-listing mode,
   for the SAME country. `verdict` is one of `"SUPPORT"` (a real,
   hand-vetted registered pair with no open caveats -- may be treated as
   a confirmed relationship), `"QUALIFY"` (hand-vetted, but the evidence
   carries real caveats -- e.g. no robustness check for outliers, or an
   unverified geography-level join; read `uncertainty` and `reasons`
   before presenting it as confirmed), `"REJECT"` (a real structural
   impossibility or a human-vetted "no" -- the two stats share no
   geography level at all, or a reviewer rejected this exact pairing),
   or `"INSUFFICIENT"` (not registered, not ruled out either --
   StatsMapped genuinely hasn't vetted this pair; never treat this as
   "probably comparable"). `uncertainty` names 4 separate dimensions
   (data_quality, comparability, statistical_strength,
   causal_strength) -- `causal_strength` is always `"not_established"`,
   since no comparison here implies causation regardless of verdict.
   `comparable` (DEPRECATED, kept only for callers that haven't
   migrated) collapses `verdict` to the old 3-way yes/no/unknown --
   `"yes"` for both `SUPPORT` and `QUALIFY` (both mean "hand-vetted",
   the old `comparable` meaning this field has always carried; the
   caveats a `QUALIFY` pair carries live in `uncertainty`/`reasons`,
   not in demoting `comparable`), `"no"` for `REJECT`, `"unknown"` for
   `INSUFFICIENT`. Prefer `verdict` directly when you need to
   distinguish a fully-confirmed `SUPPORT` from a caveated `QUALIFY`.
   Read `reasons` before presenting any answer other than `"SUPPORT"`
   as unqualified.
4. None of the above given: lists 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: pass one of the returned `pair_key`
   values to mode 2 for the real correlation and axis detail.

   `level` is only meaningful together with `stat_key` (mode 1); giving
   it without `stat_key` raises rather than silently dropping it and
   falling through to mode 4's unrelated pair listing.

Input Schema

Name	Required	Default
`level`	No
`country`	No	ireland
`pair_key`	No
`stat_key`	No
`stat_key_a`	No
`stat_key_b`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses error behavior on ambiguous arguments, that an unregistered level returns an empty list instead of an error, that `rate_per_1000` must be used over `latest_value` for no-denominator stats, that caveats must be carried forward, and that `causal_strength` is always 'not_established'. The deprecated `comparable` field's mapping to `verdict` is spelled out, which is exactly the kind of non-obvious contract an agent could otherwise get wrong.

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

Conciseness4/5

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

The numbered mode structure is excellent and the 'use when' clause is front-loaded, but the text is long and repeats 'for the SAME country' three times and re-explains the deprecated `comparable` collapse at length. Individual sentences earn their place, yet some of the detail could be tightened without losing semantics.

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

Completeness5/5

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

For a six-parameter, four-mode tool with zero annotation support, the description supplies everything an agent needs: mode dispatch rules, failure modes, key provenance, return-field interpretation, and caveat handling. An output schema exists, yet the description still explains the field semantics an agent cannot infer from structure alone.

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

Parameters5/5

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 and it does: every one of the six parameters is given meaning, valid-value provenance, and interaction rules (which combinations are legal, which raise, which are ignored). Mode 3's `verdict` enum values are defined individually with actionable interpretations, going well beyond what a bare schema could convey.

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

Purpose5/5

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

Opens with a specific verb+resource framing ('how areas rank or compare on a stat') and immediately enumerates the four distinct modes it serves, so an agent knows exactly what it returns for a given argument combination. It also names the sibling `query_data` as the tool for a single area's figures, making it distinguishable from alternatives in one sentence.

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

Usage Guidelines5/5

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

Explicitly routes the agent: 'For one area's own figures use `query_data`', then states the argument combination that selects each of the four modes and warns that mixing arguments raises an error rather than guessing. It also explains where each key value comes from (`stat_key` from query_data's dataset-listing mode, `pair_key` from mode 4) and that `level` is only valid alongside `stat_key`, so when-not-to-use is covered.

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

All StatsMapped Public Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.