Search UNICEF child development indicators by keyword.

Returns indicator codes, names, and categories. Use the returned code values with get_indicator_info() or get_data(). Always start here if you don't know the indicator code.

Examples: "mortality", "breastfeeding", "education", "child labour", "stunting"

v1.1.0 advisory layer (additive to v0.9.0/v1.0.0 ambiguity_flag):

• If response carries requires_confirmation=True, STOP and ask the user to disambiguate before calling get_data.

• If response carries recommended + next_step, the model SHOULD call next_step verbatim (e.g. get_indicator_info(code='...')).

• assistant_guidance is a plain-English directive (<200 chars).

• Decision order: curated-ambiguous -> curated-preferred -> confident match -> none (wire-equivalent to v1.0.0). See internal/v1.1.0_design/ for rationale.

List all UNICEF indicator categories (thematic groups).

Categories correspond to SDMX dataflows: CME (child mortality), NUTRITION, EDUCATION, CHILD_PROTECTION, WASH, HIV_AIDS, etc. Use this to browse available topics before searching for specific indicators.

List countries available in the UNICEF database with ISO3 codes.

Optionally filter by region name (case-insensitive partial match). Use the iso3 values in get_data().

Get full metadata for a UNICEF indicator.

Returns description, category, dataflow, and SDMX API details. Use this before calling get_data() to understand what the indicator measures and which disaggregation filters (sex, age, wealth_quintile, residence) apply.

Strict canonical lookup of a UNICEF indicator by its exact code.

Use this INSTEAD of search_indicators when you already have a UNICEF indicator code (e.g. CME_MRY0T4, IM_DTP3, ED_15-24_LR). Do NOT pass natural-language descriptions, synonyms, or partial names — this tool is canonical-only.

Two-tool separation introduced in v0.9.0 to give the LLM a self-describing choice at tool-selection time:

• have a CODE? → lookup_by_code(code)

• have WORDS? → search_indicators(query)

Returns the same canonical metadata shape as get_indicator_info on success. On unknown code, returns an error with an explicit abstain_instruction directing the model to stop — NOT to fall back to search_indicators (which would re-enter the loop that 96% of v9 Arm B stuck queries hit).

Returns:

• on success: {status: "ok", code, name, description, dataflow, sdmx_api, disaggregation_filters, ambiguity_flag: false, ...}

• on unknown code: {status: "error", error, ambiguity_flag: false, abstain_instruction, tip}

• on natural-language input mistakenly passed: {status: "error", error, abstain_instruction directing to search_indicators}

Check what years of data are available for a UNICEF indicator.

Fetches a small sample to determine the time range. Lightweight — does not fetch all observations. Use before get_data() to pick a year range.

Fetch UNICEF data for an indicator and one or more countries.

Returns annual observations from the UNICEF SDMX API. Use format="compact" (default) for a clean 5-column table; use format="full" for all columns including disaggregation details and confidence bounds.

indicator accepts BOTH codes AND human-readable names (v0.7.0). Pass whichever you have from the user's question — the server resolves names to canonical codes for you. Examples: indicator='CME_MRM0' → code passthrough indicator='neonatal mortality' → resolves to 'CME_MRM0' indicator='Under-five mortality rate' → resolves to 'CME_MRY0T4' indicator='U5MR' → resolves to 'CME_MRY0T4' indicator='stunting' → resolves to 'NT_ANT_HAZ_NE2' indicator='LBW' / 'low birth weight' → resolves to 'NT_BW_LBW' Acronyms accepted: NMR, IMR, U5MR, SBR, LBW, ANC1, SAB, BCG, DTP1/3 …

Genuinely ambiguous queries are refused with a disambiguation list. Examples: indicator='child mortality' → refused: pick CME_MRM0 / CME_MRY0 / CME_MRY0T4 / CME_MRY1T4 indicator='vaccination' → refused: pick IM_BCG / IM_DTP1/3 / IM_MCV1/2

Prefer passing the user's phrasing verbatim over guessing the code from memory — that's where the v0.6.x had a documented failure mode (model recalls CME_MRY0T4 thinking it's neonatal mortality; it's under-five). The response echoes the resolution under indicator_resolution so you can confirm the canonical code+name match the user's intent.

countries accepts BOTH ISO3 codes AND country names (v0.6.2). Pass whichever you have from the user's question — the server resolves country names to canonical ISO3 codes for you. Examples: countries=['Burundi'] → resolves to ['BDI'] countries=['BDI', 'Belgium'] → resolves to ['BDI', 'BEL'] countries=['Cote d'Ivoire'] → resolves to ['CIV'] countries=['USA', 'UK'] → resolves to ['USA', 'GBR'] Common synonyms accepted: 'USA'/'United States', 'UK'/'Great Britain', 'Ivory Coast'/'Cote d'Ivoire', 'South Korea', 'DRC', 'Czech Republic', 'Burma', 'Vatican', etc. The response echoes the resolution under country_resolutions and the canonical name+code pairs under countries_returned_with_names so you can confirm intent matched.

Prefer passing the user's country name verbatim over guessing the ISO3 code from memory — that's where v0.6.0 had a documented failure mode.

v0.6.0 server-side hardening: this tool also performs a pre-flight year-frontier check. If start_year or end_year exceeds the indicator's data frontier (max year observed), the call is refused server-side without issuing the SDMX request — preventing the silent-truncation pattern where a range like 2020-2027 returns 2020-2024 and the model extrapolates the missing years. Successful responses include a data_frontier field naming the max year and an explicit no-extrapolation directive.

Disaggregation filters (v1.2.0): sex: "_T" (total, default), "M" (male), "F" (female). age: SDMX AGE code such as "Y0T4", "Y15T19", "Y15T24". The age codelist depends on the indicator's dataflow — call get_indicator_info(code) to see what's supported. filters: dict[str, str | None] for every other dimension. Examples: filters={"WEALTH_QUINTILE": "Q1"} → poorest quintile filters={"RESIDENCE": "U"} → urban filters={"EDUCATION_LEVEL": "ISCED11_2"} → secondary filters={"WEALTH_QUINTILE": "Q1", "RESIDENCE": "U"} → both A None value is treated as "use the dim's total" (typically "_T").

When any non-_T filter is present (typed age= or filters dict non-empty), the response carries mode: "raw_filtered" to signal that the underlying call switched to raw=True + post-filter — same call, different number versus a totals-only response.

Validation: filters are checked against the indicator's actual primary dataflow before the SDMX call. Unsupported (dim, value) pairs are refused with a failed_validation envelope listing available dimensions and codelist values, so the LLM can recover in a single wave instead of retrying blindly.

BREAKING CHANGE FROM v1.1.x: the typed wealth_quintile= and residence= kwargs no longer route to the SDMX call — they are present in the signature only as deprecation trip-wires. Pass them and the call returns a structured migration error pointing at filters={"WEALTH_QUINTILE": ...}. v1.1.x silently dropped these kwargs at the SDMX call and returned the totals slice — that hazard is gone.

Limit defaults to 200 rows — narrow your country/year filters or increase limit (max 500) if you need more data. In raw_filtered mode, rows_truncated: true also means the pre-filter raw pull was larger than limit, so post-filter rows you wanted may be missing.

Get the unicefdata package API reference for Python, R, or Stata.

Returns function signatures, parameter descriptions, and usage examples. Use this when you need to write code that uses the unicefdata package, or when the user wants to move from conversational exploration to reproducible scripts.

Return machine-readable identity, provenance, and version information for this MCP server.

Use this to verify you are connected to the authentic unicefstats-mcp server and to inspect its canonical identity, data source, and publisher information. No API call — returns local metadata only.