What can you do with this server?

This is a read-only, provenance-first MCP server that gives assistants live, citable access to the ILO's ILOSTAT labour statistics (~1,200 SDMX dataflows) over hosted Streamable HTTP or local stdio. * ilo_search_indicators — keyword search the ILOSTAT catalogue (employment, unemployment, wages, hours, informality, SDG 8), resolving everyday/US wording (labor→labour, wages→earnings, gender→sex) and returning ranked dataflow ids. * ilo_get_indicator_metadata — dimensions in key order, codelists, time dimension, ILO default selection and data vintage for one dataflow. * ilo_list_dimension_values — valid codes and labels of one dimension (e.g. REF_AREA countries like BRA, SEX categories), with search and pagination. * ilo_get_data — the actual statistical observations, filtered by dimension codes and period; REF_AREA is required (up to 30 areas), raw values with unit/multiplier attributes, one live REST call per query, no transformation. * search + fetch — the ChatGPT Deep Research contract: rank a query against the catalogue and return one dataflow as readable Markdown with a citable public data explorer URL. * Provenance on every answer — source URL, data vintage, real retrieval timestamp, license (CC BY 4.0), ILO citation, and a retrieval diagnostic of upstream requests/retries, in structuredContent, _meta and a text footer (concise/detailed mode). * Resources and prompts — ilostat://guide, ilostat://reference/key-dataflows, ilostat://reference/provenance, plus prompts for a country labour profile, multi-country comparison and indicator trend. * Zero-setup or self-hosted use — point any MCP client at https://ilo.sidneybissoli.com/mcp (no account, key or install), or run npx ilo-mcp-server locally over stdio against the official API.

How do I use ILO Statistics (ILOSTAT) MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ILO Statistics (ILOSTAT) MCP Server get unemployment rate data for Brazil" 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.

de en es ja ko ru zh

ILO Statistics (ILOSTAT) MCP Server

by SidneyBissoli

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

ILO Labour Statistics (ILOSTAT) — MCP Server

MCP Version Tools Resources Prompts npm MCP Registry ilo-mcp-server MCP server License: MIT Status

🇧🇷 Leia em Português

A public, hosted, provenance-first MCP server for the International Labour Organization (ILO) statistics — the ILOSTAT database — no installation, no account, no API key. Point your MCP client at the hosted endpoint and ask about unemployment, employment, wages, working time and other labour indicators by country, year, sex and age. It runs on Cloudflare Workers over Streamable HTTP and talks to the official ILOSTAT SDMX REST API.

Independent project. This is an unofficial, community-built client of the ILO's public ILOSTAT API — not affiliated with or endorsed by the International Labour Organization. Data remain © ILO under CC BY 4.0; see Data license and attribution.

Every response carries a provenance block (source URL, data vintage, real retrieval timestamp, license, ILO citation) — exact figures with an audit trail, not numbers guessed from training data.

🇧🇷 Em português. Servidor MCP remoto e hospedado (nada para instalar, sem conta e sem chave) para as estatísticas de mercado de trabalho da OIT — desemprego, emprego, salários, jornada e informalidade por país, ano, sexo e idade, direto no Claude, no ChatGPT ou em qualquer cliente MCP, com proveniência e citação da fonte em cada resposta: README em português.

Questions it answers

In plain language, inside the MCP client — the assistant picks the tool and the filters:

"What has happened to unemployment in Brazil since 2015?" (ilo_get_data)
"Compare youth unemployment in Brazil, Mexico and South Africa." (ilo_compare_countries)
"How large is the gender pay gap, and where does the ILO publish it?" (ilo_search_indicators → ilo_get_data)
"What share of employment in India is informal?" (ilo_search_indicators → ilo_get_data)
"Which ILOSTAT dataflow has average monthly earnings by sex and economic activity?" (ilo_search_indicators)
"Which country, age and sex codes can I filter this indicator by?" (ilo_list_dimension_values)
"Give me a labour-market profile of Viet Nam." (ilo_country_labour_profile)

Ask in your words, not the ILO's. ILOSTAT is worded in British statistical English, and the catalogue is matched on the dataflow name — so the everyday or US word used to return nothing at all. Measured over the 1,212 dataflows of the official catalogue (2026-09-13), and fixed since 0.6.0: the search translates the term and tells you it did.

you ask	hits before	ILOSTAT writes	hits
`labor`, `labor force`	0	labour, labour force	176, 122
`wages`, `salary`	0	earnings	107
`informality`	0	informal	133
`gender`	2	sex	1,131
`productivity`	0	output per worker	4
`jobless`	0	unemployment	108

