Return basic runtime metadata for smoke tests and client wiring.

Find all available UNESCO data themes and basic information about them.

UIS themes are the highest-level topical groups used to organize indicators.

Returns: A dictionary with three keys: - "theme information": A list containing each theme code, name, last update date, description of the update, and the count of indicators in that theme. - "theme count": The total number of themes available. - "hint": A string providing guidance on how to use the theme codes for searching indicators

Find all available disaggregation types for UNESCO UIS indicators.

Disaggregation types describe how indicator data can be broken down (e.g. by sex, age group, education level, wealth quintile, etc.).

Returns: A dictionary with: - "disaggregation_types": A list of dicts, each with 'type_code' and 'type_name'. - "count": The total number of disaggregation types. - "hint": Guidance on how to use the type codes.

Get the available values for a specific disaggregation type.

Given a disaggregation type code (e.g. 'SEX', 'AGE', 'EDU_LEVEL'), return all possible values that indicators can be broken down by.

Args: type_code: The disaggregation type code (from list_disaggregation_types).

Returns: A dictionary with: - "type_code": The requested type code. - "type_name": The human-readable name of the disaggregation type. - "values": A list of dicts, each with 'code', 'name', and 'description'. - "count": The total number of values.

Search UNESCO UIS indicators by relevance using text and structured filters.

Use this tool to discover which indicators exist for a topic. Results are capped (default 20, max 50) and intended for interactive exploration. For counting indicators with precise year or date filters, use count_indicators.

Suggested workflow for complex queries:

1. Call list_themes to find the theme code if the user mentions a thematic area.

2. Call list_disaggregation_types and get_disaggregation_values to find codes for concepts like "sex", "primary education", "age group". Do not pass these as the query parameter — use the structured filter parameters instead.

3. Pass discovered codes as structured filters. Only use query for name-based narrowing after applying structured filters.

All provided filters are combined with AND logic. At least one filter must be provided. Results default to 20. If more exist, suggest narrowing with additional filters rather than increasing the limit.

Args: query: Full-text search on indicator name (supports stemming, e.g. "completing" matches "completion"). Secondary refinement only — do not use for concepts that map to themes or disaggregations. theme: Exact theme code (from list_themes). disaggregation_types: List of disaggregation type codes (from list_disaggregation_types). Indicators must support ALL listed types. disaggregation_values: List of disaggregation value codes (from get_disaggregation_values). Indicators must match ALL listed values. limit: Maximum number of results to return (default 20, max 50). Prefer narrowing filters over increasing limit.

Returns: A dictionary with: - "indicators": List of matching indicators, each with: code, name, theme, timeLine_min, timeLine_max. - "query_matches": Number of indicators matched by this query. This is NOT the total count of all UNESCO indicators — it only reflects how many matched these specific filters. Some relevant indicators may be missing if the query is too narrow or the text search didn't capture them. - "returned": Number of indicators included in this response (may be less than query_matches if truncated). - "hint": Guidance on next steps.

Count UNESCO UIS indicators matching precise filter criteria.

Use this tool when the user wants to know how many indicators exist for a given combination of filters, including year coverage or update date constraints. Unlike search_indicators, this tool returns an exact count and accepts year range filters.

All provided filters are combined with AND logic. If no filters are provided, returns the total count of all indicators in the database.

Args: theme: Exact theme code (from list_themes). disaggregation_types: List of disaggregation type codes. Indicators must support ALL listed types. disaggregation_values: List of disaggregation value codes. Indicators must match ALL listed values. coverage_start_year: Only count indicators whose data begins by this year (i.e. timeLine_min <= year). coverage_end_year: Only count indicators whose data extends through this year (i.e. timeLine_max >= year). updated_since: ISO date string (e.g. "2024-01-01"). Only count indicators updated on or after this date.

Returns: A dictionary with: - "count": The exact number of indicators matching all provided filters. - "filters_applied": A summary of which filters were used.

Get detailed metadata for a specific UNESCO UIS indicator.

Returns definitional and methodological information for an indicator, including its glossary definition, purpose, calculation method, data sources, and available disaggregations. Use this after finding indicator codes via search_indicators.

Args: indicator_code: The indicator code (e.g. "CR.1", "ROFST.1.cp").

Returns: A dictionary with: - "code": Indicator code. - "name": Full indicator name. - "theme": Theme code. - "last_update": Date and description of the most recent data release. - "data_availability": Time coverage (min/max year), total record count, and geographic unit types. - "definition": Glossary entry with definition, purpose, calculation method, data source, interpretation, and limitations (if available). - "disaggregations": List of available disaggregation breakdowns (code, name, type).

Get a lightweight summary for one or more UNESCO UIS indicators.

Returns key fields from the local database without making API calls. Much faster than get_indicator_metadata — use this when you need a quick overview of multiple indicators (e.g. after a search) rather than full definitional detail.

Use get_indicator_metadata when you need glossary definitions, methodology, or detailed disaggregation breakdowns for a single indicator.

Args: indicator_codes: List of indicator codes (1–10). Use codes from search_indicators results.

Returns: A dictionary with: - "indicators": List of summaries, each with code, name, theme, timeLine_min/max, totalRecordCount, geoUnitType, lastDataUpdate, and disaggregation_types (list of type names). - "returned": Number of indicators found. - "not_found": List of requested codes that were not in the database.

Search for UNESCO UIS geographic units (countries and regions) by name or code.

