ilostat-mcp-server

Compare areas on an ILOSTAT dataset

ilostat_compare_geographies

Read-onlyIdempotent

Compare reference areas on one ILOSTAT dataset and one slice — a sex code plus breakdown codes, defaulting to the dataset's totals — giving each area's value at a common period or at its latest non-projected period, optional change over N years, and a rank, with each value's period, source, status, and basis (reported, modelled_estimate, or projection). A change carries the earlier value's source, basis, status, and notes, and flags whether the source or basis differs or the series breaks between the two values. Areas without a value are listed separately with the reason, and the response flags mixed periods and mixed bases rather than hiding them. Select areas by code list, by group (X01 for every country, an ILO region or subregion, or a World Bank income group), or both; X-coded aggregates require a dataset with aggregates.

Input Schema

Name	Required	Description	Default
`sex`	No	Sex code SEX_T, SEX_M, SEX_F, or SEX_O; T/M/F/O and total/both/male/female/other are accepted. Defaults to SEX_T on a dataset with a sex breakdown; refused on one without.
`sort`	No	Row order: value_desc (default), value_asc, or ref_area. rank is always by value, highest first.	value_desc
`period`	No	A common period, YYYY, YYYYQn, or YYYYMmm matching the dataset frequency (2024-Q2 and 2025-03 are normalized). Omit to compare each area at its latest period.
`classif1`	No	First breakdown code, case-insensitive. Defaults to the dataset's total code; required when the breakdown has no total (deciles); refused on a dataset without the breakdown. ilostat_describe_indicator lists the dataset's codes and marks its totals.
`classif2`	No	Second breakdown code; same defaults and rules as classif1.
`ref_areas`	No	Reference areas (up to 300): ISO3 codes (USA) or X-coded aggregates (X01 World); case-insensitive, ILO_GEO_ forms accepted. At least one of ref_areas or area_group is required.
`area_group`	No	X01 for every country, an ILO region or subregion, or a World Bank income group (X06, X56, X02, …); expands to its member countries. The group's own aggregate is compared only when listed in ref_areas. ilostat_list_reference topic area_groups lists the codes.
`dataset_id`	Yes	One dataset ID (UNE_DEAP_SEX_AGE_RT_A), as ilostat_search_indicators returns it; case-insensitive, a DF_ prefix (the SDMX dataflow form) stripped, a bare indicator code resolved when it has one frequency.
`change_years`	No	Adds each value's change from the same sub-period this many years earlier, in the dataset unit.
`lookback_years`	No	Latest mode: an area's latest value must fall within this many years of the current year.
`include_projections`	No	Latest mode: let projections (ILO modelled values after the cutoff) be an area's latest value.

Output Schema

Name	Required	Description
`cap`	No	Inline preview budget, in serialized characters.
`mode`	No	latest: each area's latest value; period: every area at one period.
`rows`	No	Areas with a value, in the requested order; the staged dataframe holds all when larger.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows returned inline.
`slice`	No	The one series compared per area.
`legend`	No	Labels for the status flags and note codes in rows.
`notice`	No	Mixed periods, mixed bases, changes that are not like-for-like, missing areas, a unit or area list the structure service could not supply, where the full comparison is staged, or why the inline rows stop early.
`period`	No	Period mode: the period compared.
`dataset`	No	One requested dataset and how its values are classed.
`missing`	No	Requested areas with no value, and why.
`dataframe`	No	The staged dataframe holding the full result; present only when staged.
`truncated`	No	True when the inline rows stop before the last area — also when a dataframe holds the full comparison.
`attribution`	No	Citation to keep with any use of the data.
`window_from`	No	Latest mode: the first year requested — lookback_years before the current year, and change_years further back to reach the change base. A latest value still falls within lookback_years.
`change_years`	No	Years the change is measured over, when requested.
`comparability`	No	What makes the current values more or less comparable, over every area; each change's baseline is compared by its own source_changed, basis_changed, and break_in_series.
`applied_filters`	No	Every parameter sent upstream.
`include_projections`	No	Whether a projection could be an area's latest value.

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedOct 15, 2026

changedOutput schema / properties / applied_filters / properties / time / description

Previous value: -"Exact periods sent (period mode)."New value: +"Exact periods sent: period mode without change_years, or the period and its change base when the years between could not be read within the call's size and time limits."

changedOutput schema / properties / applied_filters / properties / time_from / description

Previous value: -"First year sent (latest mode); no end year is sent."New value: +"First year sent: latest mode's window start (no end year is sent), or period mode's change base year."

addedOutput schema / properties / applied_filters / properties / time_to

Added value: +{
+  "description": "Last year sent: the period's year, in period mode with change_years.",
+  "type": "number"
+}