Related MCP server: world-bank-economic-mcp

Comparison with the alternatives

Anyone who already works with ILOSTAT has good tools, and this server replaces none of them — it sits somewhere else in the chain: it answers the question at the point where the question is asked, inside the assistant, with source, vintage and licence attached to the answer. Detail, side-by-side examples and the measured numbers in docs/alternatives.md.

Tool	What it is	When to prefer it
ilo-mcp-server (this)	Remote MCP server, hosted, nothing to install: 6 tools over the ~1,200 ILOSTAT dataflows, with a provenance block per answer	The question is asked in an assistant (Claude, ChatGPT, Cursor, Claude Code) and the answer has to be auditable
Rilostat 2.5.0 (R, CRAN)	The ILO's own R package, written by ILO staff: bulk download, metadata, filtering and reshaping	You are in R and want the dataset in a data frame — a whole table, repeatedly, for analysis
sdmx1 2.27.0 / pandaSDMX 1.10.0 (Python)	Generic SDMX clients; ILO is one of ~36 sources they know	Your pipeline is Python and you want SDMX objects, or the same code across several SDMX agencies
DBnomics (API, `dbnomics` for Python, rdbnomics 0.6.4 for R)	Aggregator that republishes 1,071 ILO datasets next to other providers, one API for all	You want ILO series alongside IMF, OECD, Eurostat in a single interface
ILOSTAT SDMX REST API	The source itself, which this server calls	You are building your own client and want full control
cyanheads/ilostat-mcp-server 0.1.2	Another ILOSTAT MCP server, hosted or local: tells survey values from ILO modelled estimates row by row, takes up to 300 areas per call and stages large results as dataframes you query with SQL	You need reported vs modelled on every row, or many countries and SQL over a large pull
Pipeworx mcp-ilostat 0.1.4	The ILOSTAT pack of the Pipeworx gateway: positional SDMX keys, answers without source, licence or value status	You already work through the Pipeworx gateway and want ILOSTAT next to its other sources

Do not use this server when you need a whole dataset rather than an answer (Rilostat's bulk download is the right tool), when the question is not labour statistics published by the ILO (education → UNESCO UIS, national accounts → IMF/World Bank), or when you need microdata: ILOSTAT publishes aggregates, and so does this server.

Sister servers, same design and same provenance block, for other official sources: IBGE (Brazilian statistics), BCB (Central Bank of Brazil), Senado (Brazilian Senate open data), SIH/SUS (Brazilian hospital admissions) and medical terminologies (ICD-11, ICD-10, LOINC, RxNorm, ATC, MeSH).

Use it (hosted — no setup)

Point any MCP client at the Streamable HTTP endpoint:

https://ilo.sidneybissoli.com/mcp

Claude Desktop / Claude Code and other clients with native remote support:

{
  "mcpServers": {
    "ilostat": {
      "url": "https://ilo.sidneybissoli.com/mcp"
    }
  }
}

For clients that launch MCP servers as a command, use the mcp-remote bridge:

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ilo.sidneybissoli.com/mcp"]
    }
  }
}

The ilo-mcp-server.sidneybissoli.workers.dev hostname is also served, as a secondary.

ChatGPT (Deep Research)

ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the ilo_* tools. Point the connector at the hosted endpoint, no key required:

https://ilo.sidneybissoli.com/mcp

search ranks the query against the full ILOSTAT dataflow catalogue (~1,200 SDMX dataflows — employment, unemployment, wages, working time, informality, SDG labour indicators) and returns { id, title, url } (ind:<DATAFLOW_ID>, e.g. ind:DF_UNE_2EAP_SEX_AGE_RT); fetch returns the dataflow as readable Markdown — name, data vintage, dimensions and codelists, the ILO's default selection and how to query it with ilo_get_data — with the public ILOSTAT data explorer page as url, which is what ChatGPT cites. Both carry the same provenance block as every other tool, in structuredContent and _meta (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the ilo_* tools remain the ones to use for data.

Run locally (stdio)

Prefer not to route queries through a third-party host? The same server also runs as a local stdio process that talks directly to the official ILOSTAT API — same 6 tools, resources and prompts, same limits, same provenance block, no Cloudflare in the loop.

No install needed — the package is on npm (ilo-mcp-server, Node ≥ 20):