Use this to find the geo unit code needed for get_latest_value. Accepts either a country/region name (e.g. "Kenya", "Sub-Saharan Africa") or an ISO3 code directly (e.g. "KEN", "ZWE"). When multiple grouping systems match a region (WB, SDG, UNICEF, etc.), the tool will elicit a choice from the user directly.

Args: query: Country or region name, or ISO3 code (e.g. "Kenya", "ZWE", "Sub-Saharan Africa"). type_filter: Optional. "NATIONAL" to show only countries, "REGIONAL" for aggregates only. region_group: Optional. Restrict to a specific grouping system (e.g. "WB", "SDG", "UNICEF").

Returns: A dictionary with: - "geo_units": List of matches, each with code, name, type, and region_group. - "count": Number of results returned. - "hint": Guidance on next steps.

Get the full time series for a UNESCO UIS indicator for one country or region.

Returns all data points for the indicator × geography combination, optionally filtered to a year range. Ideal for trend analysis and time-series visualisation.

GEOGRAPHY RULES:

• For countries: pass the ISO3 code directly (e.g. "KEN", "FRA").

• For regions: ALWAYS call search_geo_units first — it will ask the user which grouping system to use. Regional names map to multiple codes with different country compositions; using the wrong one gives silently wrong data.

• If omitted, the tool will interactively ask the user for the geography.

Args: indicator_code: The indicator code (e.g. "LR.AG15T99"). geo_unit_code: ISO3 code for countries, or a confirmed code from search_geo_units for regions. Omit to trigger interactive geography lookup. start_year: Optional. First year to include (inclusive). end_year: Optional. Last year to include (inclusive).

Returns: A dictionary with: - "indicator_code", "indicator_name": Indicator identity. - "geo_unit_code", "geo_unit_name": Geography identity. - "data_points": Chronological list of {year, value, qualifier}. - "summary": {total_data_points, min_value, max_value, latest_year, note}.

Rank countries (not regions) by their value for a UNESCO UIS indicator.

Returns the top-N and bottom-N countries for a given indicator in a specific year. Uses dense ranking (tied countries share the same rank).

Year handling:

• strict_year=True (default): year must be provided explicitly.

• strict_year=False and year omitted: uses the year with the most country coverage.

Args: indicator_code: The indicator code (e.g. "LR.AG15T99"). year: Optional. The year to rank countries for. If omitted, the year with the most data points is used only when strict_year=False. top_n: Number of top-ranked countries to return (default 10, max 200). bottom_n: Number of bottom-ranked countries to return (default 10, max 200). strict_year: If True, require an explicit year to avoid implicit year selection.

Returns: A dictionary with: - "indicator_code", "indicator_name": Indicator identity. - "year_used": The year the ranking is based on. - "total_countries_with_data": Countries with non-null values that year. - "top": [{rank, code, name, value}, ...] — highest-value countries. - "bottom": [{rank, code, name, value}, ...] — lowest-value countries. - "note": Context (e.g. year selection rationale, overlap explanation).

Compare a UNESCO UIS indicator across a specific list of countries or regions.

Retrieves the indicator value for each supplied geo unit code and ranks them by value. Use this to directly compare a set of countries or regions you already know the codes for (e.g. from prior searches or elicitations).

Year handling:

• strict_year=True (default): year must be provided; if a geography has no value in that year, it is reported in missing_codes (no fallback year used).

• strict_year=False:

  • year provided: falls back to the nearest available year per geography.

  • year omitted: uses the most recent available year per geography (mixed years possible).

Args: indicator_code: The indicator code (e.g. "LR.AG15T99"). geo_unit_codes: List of geo unit codes to compare (max 20, e.g. ["KEN", "TZA", "UGA"]). Codes must already be known — use search_geo_units to find them. year: Optional. The year to compare. If omitted, the most recent available value for each geography is used only when strict_year=False. strict_year: If True, require an explicit year and disallow fallback years.

Returns: A dictionary with: - "indicator_code", "indicator_name": Indicator identity. - "comparison": [{rank, code, name, value, year, qualifier}, ...] sorted by value desc. - "missing_codes": Geo unit codes for which no data was found. - "note": Context (e.g. mixed years warning, missing codes).

Get the value of a UNESCO UIS indicator for a specific country or region.

Returns a single data point — either the most recent available value, or the value for a specific year. Use this for answering questions like: "What is the literacy rate in Kenya?" or "What was the completion rate in Sub-Saharan Africa in 2015?"

GEOGRAPHY RULES:

• For countries: pass the ISO3 code directly (e.g. "KEN", "FRA").

• For regions: ALWAYS call search_geo_units first — it will ask the user which grouping system to use. Regional names map to multiple codes with different country compositions; using the wrong one gives silently wrong data.

• If omitted, the tool will interactively ask the user for the geography.

To find indicator codes, use search_indicators. Always show the user the year alongside the value, since data is not always available for the most recent years.

Args: indicator_code: The indicator code (e.g. "CR.1", "LR.AG15T99"). geo_unit_code: ISO3 code for countries, or a confirmed code from search_geo_units for regions. Omit to trigger interactive geography lookup. year: Optional. The specific year to retrieve. If omitted, returns the most recent available value. If no data exists for the requested year, returns the nearest available year instead, with a note.

Returns: A dictionary with: - "indicator_code": The indicator code. - "indicator_name": Full name of the indicator. - "geo_unit_code": The geo unit code. - "geo_unit_name": Human-readable geography name. - "year": The year of the returned value. - "value": The numeric data value. - "qualifier": Data quality flag if present (e.g. "<", "~"), else null. - "note": Context about the data point (e.g. year range, year substitution).