back
loading skill details...
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, <indicator name> (<code>), <country>, <year>.**
> https://data.worldbank.org/indicator/<code>
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
don't have the plugin yet? install it then click "run inline in claude" again.
restructured into implexa's six-component format, made api connection explicit, formalized decision points for missing data and error codes, clarified output contract and outcome signals, and preserved all original procedure logic and voice.
this skill equips agents 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 it when you need cross-country development indicators (health, education, poverty, environment, infrastructure), macroeconomic time series (gdp, inflation, unemployment), or demographic data (population, life expectancy, fertility) with long historical coverage. world bank data is free, open, and authoritative. do not use this skill for high-frequency or real-time data, the very latest unpublished quarters, or firm-level ticker data.
external connection: world bank open data api v2 (via worldbank-mcp server)
WORLDBANK_API_BASE_URL env var to override)WORLDBANK_TIMEOUT_MS (request timeout), WORLDBANK_MAX_RETRIES (http 429 backoff), LOG_LEVEL (debug/info/warn/error)six tools exposed by the mcp server:
worldbank_search_indicators: find indicator codes by keywordworldbank_indicator_metadata: fetch unit, definition, source, topics for a codeworldbank_indicator_data: retrieve time-series values (the main tool)worldbank_country: resolve country codes and metadataworldbank_topics: browse the 20+ indicator topic categoriesworldbank_request: generic passthrough to any /v2 endpoint (sources, regions, income levels, lending types, topic endpoints, etc.)context needed from user:
USA), iso2 (US), all, or multiple joined with ; (USA;CHN;IND)date: "2010:2023") or most-recent-values count (mrv: N)confirm the indicator code. if unknown, call worldbank_search_indicators with a keyword. review the results and pick the best match by id and name. if the code is already known (e.g., NY.GDP.MKTP.CD for gdp), skip this step.
check the indicator's metadata. call worldbank_indicator_metadata with the chosen code to confirm the unit, definition, source, and relevant topics. this step prevents misinterpretation (e.g., ensuring you know the figure is in current usd, not constant).
resolve country code(s). if the country name is provided but the code is unknown, call worldbank_country to map the name to iso3 or iso2 code. if comparing multiple countries, concatenate codes with ; (e.g., USA;CHN;IND). use all only for truly global comparisons; this will return a large dataset.
fetch the time series. call worldbank_indicator_data with the indicator code, country code(s), and a time window. prefer date: "YYYY:YYYY" for a fixed range (e.g., date: "2000:2023" for a trend) or mrv: N for the n most recent values (e.g., mrv: 1 for the latest single year). omit per_page and page unless pagination is necessary; keep per_page under 100 to be polite to the api.
handle the response structure. the tool returns a flat data array. if using worldbank_request for advanced queries, the response is [paginationMeta, dataArray]: read index 0 for metadata (including lastupdated and total pages) and index 1 for records. paginate if pages > 1 by incrementing the page param.
interpret values correctly. check each data point's value field. a null means the data is missing for that year; do not treat it as zero or invent a number. pair all reported figures with their unit (from step 2's metadata). note whether you are reporting a single country, a region aggregate (e.g., EUU for european union), or a world aggregate (WLD). distinguish aggregates clearly from individual countries.
cite the source. include a citation using this exact pattern: World Bank, ), . always include the indicator name, code, country, year(s), and the url. if freshness matters, note the lastupdated value from the api response.
if the indicator code is unknown: search using worldbank_search_indicators. do not guess. if the search returns no results or ambiguous matches, try a broader or narrower keyword, then verify the top candidate with worldbank_indicator_metadata.
if the country code is unknown: call worldbank_country to resolve it. do not attempt to derive the code from the country name alone.
if the response contains null values for the requested years: the data is simply not available (not yet published, or never collected). report "data not available" for those years. do not substitute zero or any invented figure.
if the response is empty (no records): the country, indicator, or date range combination returned no data. try one or more of: widen the date range, use mrv: N instead of a fixed date, verify the indicator code with worldbank_search_indicators, or check the country code with worldbank_country. if the code is valid but no data exists, report that the indicator is not tracked for that country or time period.
if the api returns an error body with [{ "message": [...] }]: this signals an invalid parameter (bad country code, indicator code, or syntax). read the error message, correct the code or param, and retry once. do not blindly retry.
if http 429 (rate limit) is returned: back off and rely on the server's built-in retry logic and caching. do not hammer the api in a tight loop.
if comparing many countries: prefer a single worldbank_indicator_data call with all country codes joined by ; over multiple single-country calls.
if presenting analysis or recommendations: do not frame world bank figures as financial, investment, or economic advice. report the data and cite the source; let the user draw conclusions.
on success, deliver:
ny.gdp.mktp.cd)), , . lastupdated field from the api metadatadata format: plain text, markdown table, or json as appropriate for the context. do not fabricate missing years; omit them or state "data not available".
file location: not applicable (this skill returns data inline to the agent, not to a file).
the user knows the skill worked when: