ILO Labour Statistics (ILOSTAT): unemployment, wages, informality

Name: ILO Labour Statistics (ILOSTAT): unemployment, wages, informality
Author: SidneyBissoli

Server Details

Labour market data from the ILO (ILOSTAT) by country, year, sex and age, with provenance.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 100.0% over 56 days
Last Tested: 2026-10-31 09:33
Transport: Streamable HTTP · MCP 2025-11-25
URL
Repository: SidneyBissoli/ilo-mcp-server
GitHub Stars: 2
Server Listing: ILO Statistics (ILOSTAT) MCP Server

TDQS

A4.4/5.0

Scored 2026-10-28 00:45 across 6 tools

Disambiguation4/5

The four ilo_* tools have clearly distinct roles: indicator discovery, dataflow structure, dimension-code lookup, and data retrieval. The generic search/fetch pair overlaps somewhat with ilo_search_indicators because both search the ILOSTAT catalogue, but the descriptions explicitly route document retrieval to search/fetch and statistical queries to ilo_*.

Naming Consistency3/5

The four ilo_* tools follow a consistent snake_case verb_noun pattern. The unprefixed search and fetch tools break that convention, though they are required by the OpenAI Deep Research contract, leaving a readable but mixed naming scheme.

Tool Count5/5

Six tools is well scoped for a read-only statistical data server. Each tool supports a distinct step in the workflow: discovering indicators, inspecting metadata or dimension codes, retrieving observations, and fetching catalogue documents.

Completeness4/5

The core read-only workflow is covered: search indicators, inspect dimensions and codes, then retrieve data with provenance. Minor gaps remain, such as no browse/list-all indicator operation, no batch query across multiple dataflows, and an unclear suggestion to use document search to resolve country names to dimension codes.

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.

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

Output 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	Source URLs the figures came from (the provenance source_url of each block), for linking the citation

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 behavior, so the bar is lower; the description nonetheless adds real context by disclosing the live GET against the public source and the error on unknown ids. It doesn't discuss rate limits or caching, but the value-add beyond annotations is solid.

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 return contract, then the usage constraint, then behavior—logical ordering with no filler sentences. It is slightly dense with parentheticals and catalog detail, but every clause carries information an agent needs.

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?

Has an output schema, so return values needn't be explained, yet the description still summarizes the shape and field meanings. Combined with the id-validity rule and the sibling routing, nothing an agent needs 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 baseline is 3; the description adds genuine meaning by specifying that the id must originate from `search` and that `url` is the canonical citable page. This goes beyond the terse schema description ('Identifier of a document returned by `search`').

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 the specific verb and resource ('Returns the full document for an id') and immediately enumerates the return shape (id, title, text, url, metadata), clarifying which field is readable content and which is the citable URL. It also distinguishes itself from siblings by naming `search` as the id source and pointing data queries to the `ilo_*` tools.

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 constrains usage: 'Only ids returned by `search` are valid; an unknown id returns an error,' and directs data queries to `ilo_*` tools instead. Both when-to-use and when-not-to-use are covered, plus the failure mode.

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).

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

