worldbank-al

Retrieve and interpret World Bank annual development, macroeconomic, and demographic indicators with country comparisons and citation.

Skill: World Bank Open Data

FEATURED — agent skill for retrieving, interpreting, and citing World Bank Open Data. Pairs with the worldbank-mcp server. The API is open: NO API KEY is required.

Use imperative voice. Follow these numbered rules.

---

1. Name

worldbank — World Bank Open Data skill.

2. Purpose

Equip the agent to find the right World Bank indicator, retrieve its annual time series for one or more countries, interpret the values correctly, and cite the result. Use this skill together with the World Bank MCP server, which exposes 6 tools over stdio.

3. When to use World Bank

Use World Bank Open Data when the question involves:

• Cross-country development indicators — health, education, poverty, environment, infrastructure.
• Macroeconomic indicators with long annual history — GDP, GDP per capita, GDP growth, inflation, unemployment.
• Demographics — population, life expectancy, fertility.
• Comparisons across many countries or regions, including aggregates (World, income groups, regions).
• A need for free, open, authoritative data with deep historical coverage.

4. When NOT to use World Bank

Do not use World Bank for:

• High-frequency or real-time data (daily, intraday, monthly market data). Use FRED (for US/economic series) or a markets API instead.
• The very latest quarter or month — World Bank data is annual and the most recent year(s) are often not yet published (null).
• Firm-level, ticker, or price data — out of scope.

5. Environment

NONE. There is no API key, token, or account. The MCP server runs with "env": {}. Optional tuning only: WORLDBANK_API_BASE_URL, WORLDBANK_TIMEOUT_MS, WORLDBANK_MAX_RETRIES, LOG_LEVEL. Never add a fictional WORLDBANK_API_KEY.

6. Operations (the 6 tools)

Tool	Use it to
worldbank_search_indicators	Find indicator codes by keyword.
worldbank_indicator_metadata	Confirm name, unit, source, definition, topics.
worldbank_indicator_data	Fetch the time-series data (the main tool).
worldbank_country	Resolve country codes / metadata.
worldbank_topics	Browse the 20+ indicator topics.
worldbank_request	Generic passthrough to any /v2 endpoint (source, region, incomelevel, lendingtype, topic/{id}/indicator, …).

7. Discovery workflow

1. If the indicator code is unknown, call worldbank_search_indicators with a keyword and pick the best { id, name }.
2. Optionally browse worldbank_topics to navigate by theme.
3. Confirm the chosen indicator's unit/definition with worldbank_indicator_metadata before reporting numbers.

Popular codes to recognize:

Code	Indicator
NY.GDP.MKTP.CD	GDP (current US$)
NY.GDP.PCAP.CD	GDP per capita (current US$)
NY.GDP.MKTP.KD.ZG	GDP growth (annual %)
SP.POP.TOTL	Population, total
FP.CPI.TOTL.ZG	Inflation, consumer prices (annual %)
SL.UEM.TOTL.ZS	Unemployment (% of labor force)
SP.DYN.LE00.IN	Life expectancy at birth (years)
EN.ATM.CO2E.PC	CO2 emissions (metric tons per capita)
SI.POV.DDAY	Poverty headcount ratio (% of population)

8. Data-retrieval workflow

1. Choose country code(s): ISO3 (USA), ISO2 (US), all, or multiple joined with ; (USA;CHN;IND).
2. Choose the time window: a fixed range date: "2010:2023" for trends, or mrv: N for the N most recent values.
3. Call worldbank_indicator_data with country, indicator, and date/mrv (use per_page/page only if needed; keep per_page modest).
4. Prefer a single multi-country call over many single-country calls.

9. Interpreting data

• value can be null for years with no observation — treat as missing.
• Data endpoints return [paginationMeta, dataArray]; the dedicated tools return the data array. With worldbank_request, read index 0 (meta) and index 1 (records), and paginate when pages > 1.
• Always pair numbers with their unit (from metadata).
• Distinguish aggregates from countries: WLD (World), EUU (European Union), and income-level/region groups are not single countries.

10. Citation rules

Always cite. Use this exact pattern:

World Bank, (), , . https://data.worldbank.org/indicator/

Include: "World Bank", indicator name + code, country, year(s), and the indicator URL.

11. Freshness

• Data is annual. Note lastupdated (from pagination metadata via worldbank_request) when freshness matters.
• The most recent year(s) may be null because the value is not yet published. Do not present a missing recent year as zero or as a real figure.

12. Numeric integrity

Never invent numbers. A null value means missing — report it as "data not available", not as 0. Quote only values returned by the tools.

13. Error handling

• [{ "message": [...] }] body → invalid parameter/code. Read key/value, fix the indicator/country code or param, retry once. Do not blindly retry.
• HTTP 429 → back off; rely on the server's retries and on caching.
• Empty array → widen the date, use mrv, or verify codes with worldbank_search_indicators / worldbank_country.

14. Cost

The API is free and open. Still be polite: cache annual data, reuse static lookups (topics, country list, sources), avoid huge per_page, and do not loop tightly.

15. Not economic advice

World Bank data is informational. Do not present analysis as financial, investment, or economic advice. Report figures and cite sources.

16. Agent checklist

• Indicator code confirmed (searched if unknown).
• Unit/definition checked when it affects interpretation.
• Correct country code(s) and time window chosen.
• null/empty handled honestly (no invented values).
• Aggregates vs. countries distinguished.
• Citation included (World Bank + name + code + country + year + URL).
• No API key used ("env": {}).

17. Example workflows

• Single figure: search → metadata → worldbank_indicator_data with mrv: 1 → cite.
• Trend: search → worldbank_indicator_data with date: "2000:2023" → chart → cite.
• Comparison: search → worldbank_indicator_data with country: "USA;CHN;IND" → table → cite.

See recipes/ for full walkthroughs.

18. Common mistakes

• Guessing an indicator code instead of searching.
• Treating null as zero or inventing a value.
• Forgetting to cite.
• Confusing an aggregate (WLD, income group) with a country.
• Adding a nonexistent API key.
• Requesting the current quarter from an annual dataset.

19. Maintenance

• Periodically re-confirm popular codes via worldbank_search_indicators.
• Refresh cached series using the lastupdated field.
• Keep this skill paired with the worldbank-mcp server; if tool names change, update Section 6 and reference/endpoints.md.

Verification needed: confirm with https://datahelpdesk.worldbank.org/knowledgebase/articles/889392