{
  "mcpServers": {
    "ilostat": {
      "command": "npx",
      "args": ["-y", "ilo-mcp-server"]
    }
  }
}

Or from source:

git clone https://github.com/SidneyBissoli/ilo-mcp-server
cd ilo-mcp-server
npm install
npm run build
node dist/cli.js   # serves MCP over stdio (Ctrl+C to stop)

(then point the client at node /path/to/ilo-mcp-server/dist/cli.js).

Differences from the hosted server, all due to the absence of Cloudflare bindings: the SDMX cache lives in process memory (structures and codelists are reused within a session, not across sessions); the search catalogue is downloaded from the official endpoint on the first search (its real retrieved_at is reported in provenance); no usage metrics, rate limit or auth. Logs go to stderr — stdout carries only the JSON-RPC stream. The repository Dockerfile builds this runtime (used by the Glama registry).

Tools

Tool	What it does	Source
`ilo_search_indicators`	keyword search over ~1,210 dataflows (paginated by `offset`)	local catalogue (no upstream call)
`ilo_get_indicator_metadata`	dimensions, codelists, vintage and default selection of a dataflow	cached structure (miss → upstream)
`ilo_list_dimension_values`	valid codes of one dimension (paginated by `offset`)	cached codelist (miss → upstream)
`ilo_get_data`	observations filtered by dimension and period	1 live REST call per query
`search`	ChatGPT Deep Research contract: ranks a query against the full dataflow catalogue, returns `{ id, title, url }` (`ind:<DATAFLOW_ID>`)	in-memory index built from the local catalogue (24 h)
`fetch`	ChatGPT Deep Research contract: one dataflow as readable Markdown with the public data explorer page as `url`	cached structure (miss → upstream)

Typical flow: ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_values to discover valid filter codes → ilo_get_data with country and period filters.

Every response carries the portfolio provenance block (@sbissoli/mcp-provenance, modes concise/detailed via the provenance_mode parameter) on three channels: structuredContent, namespaced _meta (com.sidneybissoli.ilostat/*) and a text footer. Since 1.1.0 the block includes retrieval, the origin diagnostic of the call — how many requests went to ILOSTAT, how many attempts they took, which anomalies were overcome and whether the answer is unstable — measured by the portfolio's common fetch (@sbissoli/mcp-upstream); null when the answer did not touch ILOSTAT (catalogue or cached structure).

Resources and prompts

Three resources (static, text/markdown, no upstream call) that a client can attach to the context before calling tools — they save the 2–3 discovery calls most sessions spend on "which dataflow, which codes":

URI	Content
`ilostat://guide`	tool workflow, stable code conventions (`REF_AREA` ISO3 + `X`-aggregates, `SEX`, `AGE`, `FREQ`, dataflow id suffixes), limits, reporting rules
`ilostat://reference/key-dataflows`	verified dataflow ids by topic (unemployment, employment, participation, wages, hours, informality, NEET, SDG 8, productivity)
`ilostat://reference/provenance`	meaning of every provenance field and how to cite the ILO

Three prompts — ready-made workflows that chain the tools and end with the citation rules (arguments are strings; period arguments optional):

Prompt	Arguments	Result
`ilo_country_labour_profile`	`country`, `start_period`, `end_period`	labour-market profile of one country (unemployment, participation, employment ratio, informality, NEET, earnings, hours)
`ilo_compare_countries`	`countries`, `indicator`, `start_period`, `end_period`	comparison table across countries/aggregates in one data call, flagging modelled estimates vs reported data
`ilo_indicator_trend`	`indicator`, `country`, `start_period`, `end_period`	time series of one indicator with first/last, peak/trough and `OBS_STATUS` breaks

Every dataflow id quoted in the resources and prompts is checked against the catalogue seed by the test suite, so the documentation cannot point at an id the search would not find.

Behaviour and limits

REF_AREA is required in ilo_get_data, up to 30 areas per call. The ILO gateway times out (HTTP 504) on unrestricted queries, so the server never issues one; for broad panels, split the areas into batches and/or paginate by period (start_period/end_period). The error message explains how.
One live REST call per data query. Data is never cached — every ilo_get_data result is fetched from ILOSTAT at request time. Dataflow structures (TTL 24 h) and codelists (TTL 7 days, shared across dataflows) are cached.
data_vintage is the dataflow's last-update date as published by the ILO (LAST_UPDATE annotation, normalised to ISO).
retrieved_at is always the real instant of extraction from ILOSTAT, preserved alongside any cached value — never the build or response time. Cached responses say so (served_from_cache: true).
The indicator catalogue is a local snapshot (~1,210 dataflows), refreshed periodically; its own retrieved_at is reported in the provenance of ilo_search_indicators, so its age is always visible.
Every upstream call carries an identifiable User-Agent (service URL + contact), so ILO administrators can reach the operator.
Every upstream call has a timeout and a retry policy (since 1.1.0, measured against the live API): 65 s per attempt — above the ~61 s the ILO gateway itself takes to reject an unrestricted query with 504, so a legitimate wide query is never cut short by this server —, up to 3 attempts on 5xx, 429 (honouring Retry-After) and network errors, 70 s in total per call. Timeouts, HTTP 504 (query too broad) and 404 (no observations) are never retried. What happened is reported in the provenance retrieval field.
Language: English; timezone: UTC (ILO data is published in English).

Provenance fields

derived — true only for real transformation (aggregation, server-computed rate, interpolation, harmonisation), always with a derivation_note; unit conversion and rounding do not count. This server does not transform values, so derived is always false.
notices — reproduces the values of OBS_STATUS (the SDMX status/disclaimer channel, e.g. "Break in series"), verbatim and with counts. Technical per-observation attributes (DECIMALS etc.) stay on the rows (rows[].attributes).

Surface fingerprint, checkable from the registry

Every release publishes, in its MCP Registry entry, the sha256 of the surface this version serves (initialize, tools, resources, prompts) and which methods answer without a credential. A surface change without a version bump fails the build; the fingerprint in the registry lets a client check the same thing on its own side. Canonical form and procedure: SPEC.md of @sbissoli/mcp-surface. To check it yourself (Node 18+, no dependencies):

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/ilo-mcp-server

Data license and attribution

ILOSTAT data and metadata: CC BY 4.0 (since 2023-05-03; license verified 2026-08-04).
ILO attribution in every response (citation field): International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed <date>.
The ILO logo is not used. This service is not endorsed by the ILO.

Self-hosting / development

Everything below is only needed to run your own instance — it is not required to use the public server.

npm install
npm run typecheck && npm test   # offline suite (parsers, key, tools, output contract, resources/prompts, in-memory catalogue, vocabulary, eval fixtures)
npm run dev                     # http://localhost:8787/mcp (Worker)
npm run build && npm start      # stdio runtime (dist/cli.js)

# Catalogue seed (D1) — required before first use:
node scripts/seed-catalog.mjs   # downloads via curl and generates scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --local  --file=scripts/seed-catalog.sql
npx wrangler d1 execute ilostat-catalog --remote --file=scripts/seed-catalog.sql

npm run deploy
node scripts/smoke-mcp.mjs      # smoke test against production (initialize → 6 tools → search → fetch → errors)
npm run manifest:lhm            # regenerate tools/resources/prompts in lhm.plugin.json from the real server
# (the seed also writes tests/fixtures/catalog-ids.txt — the versioned id list the tests check resources/prompts against)

Bindings (see wrangler.jsonc): KV SDMX_CACHE, D1 CATALOG_DB, Durable Object USAGE (SQLite-backed usage counters), CF_VERSION_METADATA. Optional Bearer auth (wrangler secret put API_KEY); token-bucket rate limit per IP.

Notes for operators:

ILOSTAT returns JSON only when negotiated via the Accept header (application/vnd.sdmx.{structure,data}+json); ?format= is ignored and returns XML.
The ILO gateway answers HTTP 500 (languageTag1) to the Accept-Language: * header that Node's fetch (undici) sends by default; every upstream call therefore sets Accept-Language: en explicitly (Cloudflare's runtime sends no such header, so the Worker was never affected). It also expects an identifiable User-Agent.
Catalogue refresh is manual (no cron): quarterly, or immediately if a dataflow that exists upstream does not show up in search. Procedure: the three seed commands above. Data queries are always live, so only the search catalogue can age — and its age is exposed in provenance.

Evals

@sbissoli/mcp-evals: 24 fixtures in evals/fixtures/queries.ts, validated offline in npm test. The run with a real model (npm run eval) uses the Anthropic API and needs ANTHROPIC_API_KEY (without it, it exits with instructions). Run of 2026-08-07: top-1 100% (24/24) — evals/results/.

End-to-end: 10 complex questions with a single verifiable answer in evals/e2e/evaluation.xml, answers validated manually against production (evals/e2e/validacao-respostas.md). Run of 2026-08-07 (Sonnet): 9/10 exact string; 10/10 substantive — evals/results/2026-08-07-e2e.md.

Endpoints

Route	Purpose
`/`	landing page (service identity + contact — public)
`/health`	liveness
`/status`	version, tool/resource/prompt counts and names, provenance contract version, current deploy (feeds the README badges)
`/metrics`	aggregated usage (MCP endpoint only; no IPs, no query content)
`/.well-known/mcp/server-card.json`	MCP server card for directory scanners (`serverInfo`, tools, resources, prompts — derived from the running server)
`/mcp`	MCP Streamable HTTP

Security

Snyk Agent Scan (2026-08-07): passed — report in security/.

License

Code: MIT. Data: ILOSTAT, CC BY 4.0 (see "Data license and attribution" above).

Privacy

Contact

Sidney da Silva Pereira Bissoli — sbissoli76@gmail.com. This service is not endorsed by the ILO.

Available Tools

6 tools

fetchDeep Research DocumentA

Read-onlyIdempotent

Inspect

Returns the full document for an id obtained from search, as { id, title, text, url, metadata }: text is the readable content (Markdown) and url the canonical public page to cite.

Companion of search in the OpenAI Deep Research contract, over the ILOSTAT labour statistics (≈1,200 SDMX dataflows: employment, unemployment, wages, working time, informality, SDG labour indicators) catalog. Only ids returned by search are valid; an unknown id returns an error. The ilo_* tools remain the tools for data queries.

Behavior: read-only and idempotent — a live GET against the public source when the document needs it.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Identifier of a document returned by `search`

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Unique identifier of the document on this server; what `fetch` takes
`url`	Yes	Canonical public URL of the document — ChatGPT's citation depends on it
`text`	Yes	Full readable content of the document (Markdown)
`title`	Yes	Human-readable title of the document
`metadata`	No	Additional key/value pairs about the document (kind, source, period…)
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`attribution`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, open-world and non-destructive, so safety is covered. The description earns credit by adding the error behavior on unknown ids, noting it is a live GET against the public source, and characterizing the corpus (≈1,200 SDMX dataflows) — genuine context beyond the structured fields.

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-loads the return contract, then the catalogue/contract context, then behavior — a sensible ordering. It is dense (parenthetical field list, domain aside) but each sentence carries information an agent needs; nothing is padding.

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?

With annotations covering safety and an output schema covering the return shape, the description supplies the remaining essentials: provenance of the id, the error case, cross-tool routing to `ilo_*`, and the live-fetch behavior. Nothing needed to call this correctly is missing.

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 coverage is 100%, so the single `id` parameter is documented in the schema itself (baseline 3). The description adds real meaning by tying the id to `search` output and stating the failure mode for ids outside that set, which the schema does not 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?

States a specific verb and resource ('Returns the full document for an id obtained from `search`') and enumerates the exact return fields. It also distinguishes itself from siblings by naming `search` as its companion and declaring that 'the `ilo_*` tools remain the tools for data queries'.

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?

Explicit conditions: only ids returned by `search` are valid, an unknown id returns an error, and data-query needs must go to the `ilo_*` tools instead. Both the when-to-use and the when-not-to-use are stated, naming the alternatives.

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

ilo_get_dataGet ILOSTAT dataA

Read-onlyIdempotent

Inspect

Statistical observations from one ILOSTAT dataflow, filtered by dimension codes (filters, e.g. {"REF_AREA": ["BRA","ARG"], "SEX": "SEX_T"}) and period (start_period/end_period, e.g. "2015"/"2024"). REF_AREA is required, maximum 30 areas per call — for broad panels, split areas into batches and/or paginate by period. Unfiltered dimensions return all their categories. Does not aggregate, convert or otherwise transform values (raw ILOSTAT data only): read each value with the unit and multiplier the ILO states in its row attributes (UNIT_MEASURE, UNIT_MULT — e.g. UNIT_MULT 3 = thousands). Read TIME_PERIOD with the FREQ column (annual, quarterly or monthly) and OBS_STATUS when present (break in series, estimated or provisional value). Values are the current release, dated by data_vintage (the dataflow LAST_UPDATE): the ILO revises published figures and re-estimates modelled series (_2 ids) at each release, past years included. Does not search indicators (use ilo_search_indicators).

ParametersJSON Schema

Name	Required	Description
`filters`	Yes	Dimension id → code or list of codes (from ilo_list_dimension_values). REF_AREA is required (up to 30 area codes); any other dimension is optional and, left out, returns all of its categories.
`dataflow`	Yes	Dataflow id from ilo_search_indicators (e.g. "DF_UNE_DEAP_SEX_AGE_RT")
`end_period`	No	Last period, e.g. "2024"
`start_period`	No	First period, e.g. "2015"
`provenance_mode`	No	Provenance verbosity: 'concise' (default — source, url, vintage, retrieval date, citation, license) or 'detailed' (full canonical block with dataset, dimension key and notices)
`last_n_observations`	No	Alternative to periods: only the latest N observations per series

Output Schema

ParametersJSON Schema

Name	Required	Description
`rows`	Yes
`columns`	Yes
`dataflow`	Yes
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`rows_count`	Yes
`attribution`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial behavior beyond them: values are the current release dated by data_vintage, the ILO revises past years and re-estimates modelled (_2) series, no aggregation or transformation occurs, and how to read UNIT_MULT/OBS_STATUS/FREQ. This is rich, non-obvious operational 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?

The core purpose and the required-REF_AREA constraint are front-loaded, and most sentences carry distinct information (units, revisions, alternatives). It is a dense single paragraph, so slightly more structure or trimming would improve scannability, but there is little outright waste.

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?

With an output schema present, the description needn't restate return shapes, and it correctly focuses on interpretation (units, multiplier, series revisions) plus the required-parameter and batching constraints. Nothing an agent needs to call this correctly appears to be missing.

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 100%, so the baseline is 3. The description still adds value with a concrete filters example, the REF_AREA-cap and batching rule, and the 'unfiltered dimensions return all categories' semantics, though it largely reinforces what the schema already states.

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 — statistical observations from one ILOSTAT dataflow — and explicitly scopes what it is not ('Does not search indicators (use ilo_search_indicators)'). This lets an agent distinguish it from ilo_search_indicators and ilo_get_indicator_metadata without opening any schema.

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?

Gives concrete when-to-use conditions and alternatives: use ilo_search_indicators for discovery, ilo_list_dimension_values for dimension codes, and split areas into batches when exceeding the 30-area cap. It names the batching/pagination strategy for broad panels, which is exactly the operational guidance an agent needs.

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

ilo_get_indicator_metadataGet ILOSTAT indicator metadataA

Read-onlyIdempotent

Inspect

Structure of one ILOSTAT dataflow: dimensions (in SDMX key order), their codelists, the time dimension, the source's default selection and the data vintage (last update at the ILO). Use before ilo_get_data to know which filters exist. Does not return statistical values and does not list the codes themselves (use ilo_list_dimension_values).

ParametersJSON Schema

Name	Required	Description	Default
`dataflow`	Yes	Dataflow id from ilo_search_indicators (e.g. "DF_UNE_DEAP_SEX_AGE_RT")
`provenance_mode`	No	Provenance verbosity: 'concise' (default — source, url, vintage, retrieval date, citation, license) or 'detailed' (full canonical block with dataset, dimension key and notices)

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`name`	Yes
`version`	Yes
`dimensions`	Yes
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`attribution`	Yes
`data_vintage`	Yes
`time_dimension`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real behavioral boundaries by stating it 'does not return statistical values' and 'does not list the codes themselves'. It does not mention auth requirements, rate limits, or payload size, but the exclusion statements are meaningful additions beyond structured fields.

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

Conciseness5/5

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

Three sentences, front-loaded with the resource and its returned structure, then sequencing guidance, then exclusions. No filler or redundancy; every clause earns its place.

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 described in prose; the description instead supplies what the schema cannot — when to call it, what it excludes, and how it relates to sibling tools. Nothing an agent needs to invoke this correctly is missing.

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%, including the dataflow id format example and the provenance_mode enum semantics, so the schema does the heavy lifting and a baseline 3 applies. The description adds only indirect context about SDMX key ordering and default selection rather than per-parameter meaning.

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 names a specific resource (one ILOSTAT dataflow) and enumerates exactly what is returned: dimensions in SDMX key order, codelists, time dimension, default selection, and data vintage. It explicitly bounds scope against siblings, telling the agent it is not a value-returning or code-listing tool. An agent can distinguish this from ilo_get_data and ilo_list_dimension_values without opening any schema.

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?

Gives an explicit sequencing instruction — 'Use before ilo_get_data to know which filters exist' — and names the alternative tool for the adjacent task ('use ilo_list_dimension_values'). Both the when and the not-when are stated, leaving nothing to inference.

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

ilo_list_dimension_valuesList valid codes of a dimensionA

Read-onlyIdempotent

Inspect

Valid codes (id + label) of one dimension of an ILOSTAT dataflow — e.g. the country/area codes of REF_AREA (ISO 3166-1 alpha-3 such as BRA, plus X-codes for aggregates such as X01 World) or the categories of SEX (SEX_T/SEX_M/SEX_F) and AGE. Use search to resolve a name to a code (e.g. search "Brazil") instead of paging through hundreds of codes; codelists are shared across dataflows, so a code found here is valid wherever the same codelist is used. Use to build correct ilo_get_data filters. Does not return statistical values, does not say which codes actually have data for a given dataflow, and is not applicable to the time dimension (filter it via start_period/end_period in ilo_get_data).

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum codes returned (default 200)
`offset`	No	Codes to skip, for pagination (default 0)
`search`	No	Case-insensitive filter on code id or label
`dataflow`	Yes	Dataflow id the dimension belongs to
`dimension`	Yes	Dimension id from ilo_get_indicator_metadata (e.g. "REF_AREA", "SEX")
`provenance_mode`	No	Provenance verbosity: 'concise' (default — source, url, vintage, retrieval date, citation, license) or 'detailed' (full canonical block with dataset, dimension key and notices)

Output Schema

ParametersJSON Schema

Name	Required	Description
`offset`	Yes
`values`	Yes
`showing`	Yes
`codelist`	Yes
`dataflow`	Yes
`has_more`	Yes
`dimension`	Yes
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`attribution`	Yes
`next_offset`	No
`total_codes`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/openWorld/destructive, so the bar is lower, yet the description adds meaningful negative-scope context: no statistical values returned, no signal of which codes actually have data, time dimension excluded. It does not mention pagination limits or default page size behavior beyond what the schema states.

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 definition followed by usage, alternative, and exclusions in a logical order. Dense and slightly run-on with parenthetical asides, but nearly every clause carries actionable information.

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 6-param, output-schema-backed lookup tool, the description covers purpose, alternatives, negative scope, and the relationship to downstream filtering. An agent has everything needed to call it correctly without the return shape being restated.

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 coverage is 100% so baseline is 3, but the description adds real meaning beyond the schema: what `search` does semantically (resolve a name like 'Brazil' to a code), that codelists are shared across dataflows, and example dimension ids. It says nothing extra about provenance_mode or limit/offset.

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 - valid codes (id + label) of one dimension of an ILOSTAT dataflow - and grounds it with concrete examples (REF_AREA ISO 3166-1 alpha-3, SEX_T/SEX_M/SEX_F). Easily distinguished from siblings like ilo_get_data or ilo_get_indicator_metadata.

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 to `search` for name-to-code resolution rather than paging, states the downstream purpose (build correct ilo_get_data filters), and gives exclusions: not statistical values, not a data-availability check, not applicable to the time dimension (use start_period/end_period instead).

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

ilo_search_indicatorsSearch ILOSTAT indicatorsA

Read-onlyIdempotent

Inspect

Search the ILOSTAT catalogue of ~1,200 indicator dataflows by keywords in the name or id (e.g. "unemployment rate sex age"). All terms must match (AND, case-insensitive), so start with 2–3 English words and drop terms if you get 0 results. Everyday and US wording is resolved to the ILO's own (labor→labour, wages/salary→earnings, informality→informal, gender→sex, productivity→output per worker); when that happens the response says so in vocabulary_notes. Results are ranked by ILO relevance weight, not by match count. Reading the id tells you the shape: suffix _RT = rate/ratio, NB = number (usually thousands); dataflows whose second token starts with 2 (e.g. DF_UNE_2EAP…) are ILO modelled estimates with full country/year coverage, the others are reported national data. Returns dataflow ids to use with ilo_get_data / ilo_get_indicator_metadata. Searches the local catalogue only — it does not return statistical values (use ilo_get_data), does not search dimension codes such as countries (use ilo_list_dimension_values) and does not cover non-ILO sources.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum results (default 20)
`query`	Yes	Keywords, matched against dataflow name and id (AND between terms)
`offset`	No	Results to skip, for pagination (default 0)
`provenance_mode`	No	Provenance verbosity: 'concise' (default — source, url, vintage, retrieval date, citation, license) or 'detailed' (full canonical block with dataset, dimension key and notices)

Output Schema

ParametersJSON Schema

Name	Required	Description
`hint`	No
`offset`	Yes
`showing`	Yes
`has_more`	Yes
`indicators`	Yes
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`attribution`	Yes
`next_offset`	No
`total_matches`	Yes
`vocabulary_notes`	No

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), and the description corroborates the closed-world hint with 'Searches the local catalogue only'. Beyond that it discloses non-obvious behavior: synonym resolution to ILO vocabulary with a vocabulary_notes signal in the response, relevance-weight ranking rather than match count, and the id-suffix encoding (_RT vs _NB, modelled estimates).

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?

Dense but front-loaded: retrieval purpose, query syntax, then result interpretation and routing, with zero filler sentences. It runs long for a search tool and the id-suffix decoding could be deferred to metadata, but every sentence carries actionable signal.

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?

Covers the query semantics, the synonym/ranking caveats an agent could otherwise misread, and the downstream tools to route to; an output schema exists so return values need not be described. Nothing required to invoke or interpret results is missing.

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 coverage is 100%, so limit/offset/provenance_mode are already documented and the baseline is 3. The description still adds real meaning for the query parameter beyond the schema, specifying AND-matching across name and id, case-insensitivity, term-dropping strategy, and synonym normalization behavior.

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 with scope: 'Search the ILOSTAT catalogue of ~1,200 indicator dataflows by keywords in the name or id'. It explicitly names what it is not (does not return statistical values, does not search dimension codes), so it is unambiguously separable from ilo_get_data and ilo_list_dimension_values.

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?

Gives both when-to-use and when-not: use this for finding dataflow ids, then use ilo_get_data for values and ilo_list_dimension_values for dimension codes, plus an explicit exclusion of non-ILO sources. It even includes operational advice on query construction (start with 2–3 English words, drop terms on zero results).

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

searchDeep Research SearchA

Read-onlyIdempotent

Inspect

Searches the ILOSTAT labour statistics (≈1,200 SDMX dataflows: employment, unemployment, wages, working time, informality, SDG labour indicators) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).

This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools search and fetch. Pass one of the returned ids to fetch to read the document. For direct questions and for data (values, series, rankings) prefer the ilo_* tools, which return the actual data with provenance — this is a catalog index, not a data query.

Query: natural language or keywords, Portuguese or English; accents and case are ignored.

Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search terms, natural language or keywords (accents and case are ignored)

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes	Matching documents, in relevance order
`provenance`	Yes	Portfolio provenance block. concise (default): source, source_url, data_vintage, retrieved_at, retrieval, citation, license; detailed: the full canonical block (dataset, dimension_key, notices, served_from_cache, ...). retrieval is the origin diagnostic of this call — requests made to ILOSTAT, attempts including retries, anomalies overcome (timeout, network, rate_limited, http_5xx, http_4xx, malformed_body) and unstable (true when anything had to be retried: treat the figures as obtained with difficulty); null when nothing was fetched from ILOSTAT (catalogue or cached answer). Optional keys (field_sources, notices, derived, derivation_note, revision) appear only when there is something to say
`attribution`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so 'read-only and idempotent' largely restates structured data. However, the description adds genuinely new behavior: the catalog is public-source and cached in memory, results are capped at 10 and relevance-ordered, and an empty list is the documented no-match signal.

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 return shape, then layered with routing guidance. The Deep Research contract paragraph is slightly long but earns its place by explaining the tool's raison d'être and the required pairing with `fetch`.

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 summarizes them. For a one-parameter search tool it covers scope, result semantics, failure semantics, routing alternatives, and the fetch handoff — nothing an agent needs is missing.

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?

With a single parameter at 100% schema coverage the baseline is 3, and the schema already states that accents and case are ignored. The description still adds value by clarifying that queries may be natural language or keywords and that both Portuguese and English are supported — language support is absent from the schema.

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 ('searches the ILOSTAT labour statistics catalog'), quantifies the result cap (up to 10 documents) and names the exact return shape { id, title, url } with relevance ordering. It also explicitly distinguishes itself from the ilo_* sibling tools as a catalog index rather than a data query.

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?

Gives explicit when-to-use (OpenAI Deep Research / Responses API contract requiring exactly `search` and `fetch`) and explicit when-not-to-use ('for direct questions and for data prefer the ilo_* tools'). It also chains usage by telling the agent to pass a returned id to `fetch`.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv1.6.3Oct 15, 2026

Changedfetch2 fields changed