de en es ja ko ru zh

ILO Statistics (ILOSTAT) MCP Server

Name: ILO Statistics (ILOSTAT) MCP Server
Author: SidneyBissoli

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

🇧🇷 포르투갈어로 읽기

국제노동기구(International Labour Organization, ILO) 통계 — ILOSTAT 데이터베이스 — 를 위한 공개·호스팅·출처(provenance) 우선 MCP 서버입니다. 설치 불필요, 계정 없음, API 키 불필요입니다. 호스팅된 엔드포인트에 MCP 클라이언트를 연결하고 국가, 연도, 성별, 연령별로 실업, 고용, 임금, 노동시간 및 기타 노동 지표를 조회할 수 있습니다. 이 서버는 Streamable HTTP를 통해 Cloudflare Workers에서 실행되며, 공식 ILOSTAT SDMX REST API에 접속합니다.

모든 응답에는 출처(provenance) 블록(소스 URL, 데이터 vintage, 실제 추출 시각, 라이선스, ILO 인용)이 포함됩니다. 이는 훈련 데이터에서 추정된 수치가 아니라, 감사 추적(audit trail)이 뒤따르는 정확한 수치입니다.

사용하기 (호스팅 — 설정 불필요)

Streamable HTTP 엔드포인트에 MCP 클라이언트를 연결하세요:

https://ilo.sidneybissoli.com/mcp

Claude Desktop / Claude Code 및 원격 서버를 기본 지원하는 기타 클라이언트:

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

MCP 서버를 명령어로 실행하는 클라이언트를 사용하는 경우에는 mcp-remote 브리지를 이용하세요:

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

ilo-mcp-server.sidneybissoli.workers.dev 호스트 이름도 접 등이며 부차적으로 제공됩니다.

Related MCP server: world-bank-economic-mcp

로컬 실행 (stdio)

쿼리를 제3자 호스트로 우회하는 것이 부담스러우신가요? 동일한 서버가 로컬 stdio 프로세스로도 실행되어 공식 ILOSTAT API와 직접 통신합니다 — 동일한 4개의 도구, 리소소 및 프롬프트, 동일한 제한 사항, 동일한 출처 블록을 갖고 있으며 중간에 Cloudflare가 없습니다.

설치 필요 없음 — npm 패키지로 제공됩니다 (ilo-mcp-server, Node ≥ 20):

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

또는 소스에서 실행:

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)

(그런 다음 클라이언트를 node /path/to/ilo-mcp-server/dist/index.js에 연결하세요).

호스팅 서버와의 모든 차이점은 Cloudflare 바인딩이 없다는 점 때문입니다: SDMX 캐시는 메모리 상에만 존재합니다 (구조와 코드목록(codelist)은 세션 내 에서만 재사용되며 세션 간에는 재사용되지 않습니다); 검색 카탈로그는 첫 검색 시 공식 엔드포인트에서 다운로드됩니다 (실제 retrieved_at 시각은 provenance에 기록됩니다); 사용량 지표나 rate limit·인증은 없습니다. 로그는 stderr로 출력되고 — stdout은 JSON-RPC 스트림만 전달합니다. 리포지토리의 Dockerfile이 이 런타임을 빌드합니다(Glama 레지스트리에서 사용).

도구

도구	설명	원천
`ilo_search_indicators`	대략 1,210개의 데이터플로우에 대한 키워드 검색 (`offset`으로 페이지네이션)	로컬 카탈로그 (업스트림 호출 없음)
`ilo_get_indicator_metadata`	한 데이터프로우의 차원, 코드목록, vintage 및 기본 선택 항목	캐시된 구조 (miss → 업스트림 호출)
`ilo_list_dimension_values`	한 차원의 유효 코드 조회 (`offset`으로 페이지네이션)	캐시된 codelist (miss → 업스트림 호출)
`ilo_get_data`	차원과 기간으로 필터링한 관측값	쿼리당 1회의 실시간 REST 호출

일반적인 흐름: ilo_search_indicators → ilo_get_indicator_metadata / ilo_list_dimension_data로 유효한 필터 코드를 확인 → 국가 및 기간 필터와 함께 ilo_get_data 호출.