changedOutput schema / properties / comparability / description

Previous value: -"What makes the values more or less comparable, over every area."New value: +"What makes the current values more or less comparable, over every area; each change's baseline is compared by its own source_changed, basis_changed, and break_in_series."

changedOutput schema / properties / notice / description

Previous value: -"Mixed periods, mixed bases, missing areas, a unit or area list the structure service could not supply, where the full comparison is staged, or why the inline rows stop early."New value: +"Mixed periods, mixed bases, changes that are not like-for-like, missing areas, a unit or area list the structure service could not supply, where the full comparison is staged, or why the inline rows stop early."

changedOutput schema / properties / rows / items / properties / change / description

Previous value: -"Change over change_years; absent when the earlier value is missing."New value: +"Change over change_years with the earlier value's provenance; absent when the earlier value is missing. delta is like-for-like only when source_changed, basis_changed, and break_in_series are all false."

addedOutput schema / properties / rows / items / properties / change / properties / basis_changed

Added value: +{
+  "description": "True when the earlier value has another basis.",
+  "type": "boolean"
+}

addedOutput schema / properties / rows / items / properties / change / properties / break_in_series

Added value: +{
+  "description": "True when a break in series (status B or an I11 note) is marked on the value or on an observation of its source after from_period: the series' method changed within the span. A break marked on the earlier value alone came before the span and does not count. null when only the two periods were read (notice says so) and the value marks no break: a break between them is unknown.",
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

addedOutput schema / properties / rows / items / properties / change / properties / from_basis

Added value: +{
+  "description": "Basis of the earlier value: reported, modelled_estimate, or projection.",
+  "enum": [
+    "reported",
+    "modelled_estimate",
+    "projection"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / rows / items / properties / change / properties / from_notes

Added value: +{
+  "description": "Note codes of the earlier value (legend.notes decodes them).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / rows / items / properties / change / properties / from_obs_status

Added value: +{
+  "description": "Status flag of the earlier value (legend.obs_status decodes it).",
+  "type": "string"
+}

addedOutput schema / properties / rows / items / properties / change / properties / from_source

Added value: +{
+  "description": "Source code of the earlier value.",
+  "type": "string"
+}

addedOutput schema / properties / rows / items / properties / change / properties / from_source_label
```
Added value: +{
+  "description": "Source label of the earlier value.",
+  "type": "string"
+}
```

addedOutput schema / properties / rows / items / properties / change / properties / source_changed

Added value: +{
+  "description": "True when the earlier value comes from another source.",
+  "type": "boolean"
+}

changedOutput schema / properties / rows / items / properties / change / required

Previous value: -[
-  "from_period",
-  "from_value",
-  "delta"
-]New value: +[
+  "from_period",
+  "from_value",
+  "delta",
+  "from_source",
+  "from_basis",
+  "from_notes",
+  "source_changed",
+  "basis_changed",
+  "break_in_series"
+]

First observedOct 4, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only declare readOnly/openWorld/idempotent, but the description adds real behavioral context: refusal conditions (sex on a dataset without a breakdown, classif1 where the breakdown lacks a total), how areas without a value are reported, and that mixed periods and mixed bases are flagged rather than hidden. It stops short of covering auth, rate limits, or pagination behavior.

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 purpose is front-loaded and nearly every clause carries information (modes, change semantics, missing-area handling, selection methods). However, the first sentence runs to roughly seventy words as a single breath, making it dense to parse; splitting the response-behavior detail into its own sentence would improve structure.

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 an 11-parameter tool with one required field, an output schema, and safety annotations, the description covers the mode selection, area-selection paths, refusal cases, and edge-case reporting. Nothing an agent needs to call it correctly is missing, and return-value detail is already handled by the output schema.

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

Parameters4/5

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

Schema description coverage is already 100%, so the schema carries most parameter meaning (defaults, patterns, enums). The description nonetheless adds a governing constraint not present in the schema — that X-coded aggregates require a dataset with aggregates — plus the totals-defaulting rule, which is genuine added semantics beyond the field docs.

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?

The description opens with a precise verb+resource+scope: 'Compare reference areas on one ILOSTAT dataset and one slice.' It specifies the outputs (per-area value at a common or latest period, optional change over N years, and a rank), which makes it unmistakably distinct from single-series siblings like ilostat_query_indicator without needing to name them.

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

Usage Guidelines4/5

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

It clearly explains the two operating modes (a common period vs. each area's latest non-projected period) and the three ways to select areas (code list, group, or both), and it routes the agent to ilostat_describe_indicator and ilostat_list_reference for code discovery. It never states when not to use this tool or how it compares to ilostat_query_indicator, so it stops short of full alternative routing.

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

All ilostat-mcp-server 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.