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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "compare"
}
}Input Schema
| Name | Required | Description | 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 |