모든 응답은 provenance 블록 v1.0 (@sbissili/mcp-provenance, provenance_mode 파라미터를 통한 concise/detailed 모드) 을 세 가지 채널로 함께 전달합니다: structuredContent, 네임 스pace닝된 _meta (com.sidneybissoli.ilostat/*), 그리고 텍스트 푸터(footer).

리소스 및 프롬프트

세 개의 리소스 (고정, text/markdown, 업스트림 호출 없음) — 클라이언트가 도구 호출 전에 컨텍스트에 첨부할 수 있는 항목입니다. 대부분의 세션이 "어떤 데이터플로우와 코드를 쓸까"를 알아내기 위해 소비하는 발굴 호출 2–3회를 절약합니다:

URI	내용
`ilostat://guide`	도구 워크플로, 지속적인 코드 규칙 (`REF_AREA` ISO3 + `X`-집계, `SEX`, `AGE`, `FREQ`, 데이터프로 아이디 접미사), 제한 사항, 보고 규칙
`ilostat://reference/key-dataflows`	주제별 검증된 데이터프로우 ID (실업, 고용, 참여, 임금, 근로시간, 비공식, NEET, SDG 8, 생산성)
`ilostat://reference/provenance`	각 provenance 필드의 의미와 ILO 인용 방법

세 가지 프롬프트 — 도구들을 체인으로 연결하고 마지막에 인용 규칙을 제시하는 즉시 사용 가능한 워크플로입니다 (인수는 문자열이며, 기간 인수는 선택 사항입니다):

프롬프트	인수	결과
`lo_country_labour_profile`	`country`, `start_period`, `end_period`	한 국가의 노동시장 프로필 (실업, 참여, 고용률, 비공식 경제, NEET, 근로임금, 근로시간)
`lo_compare_countries`	`countries`, `indicator`, `start_period`, `end_period`	한 번의 데이터 호출로 국가/지역 간 편자 상에비교표를 생성하, 모델링 추정치와 실제 보고 데이터를 구별 표시
`ilo_indicator_trend`	`indicator`, `country`, `start_period`, `end_period`	최초/최후, 최고/최저, `OBS_STATUS` 변환을 포함한 단일 지표의 시계열

리소소와 프롬프트에 인용된 모든 데이터프로우 ID는 테스트 스위트로 카탈로그 시드와 대조 검증되기 때문에, 문서가 검색 결과에 없는 ID를 가리킬 수 없습니다.

작동 방식 및 제한 사항

ilo_get_data에는 REF_AREA 필수이며, 호출당 최대 30개 지역까지 허용됩니다. 무한정(제약 없이) 조회 시 ILO 게이트웨이가 시간 초과(HTTP 504)가 발생하므로, 서버는 그런 쿼리를 발행해 주지 않습니다. 넓은 패널이 필요하다면 지역을 배치(batch)로 나누거나 기간(start_period/end_period)으로 페이지를 나누세요. 무엇을 말하는지 오류 메시지에 설명되어 있습니다.
데이터 쿼리마다 라이브 REST 호출 1회. 데이터는 절대 캐시되지 않습니다 — 모든 ilo_get_data 결과는 요청 시점에 ILOSTAT에서 가져옵니다. 데이터프로우 구조(TTL 24시간)와 codelist(TTL 7일, 데이터프로우 간 공유)만 캐시됩니다.
data_vintage 는 데이터프로우의 마지막 업데이트 날짜이며, 이는 ILO가 게시한(LAST_UPDATE 배지 사항)를 ISO로 정규화한 것입니다.
retrieved_at은 항상 ILOSTAT에서 데이터를 실제로 가져온 순간의 시각입니다 — 캐시된 모든 값의 일부로 보존되며, 빌드 시간이나 응답 시간이 아닙니다. 캐시에서 제공된 응답은 해당 사실을 명시합니다(served_from_cache: true).
지표 카탈로그는 로컬 스냅샷 (약 1,210개 데이터플로우)이며 주기적으로 갱신됩니다. 자체 retrieved_at은 ilo_search_indicators의 provenance에서 보고되므로, 카탈로그가 근심이 담긴 오래된 상태인지 항상 확인할 수 있습니다.
모든 업스트림 호출에는 식별 가능한 User-Agent (서비스 URL + 연락처)이 이어지며, ILO 관리자들이 운영자에게 연락할 수 있습니다.
언어: 영어; 시간대: UTC (ILO 데이터는 영어로 게시).

Provenance 필드

derived — 진정한 변환(집계, 서버 계산 비율, 보간, 조화 표준화)에 대해서만 true이며, 항상 derivation_note가 함께 제공됩니다. 단위 변환과 반올림은 여기 해당되지 않습니다. 이 서버는 값을 변환하지 않으므로 derived는 항상 false입니다.
notices — OBS_STATUS(SDMX의 상태·고지 채널, 예: "Break in series")의 값을 원문 그대로 재현하고 개수와 함께 제공합니다. 관측값별 기술 속성(DECIMALS 등)은 행(rows[].attributes)에 그대로 남습니다.

데이터 라이선스 및 출처 표기

ILOSTAT 데이터 및 메타데이터: CC BY 4.0 (2023-05-03 이후; 라이선스 확인일 2026-08-04).
모든 응답의 ILO 출처 표기(citation 필드)는 다음과 같습니다: `International Labour Organization, ILOSTAT, https://ilostat.ilo.org/data/, accessed .
ILO 로고는 사용하지 않습니다. 이 서비스는 ILO의 포괄을 받은 것과 무관합니다.

자체 호스팅 / 개발

아래 내용 전부는 자체 인스턴스를 구동할 필요가 있는 경우에만 요구됩니다. 공용 서버를 사용할 때에는 필요하지 않습니다.

npm install
npm run typecheck && npm test   # 96 offline tests (parsers, key, tools, output contract, resources/prompts, in-memory catalogue, 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 → 4 tools → 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)

바인딩(wrangler.jsonc 참조): KV SDMX_CACHE, D1 CATALOG_DB, Durable Object USAGE (SQLite-G8 기반 사용량 카운터), CF_VERSION_METADATA. 선택적인 Bearer 인증(wrangler secret put API_KEY); IP당 토큰 버킷 rate limit.

운영자 참고 사항:

ILOSTAT는 Accept 헤더로 협상할 때만 JSON을 반환합니다 (application/vnd.sdmx.{structure,data}+json); ?format=는 사용되지 않고 XML을 반환합니다.
ILO 게이트웨이는 Node.js fetch(undici)가 기본 전송하는 Accept-Language: * 헤더와 같은 요청에 HTTP 500(languageTag1)을 반환합니다. 따라서 모든 업스트림 호출에는 Accept-Language: en을 자동 설정합니다 (Cloudflare 런타임은 해당 헤더를 보내지 않으므로 Worker는 이 문제에 해당하지 않습니다). 또한 식별 가능한 User-Agent를 기대합니다.
카탈로그 갱신은 수동(cron 없음)입니다: 분기마다 수행하거나, 업스트림에 있는 데이터플로우가 검색에서 발견되지 않는 경우 즉시 수행하세요. 절차: 위의 세 시드 명령을 실행합니다. 데이터 조회는 항상 실시간이므로, 오래된버려진 수 있는 것은 검색 카탈로그뿐이며 그 나이는 exposure에 포함됩니다.

평ALS 테스트

@sbissoli/mcp- — 24개의 픽스처를 제공하는 evals/fixtures/queries.ts에 대한 오프라인 테스트는 npm test에서 수행됩니다. 실제 모델로 실행하는 경우(npm run eval)는 Anthropic API를 사용하며ANTHROPIC_API_KEY가 필요합니다(키가 없으면 안내 메시지를 출력하고 종료됩니다). 2026-08-07 실행 결과: top-1 100% (24/24) — evals/results/.

엔드투엔드: evals/e2e/evaluation.xml에 단일 검증 가능한 답변이 있는 복잡한 질문 10개, 답변은 프로덕션(evals/e2e/validacao-respostas.md)에 대해 수동으로 검증되었습니다. 2026-08-07 (Sonnet) 실행: 정확한 문자열 9/10; 실질적 10/10 — evals/results/2026-08-07-e2e.md.

엔드포인트

Route	Purpose
`/`	랜딩 페이지 (서비스 식별 + 연락처 — 공개)
`/health`	활성 상태
`/status`	버전, 도구/리소스/프롬프트 수 및 이름, 출처 계약 버전, 현재 배포 (README 배지에 제공)
`/metrics`	집계 사용량 (MCP 엔드포인트 전용, IP 없음, 쿼리 내용 없음)
`/mcp`	MCP Streamable HTTP

보안

Snyk Agent Scan (2026-08-07): 통과 — 보고서는 security/에 있습니다.

라이선스

코드: MIT. 데이터: ILOSTAT, CC BY 4.0 (위의 "데이터 라이선스 및 출처 표시" 참조).

개인정보

호스팅 서비스의 개인정보 처리방침: PRIVACY.md.

연락처

Sidney da S. P. Bissoli — sbissoli76@gmail.com. 이 서비스는 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.