ilostat-mcp-server

Query ILOSTAT observations

ilostat_query_indicator

Read-onlyIdempotent

Fetch observations for up to 3 ILOSTAT datasets, filtered by reference area or area group, sex, breakdown codes (classif1, classif2), source, and period. Rows keep their source, observation status, decoded notes, and a basis — reported, modelled_estimate, or projection — and the response echoes every filter applied, including the best-source default. Codes are checked against ILOSTAT's dictionaries before the request is sent: ilostat_list_reference lists valid codes and ilostat_describe_indicator lists the codes a dataset actually uses. A result larger than the inline preview is staged in full as a df_ dataframe for SQL through ilostat_dataframe_describe and ilostat_dataframe_query when this deployment enables dataframes. A request with no filters at all is refused when the dataset exceeds the row ceiling, and a filtered request that still exceeds it is refused with guidance to narrow it.

Input Schema

TableJSON Schema

Name	Required	Description
`sex`	No	Sex codes SEX_T, SEX_M, SEX_F, SEX_O; T/M/F/O and total/both/male/female/other are accepted.
`time`	No	One exact period: YYYY (on a quarterly or monthly dataset, every period of that year), YYYYQn, or YYYYMmm; 2024-Q2, 2024 Q2, and 2025-03 are normalized. Not combinable with time_from, time_to, or latest_only.
`sources`	No	Source codes (e.g. BA:453); ilostat_list_reference topic sources with ref_area lists an area's sources. Without source_selection, setting sources switches it to all, since a secondary source matches nothing under best.
`time_to`	No	Last year (YYYY), not before time_from.
`classif1`	No	Codes of the first breakdown (e.g. AGE_YTHADULT_YGE15); case-insensitive. ilostat_describe_indicator lists the codes a dataset uses.
`classif2`	No	Codes of the second breakdown, for datasets that have one; case-insensitive. ilostat_describe_indicator lists them.
`ref_areas`	No	Reference areas (up to 300): ISO3 country codes (USA) or X-coded aggregates (X01 World); case-insensitive, ILO_GEO_ forms accepted. Aggregates need a dataset with has_aggregates true. Omit for every area.
`time_from`	No	First year (YYYY); upstream filters by year only.
`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, unioned with ref_areas. ilostat_list_reference topic area_groups lists the codes.
`dataset_ids`	Yes	One to three dataset IDs — an indicator code plus _A, _Q, or _M (UNE_DEAP_SEX_AGE_RT_A), as ilostat_search_indicators returns them. Case-insensitive; a DF_ prefix (the SDMX dataflow form) is stripped, a bare indicator code resolves when it has one frequency, and an element holding + or , joined IDs is split.
`latest_only`	No	Only the latest period per reference area and dataset (the latest quarter or month on sub-annual datasets); combines with time_from/time_to.
`source_selection`	No	best (default): the preferred source per area and period; all: secondary sources too, each row flagged best_source; secondary: secondary sources only. Defaults to all when sources is set.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	Inline preview budget, in serialized characters.
`rows`	No	Inline preview rows; the staged dataframe holds every row when the result is larger.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows returned inline.
`legend`	No	Labels for every code in rows.
`notice`	No	Filters that could not narrow a dataset, a unit the structure service could not supply, why nothing matched, where the full result is staged, or why reading stopped early.
`summary`	No	Summary over every row read, not just the preview.
`datasets`	No	The requested datasets, in request order.
`dataframe`	No	The staged dataframe holding the full result; present only when staged.
`row_count`	No	Rows the request returned — exact when the result is inline or staged; when reading stopped early (truncated), the rows read.
`truncated`	No	True when reading stopped at the inline preview and more rows exist.
`attribution`	No	Citation to keep with any use of the data.
`applied_filters`	No	Every parameter sent upstream, defaults included.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 4, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses row content (source, observation status, decoded notes, reported/modelled_estimate/projection basis), filter echo semantics, code pre-validation against ILOSTAT dictionaries, dataframe staging for oversized results, and two distinct refusal conditions (unfiltered over ceiling, filtered still over ceiling). That is unusually rich behavioral context.

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?

Front-loaded with the core action and scope, and each subsequent sentence carries distinct information (row shape, validation, staging, refusals). It is dense as a single paragraph, but virtually no sentence is filler.

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?

An output schema exists, so return values need not be spelled out, yet the description still explains the meaningful row attributes and filter echo. Combined with refusal behavior and dataframe hand-off, an agent has everything needed to call this correctly in a complex, 12-parameter, multi-dataset query tool.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema itself documents all 12 parameters in detail, including the sources/source_selection interaction and normalization rules. The description's summary of filter dimensions and the 'best-source default' echo adds reinforcement but no new parameter syntax beyond what the schema provides, so baseline 3 applies.

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?

States a specific verb and resource ('Fetch observations for up to 3 ILOSTAT datasets') with explicit scope limits and the filter dimensions it accepts. It also distinguishes itself from siblings by naming ilostat_list_reference and ilostat_describe_indicator as code-resolution tools and the dataframe tools as the path for large results.

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?

Clearly routes the agent: consult ilostat_list_reference / ilostat_describe_indicator for valid codes before calling, and use ilostat_dataframe_describe / ilostat_dataframe_query when a result is staged. It does not explicitly contrast this tool with ilostat_compare_geographies or ilostat_get_country_profile, so it stops short of full when-not guidance.

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.