Name	Required	Description
`rows`	Yes	Raw ILOSTAT observations: one code per dimension, value (untransformed; read with UNIT_MULT) and, when present, attributes such as OBS_STATUS, UNIT_MEASURE and UNIT_MULT
`columns`	Yes	Dimension ids of each row, in SDMX order, followed by value
`dataflow`	Yes	The dataflow the observations come from
`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	Number of observations returned
`attribution`	Yes	Source URLs the figures came from (the provenance source_url of each block), for linking the citation

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes well beyond them, warning that values are raw and untransformed, how to read UNIT_MEASURE/UNIT_MULT/FREQ/OBS_STATUS, and that figures are revised across vintages including back years. That revision caveat is exactly the non-obvious behavior an agent needs, though return shape/pagination mechanics are only implied.

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 purpose and scope first, then constraints, then interpretation caveats — a sound ordering. It is dense and every sentence carries information, but the parenthetical explanations (unit multiplier example, _2 modelled series) push it toward the long side for a tool with a fully documented schema.

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-parameter, nested-object, open-world data tool with an output schema, the description covers what the schema cannot: raw-data semantics, unit/multiplier interpretation, revision behavior, and the batching constraint. Nothing an agent needs to call it correctly 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 the baseline is 3, but the description adds real semantics the schema does not: a concrete filters example ({"REF_AREA": ["BRA","ARG"], "SEX": "SEX_T"}), period examples ("2015"/"2024"), and the 30-area cap with its batching workaround. The start/end vs. last_n_observations tradeoff is left to the schema rather than clarified in prose.

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: 'Statistical observations from one ILOSTAT dataflow,' and immediately defines the scope (filtered by dimension codes and period). It explicitly names the sibling it is not ('Does not search indicators (use ilo_search_indicators)'), so an agent can distinguish it without opening the 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?

States the hard requirement (REF_AREA required, max 30 areas per call), the workaround when that limit is exceeded (split into batches, paginate by period), and the default behavior for omitted dimensions ('Unfiltered dimensions return all their categories'). It also routes the agent away from this tool for indicator search, naming the alternative explicitly.

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).

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

Name	Required	Description
`id`	Yes	Dataflow id
`name`	Yes	Dataflow name; null when the ILO gives none
`version`	Yes	Dataflow version at the ILO
`dimensions`	Yes	Dimensions in SDMX key order, each with its codelist id; filter ilo_get_data by these ids
`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	Source URLs the figures came from (the provenance source_url of each block), for linking the citation
`data_vintage`	Yes	Last update of the dataflow at the ILO (LAST_UPDATE, yyyy-MM-dd); null when absent
`time_dimension`	Yes	Id of the time dimension (filtered via start_period/end_period); null when absent

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds valuable substance by enumerating the returned structure and the data vintage concept. It does not discuss error behavior for an unknown dataflow id or any cost/latency characteristics, which is the remaining gap.

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 dense sentences: what it returns first, then when to call it, then the two negative boundaries. No filler, and the most decision-relevant information is front-loaded.

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 need not describe return values, and annotations plus schema cover the rest. Purpose, sequencing relative to ilo_get_data, and the two exclusion boundaries are all stated, leaving nothing essential unaddressed.

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 coverage is 100%, so both `dataflow` (with example id) and the `provenance_mode` enum are fully documented in the schema. The description adds nothing about either parameter — notably `provenance_mode` (concise vs detailed) is unmentioned — so this sits at the baseline.

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+resource: returns the structure of one ILOSTAT dataflow, enumerating exactly what is included (dimensions in SDMX key order, codelists, time dimension, default selection, data vintage). It explicitly distinguishes itself from ilo_get_data (no statistical values) and ilo_list_dimension_values (no codes).

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?

"Use before ilo_get_data to know which filters exist" gives the triggering condition and the downstream tool it precedes. The exclusions ("does not return statistical values", "does not list the codes themselves") route the agent to the correct sibling for the other two needs.

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).

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

Name	Required	Description
`offset`	Yes	Codes skipped before this page
`values`	Yes	Valid codes: id is the value for ilo_get_data filters, name is the ILO label
`showing`	Yes	Codes returned in this page
`codelist`	Yes	Id of the codelist that enumerates the dimension (shared across dataflows)
`dataflow`	Yes	Dataflow id the dimension belongs to
`has_more`	Yes	True when more codes remain after this page
`dimension`	Yes	Dimension id
`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	Source URLs the figures came from (the provenance source_url of each block), for linking the citation
`next_offset`	No	Offset for the next page; present only when has_more is true
`total_codes`	Yes	Codes matching the search filter (or all codes), across every page

TDQS

A4.6/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), and the description adds real behavioral context: it returns only id+label, does NOT return statistical values, does NOT indicate which codes have data, is not applicable to time, and codelists are shared across dataflows. It does not mention result ordering or the default paging cap implications, so it stops just short of the top mark.

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 purpose and examples, then alternatives, then exclusions. Dense and mostly waste-free, though the single long paragraph packs several distinct ideas that would read better as separate sentences.

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?

Annotations, a fully described 6-parameter schema, and an output schema are all present, and the description fills the remaining conceptual gaps (shared codelists, absence of statistical values, time-dimension exclusion) that an agent would otherwise guess wrong about.

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 baseline is 3; the description goes beyond it by explaining the search parameter's real use ('search "Brazil"') and by mapping the dimension parameter to the time-dimension exclusion with start_period/end_period. It adds no guidance on limit/offset tuning or provenance_mode, leaving a small gap.

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 resource (valid codes, id+label, of one dimension of a dataflow) with concrete examples (REF_AREA ISO alpha-3, SEX_T/SEX_M/SEX_F). An agent can distinguish this codelist-listing tool from ilo_get_data and ilo_get_indicator_metadata without opening either 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?

Explicit when-to-use (build correct ilo_get_data filters), an alternative with its condition ('use search to resolve a name to a code ... instead of paging through hundreds of codes'), and explicit when-not (time dimension, which is filtered via start_period/end_period).

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.

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

Name	Required	Description
`hint`	No	What to do next: how to narrow or page, or why nothing matched
`offset`	Yes	Results skipped before this page
`showing`	Yes	Dataflows returned in this page
`has_more`	Yes	True when more matches remain after this page
`indicators`	Yes	Matching dataflows, highest ILO relevance weight first; use id with ilo_get_data
`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	Source URLs the figures came from (the provenance source_url of each block), for linking the citation
`next_offset`	No	Offset for the next page; present only when has_more is true
`total_matches`	Yes	Dataflows matching all terms, across every page
`vocabulary_notes`	No	Translations applied from everyday or US wording to ILO terms (e.g. labor → labour)

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare a safe, idempotent, closed-world read, yet the description adds non-obvious behavior: terminology normalization (labor→labour, wages→earnings) surfaced via vocabulary_notes, ranking by ILO relevance weight rather than match count, and how the id suffix (_RT vs _NB, second-token '2' = modelled estimates) signals coverage. This is real predictive value an agent could not infer from annotations.

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?

Purpose and the top-level constraint are front-loaded, and each clause carries information (ranking, id decoding, alternatives). The single dense block with heavy parentheticals and semicolons makes it slightly harder to scan than a segmented version would be.

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 4-parameter search tool with an output schema, everything an agent needs is present: what is searched, how matching works, what the ids mean, what the results feed into, and what the tool does not do. Return-format detail is correctly left to 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 coverage is 100%, so baseline is 3, but the description deepens the most important parameter by explaining that all terms are ANDed case-insensitively, that query terms are vocabulary-resolved, and how to iterate when results are empty. limit, offset and provenance_mode are left to the schema, which documents them adequately.

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 (search), resource (ILOSTAT catalogue of ~1,200 indicator dataflows) and match surface (name or id), with example keywords. It also names the boundaries: not statistical values (ilo_get_data) and not dimension codes (ilo_list_dimension_values), so an agent can separate it from siblings without opening a 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 explicit operational guidance: start with 2–3 English words, drop terms on 0 results, and use ilo_get_data / ilo_list_dimension_values for the adjacent jobs. The exclusions ('does not return statistical values', 'does not cover non-ILO sources') are stated outright rather than implied.

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.

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

Output 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	Source URLs the figures came from (the provenance source_url of each block), for linking the citation

TDQS

A4.6/5.0

Behavior4/5

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

Adds real behavior beyond the annotations: a 10-result cap, relevance ordering, the meaning of an empty list, and that the catalog is cached in memory from a public source. The 'read-only and idempotent' sentence largely restates readOnlyHint/idempotentHint, which is the only dead weight here; nothing contradicts the declared hints.

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 behavior and well-partitioned into purpose, contract, routing, query, and behavior blocks — easy to scan. Slightly padded by the annotations-restating final clause ('read-only and idempotent'), which earns less than the surrounding sentences.

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 only one parameter, an output schema, and full annotation coverage, the remaining unknowns are the result cap, ordering, empty-result semantics, and catalog staleness — all of which the description supplies. Nothing an agent needs to call this correctly and interpret the response 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 baseline is 3, but the description adds information the schema lacks: the query accepts natural language OR keywords and works in Portuguese or English. Minor missed opportunity on any guidance about query breadth (e.g. how specific to be), but the value add is clear.

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'), names the covered domains, and specifies the return shape ({ id, title, url }, up to 10, relevance-ordered). It also explicitly contrasts itself with `fetch` (this produces ids, that reads documents) and the `ilo_*` data tools, so the agent can distinguish it from every sibling.

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 and when-not-to-use rules: use this for the Deep Research `search`/`fetch` contract, pass returned ids to `fetch`, and prefer `ilo_*` tools for actual values/series/rankings. The exclusion ('this is a catalog index, not a data query') is exactly the disambiguation the sibling set requires.

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 updatesOct 28, 2026

Changedfetch1 field changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

Changedilo_get_data8 fields changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

addedOutput schema / properties / columns / description

Added value: +"Dimension ids of each row, in SDMX order, followed by value"

addedOutput schema / properties / dataflow / description

Added value: +"The dataflow the observations come from"

addedOutput schema / properties / dataflow / properties / id / description
```
Added value: +"Dataflow id"
```
addedOutput schema / properties / dataflow / properties / name / description
```
Added value: +"Dataflow name; null when the ILO gives none"
```
addedOutput schema / properties / dataflow / properties / version / description
```
Added value: +"Dataflow version at the ILO"
```

addedOutput schema / properties / rows / description

Added value: +"Raw ILOSTAT observations: one code per dimension, value (untransformed; read with UNIT_MULT) and, when present, attributes such as OBS_STATUS, UNIT_MEASURE and UNIT_MULT"

addedOutput schema / properties / rows_count / description
```
Added value: +"Number of observations returned"
```

Changedilo_get_indicator_metadata7 fields changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

addedOutput schema / properties / data_vintage / description

Added value: +"Last update of the dataflow at the ILO (LAST_UPDATE, yyyy-MM-dd); null when absent"

addedOutput schema / properties / dimensions / description

Added value: +"Dimensions in SDMX key order, each with its codelist id; filter ilo_get_data by these ids"

addedOutput schema / properties / id / description
```
Added value: +"Dataflow id"
```

addedOutput schema / properties / name / description

Added value: +"Dataflow name; null when the ILO gives none"

addedOutput schema / properties / time_dimension / description

Added value: +"Id of the time dimension (filtered via start_period/end_period); null when absent"

addedOutput schema / properties / version / description
```
Added value: +"Dataflow version at the ILO"
```

Changedilo_list_dimension_values10 fields changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

addedOutput schema / properties / codelist / description

Added value: +"Id of the codelist that enumerates the dimension (shared across dataflows)"

addedOutput schema / properties / dataflow / description
```
Added value: +"Dataflow id the dimension belongs to"
```
addedOutput schema / properties / dimension / description
```
Added value: +"Dimension id"
```

addedOutput schema / properties / has_more / description

Added value: +"True when more codes remain after this page"

addedOutput schema / properties / next_offset / description

Added value: +"Offset for the next page; present only when has_more is true"

addedOutput schema / properties / offset / description
```
Added value: +"Codes skipped before this page"
```
addedOutput schema / properties / showing / description
```
Added value: +"Codes returned in this page"
```

addedOutput schema / properties / total_codes / description

Added value: +"Codes matching the search filter (or all codes), across every page"

addedOutput schema / properties / values / description

Added value: +"Valid codes: id is the value for ilo_get_data filters, name is the ILO label"

Changedilo_search_indicators9 fields changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

addedOutput schema / properties / has_more / description

Added value: +"True when more matches remain after this page"

addedOutput schema / properties / hint / description

Added value: +"What to do next: how to narrow or page, or why nothing matched"

addedOutput schema / properties / indicators / description

Added value: +"Matching dataflows, highest ILO relevance weight first; use id with ilo_get_data"

addedOutput schema / properties / next_offset / description

Added value: +"Offset for the next page; present only when has_more is true"

addedOutput schema / properties / offset / description
```
Added value: +"Results skipped before this page"
```
addedOutput schema / properties / showing / description
```
Added value: +"Dataflows returned in this page"
```

addedOutput schema / properties / total_matches / description

Added value: +"Dataflows matching all terms, across every page"

addedOutput schema / properties / vocabulary_notes / description

Added value: +"Translations applied from everyday or US wording to ILO terms (e.g. labor → labour)"

Changedsearch1 field changed

addedOutput schema / properties / attribution / description

Added value: +"Source URLs the figures came from (the provenance source_url of each block), for linking the citation"

6 tool updatesOct 8, 2026

Changedfetch2 fields changed