worldbank-mcp-server

Get World Bank Poverty and Inequality Estimates

worldbank_get_poverty

Read-onlyIdempotent

Query poverty and inequality estimates from the World Bank Poverty and Inequality Platform (PIP) for economies and for PIP's own aggregates — World, World Bank regions, income groups, and lending groups. Returns the poverty headcount ratio, poverty gap, and poverty severity at any poverty line, plus mean and median welfare and population. Use it for inequality and distribution questions too — survey-based economy rows carry the Gini coefficient, mean log deviation, polarization, and the ten decile income/consumption shares, because PIP returns poverty and inequality in the same row. PIP is a separate dataset from the WDI series worldbank_get_data reads: it measures welfare in PPP dollars per person per day, at a PPP vintage ppp_version selects, and computes its aggregates at any poverty line, where worldbank_get_data carries only the published lines. Every row reports how it was produced. On an economy, estimationType "survey" rows carry the full inequality block; "interpolation", "extrapolation", and "CMD estimation" rows are gap-filled estimates for years no survey covers, and their gini, mld, polarization, and decileShares are null — a documented gap in the source data, not an error. Aggregate rows (isAggregate true) are "actual", "nowcast", or "projection", add popInPoverty, and carry no distributional block.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Pagination page number (1-based).
`year`	No	Reporting year to return. A four-digit year (2022), "all" for the full history, or "MRV" for the most recent year. Omitted behaves as "all". MRV follows fill_gaps: with fill_gaps true each economy resolves to PIP's latest estimate year, and with fill_gaps false to its latest survey year; an aggregate resolves to its newest reporting year. PIP coverage starts in 1963 and ends at the last year of the data release in use; a year outside that span fails with the span named.
`per_page`	No	Results per page (default: server default, max: 1000). "all" countries across "all" years runs to several thousand rows. One page holds at most 70 estimates, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size; notice discloses the reduction whenever the result runs past one page.
`countries`	Yes	Country codes: a single code, an array, or one string separated by commas, semicolons, or pipes. Economies go by ISO3 (IND, USA) or ISO2 (IN, US) code, including those PIP publishes only as model estimates (AFG); "all" returns every economy. PIP's aggregates are served too: WLD; the World Bank regions AFE, AFW, EAS, ECS, LCN, MEA, NAC, SAS, SSF; the income groups HIC, LIC, LMIC (or LMC), UMIC (or UMC); and the lending groups IDX (IDA only), IDB or BLND (IDA blend), IBD or IBRD (IBRD only), and REST. Income groups follow the fiscal-year classification PIP's data release was built with — FY2026 (July 2025) for release 20260922 — applied to every year, so membership can differ from the current one worldbank_get_country reports. IDA (IDA total) is rejected because PIP computes no IDA total: ask for IDX and IDB together. Other aggregate codes (SSA, EAP, FCVY, MIC, LMY) are rejected, and welfare_type and reporting_level cannot be combined with an aggregate.
`fill_gaps`	No	When true (the default), any year the surveys do not cover falls back to PIP's own estimate for it instead of being left out — so a single-year query still answers, and a full-history query returns a row per year rather than only the survey years. Those fallback rows carry no inequality data. Set false to return survey-derived rows only, accepting an empty result for years no survey covers and for economies PIP publishes only as model estimates. It also decides what "MRV" resolves to, and has no effect on aggregate rows.
`ppp_version`	No	PPP vintage to express every dollar figure in — the poverty line, mean, and median — as a four-digit year ("2021", "2017"). It must be one of the vintages PIP's current data release is published at; any other value fails with the available vintages named. Omitted uses the newest vintage of that release. The vintage and release applied are echoed as appliedFilters.pppVersion and appliedFilters.releaseVersion.
`poverty_line`	No	Poverty line in PPP dollars per person per day, at the applied PPP vintage — any threshold, not only the published ones. Omitted uses the international poverty line for that vintage, so the applied value is echoed back on every row as povertyLine rather than assumed here. The poverty line does not affect the inequality fields, which describe the whole distribution.
`welfare_type`	No	Restrict results to one welfare measure. Surveys measure either income or consumption and the two are not directly comparable, so a cross-country comparison is safer pinned to one. Omitted returns whichever each economy publishes, and both where an economy publishes both — thirty-five do, and those return two rows per year.
`reporting_level`	No	Restrict results to one reporting level. Most economies publish a national figure only; ten publish a split and return an extra row per year for it, China with all three levels and the rest pairing national with either urban or rural. Every row states its own reportingLevel.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Context for an empty result set, for a page past the end of the results, for a page size reduced to the page cap, for a result carrying gap-filled or aggregate rows with no inequality data, and for economies fill_gaps false left out.
`estimates`	No	Poverty and inequality estimates for this page — economies and aggregates in one list, ordered by code, year, reporting level, then welfare type.
`totalCount`	No	Total estimates before pagination.
`totalPages`	No	Total number of pages.
`currentPage`	No	Page number requested — past totalPages when the request ran off the end.
`appliedFilters`	No	The effective parameters sent to PIP — confirms country code normalization and which filters were in force for these estimates.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 25, 2026

changedInput schema / properties / countries / anyOf

Previous value: -[
-  {
-    "description": "A single country code, a comma-separated list, or \"all\".",
-    "pattern": "[^\\s;,]",
-    "type": "string"
-  },
-  {
-    "description": "An array of country codes.",
-    "items": {
-      "description": "A country code.",
-      "type": "string"
-    },
-    "minItems": 1,
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "A single country code, a list separated by commas, semicolons, or pipes, or \"all\".",
+    "pattern": "[^\\s;,|]",
+    "type": "string"
+  },
+  {
+    "description": "An array of country codes; an element holding several codes separated by commas, semicolons, or pipes is split too.",
+    "items": {
+      "description": "A country code.",
+      "type": "string"
+    },
+    "minItems": 1,
+    "type": "array"
+  }
+]

changedInput schema / properties / countries / description

Previous value: -"Country codes: a single code, an array, or one string separated by commas or semicolons. Economies go by ISO3 (IND, USA) or ISO2 (IN, US) code, including those PIP publishes only as model estimates (AFG); \"all\" returns every economy. PIP's aggregates are served too: WLD; the World Bank regions AFE, AFW, EAS, ECS, LCN, MEA, NAC, SAS, SSF; the income groups HIC, LIC, LMIC (or LMC), UMIC (or UMC); and the lending groups IDX (IDA only), IDB or BLND (IDA blend), IBD or IBRD (IBRD only), and REST. Income groups follow the fiscal-year classification PIP's data release was built with — FY2026 (July 2025) for release 20260922 — applied to every year, so membership can differ from the current one worldbank_get_country reports. IDA (IDA total) is rejected because PIP computes no IDA total: ask for IDX and IDB together. Other aggregate codes (SSA, EAP, FCVY, MIC, LMY) are rejected, and welfare_type and reporting_level cannot be combined with an aggregate."New value: +"Country codes: a single code, an array, or one string separated by commas, semicolons, or pipes. Economies go by ISO3 (IND, USA) or ISO2 (IN, US) code, including those PIP publishes only as model estimates (AFG); \"all\" returns every economy. PIP's aggregates are served too: WLD; the World Bank regions AFE, AFW, EAS, ECS, LCN, MEA, NAC, SAS, SSF; the income groups HIC, LIC, LMIC (or LMC), UMIC (or UMC); and the lending groups IDX (IDA only), IDB or BLND (IDA blend), IBD or IBRD (IBRD only), and REST. Income groups follow the fiscal-year classification PIP's data release was built with — FY2026 (July 2025) for release 20260922 — applied to every year, so membership can differ from the current one worldbank_get_country reports. IDA (IDA total) is rejected because PIP computes no IDA total: ask for IDX and IDB together. Other aggregate codes (SSA, EAP, FCVY, MIC, LMY) are rejected, and welfare_type and reporting_level cannot be combined with an aggregate."

changedInput schema / properties / per_page / description

Previous value: -"Results per page (default: server default, max: 1000). \"all\" countries across \"all\" years runs to several thousand rows. One page holds at most 70 estimates, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap, disclosed in notice, and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size."New value: +"Results per page (default: server default, max: 1000). \"all\" countries across \"all\" years runs to several thousand rows. One page holds at most 70 estimates, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size; notice discloses the reduction whenever the result runs past one page."

Changed1 schema field changedSep 25, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `country_not_found`: No economy or aggregate PIP publishes goes by one or more of the codes, including a two-character code the World Bank country listing does not carry. `ambiguous_aggregate`: IDA or its ISO2 code XG names WDI's IDA total, which PIP does not compute. `unserved_aggregate`: An aggregate code this tool does not serve: an FCV or PovcalNet grouping from PIP's regions table (FCVY, SSA, EAP), or a WDI income aggregate PIP computes none for (MIC, LMY). `aggregate_filter_conflict`: welfare_type or reporting_level was set alongside an aggregate code. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `country_not_found`: No economy or aggregate PIP publishes goes by one or more of the codes, including a two-character code the World Bank country listing does not carry. `ambiguous_aggregate`: IDA or its ISO2 code XG names WDI's IDA total, which PIP does not compute. `unserved_aggregate`: An aggregate code this tool does not serve: an FCV or PovcalNet grouping from PIP's regions table (FCVY, SSA, EAP), or a WDI income aggregate PIP computes none for (MIC, LMY). `aggregate_filter_conflict`: welfare_type or reporting_level was set alongside an aggregate code. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error, or the World Bank Indicators API country listing that resolves an ISO2 code could not be loaded. Other values are possible when a failure originates below the handler."

Changed26 schema fields changedSep 25, 2026

changedInput schema / properties / countries / description

Previous value: -"Country codes. PIP identifies economies by ISO3 code (IND, USA, BRA); \"all\" returns every economy it covers. Pass a single code, an array, or one string separated by commas or semicolons. Regional, income-group, and world aggregate codes (WLD, SSF, HIC) are not served by this dataset — query the individual economies instead."New value: +"Country codes: a single code, an array, or one string separated by commas or semicolons. Economies go by ISO3 (IND, USA) or ISO2 (IN, US) code, including those PIP publishes only as model estimates (AFG); \"all\" returns every economy. PIP's aggregates are served too: WLD; the World Bank regions AFE, AFW, EAS, ECS, LCN, MEA, NAC, SAS, SSF; the income groups HIC, LIC, LMIC (or LMC), UMIC (or UMC); and the lending groups IDX (IDA only), IDB or BLND (IDA blend), IBD or IBRD (IBRD only), and REST. Income groups follow the fiscal-year classification PIP's data release was built with — FY2026 (July 2025) for release 20260922 — applied to every year, so membership can differ from the current one worldbank_get_country reports. IDA (IDA total) is rejected because PIP computes no IDA total: ask for IDX and IDB together. Other aggregate codes (SSA, EAP, FCVY, MIC, LMY) are rejected, and welfare_type and reporting_level cannot be combined with an aggregate."

changedInput schema / properties / fill_gaps / description

Previous value: -"When true (the default), any year the surveys do not cover falls back to PIP's own estimate for it instead of being left out — so a single-year query still answers, and a full-history query returns a row per year rather than only the survey years. Those fallback rows carry no inequality data. Set false to return survey-derived rows only, accepting an empty result for years no survey covers."New value: +"When true (the default), any year the surveys do not cover falls back to PIP's own estimate for it instead of being left out — so a single-year query still answers, and a full-history query returns a row per year rather than only the survey years. Those fallback rows carry no inequality data. Set false to return survey-derived rows only, accepting an empty result for years no survey covers and for economies PIP publishes only as model estimates. It also decides what \"MRV\" resolves to, and has no effect on aggregate rows."

changedInput schema / properties / year / description

Previous value: -"Reporting year to return. A four-digit year (2022), \"all\" for the full history, or \"MRV\" for the most recent year available. Omitted behaves as \"all\". PIP coverage starts in 1963 and runs to the current year."New value: +"Reporting year to return. A four-digit year (2022), \"all\" for the full history, or \"MRV\" for the most recent year. Omitted behaves as \"all\". MRV follows fill_gaps: with fill_gaps true each economy resolves to PIP's latest estimate year, and with fill_gaps false to its latest survey year; an aggregate resolves to its newest reporting year. PIP coverage starts in 1963 and ends at the last year of the data release in use; a year outside that span fails with the span named."

changedOutput schema / properties / appliedFilters / properties / countries / description

Previous value: -"Country codes as sent to PIP — arrays and semicolon-separated input are normalized to a comma-joined list, so this shows the value actually queried."New value: +"Codes as queried, comma-joined across economies and aggregates: uppercased and deduplicated, two-character codes resolved to their three-character form (NG → NGA), and WDI group spellings read as PIP's (LMC → LMIC, IDB → BLND, IBD → IBRD). PIP's IDA-only group stays IDX, since IDA means IDA total. Every code here can be sent back as countries and asks for the same economy or group."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `country_not_found`: PIP does not recognize one or more of the country codes. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error, which an aggregate country code also produces. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `country_not_found`: No economy or aggregate PIP publishes goes by one or more of the codes, including a two-character code the World Bank country listing does not carry. `ambiguous_aggregate`: IDA or its ISO2 code XG names WDI's IDA total, which PIP does not compute. `unserved_aggregate`: An aggregate code this tool does not serve: an FCV or PovcalNet grouping from PIP's regions table (FCVY, SSA, EAP), or a WDI income aggregate PIP computes none for (MIC, LMY). `aggregate_filter_conflict`: welfare_type or reporting_level was set alongside an aggregate code. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "country_not_found",
-  "invalid_parameter",
-  "ppp_version_unavailable",
-  "upstream_unavailable"
-]New value: +[
+  "country_not_found",
+  "ambiguous_aggregate",
+  "unserved_aggregate",
+  "aggregate_filter_conflict",
+  "invalid_parameter",
+  "ppp_version_unavailable",
+  "upstream_unavailable"
+]

changedOutput schema / properties / estimates / description

Previous value: -"Poverty and inequality estimates for this page, ordered by country, year, reporting level, then welfare type."New value: +"Poverty and inequality estimates for this page — economies and aggregates in one list, ordered by code, year, reporting level, then welfare type."

changedOutput schema / properties / estimates / items / description

Previous value: -"One country × year × reporting-level × welfare-type estimate."New value: +"One economy × year × reporting-level × welfare-type estimate, or one aggregate × year."

changedOutput schema / properties / estimates / items / properties / countryCode / description

Previous value: -"ISO3 country code."New value: +"ISO3 code of the economy, or the aggregate code (SSF, LIC, WLD) on an aggregate row — IDX for PIP's IDA-only group. Accepted back as countries."

changedOutput schema / properties / estimates / items / properties / countryName / description

Previous value: -"Economy name."New value: +"Economy or aggregate name — \"IDA only\" for IDX, as WDI names it."

changedOutput schema / properties / estimates / items / properties / estimationType / description

Previous value: -"How the row was produced: \"survey\" carries the full inequality block; \"interpolation\", \"extrapolation\", and \"CMD estimation\" are gap-filled and carry none. The last is what PIP publishes for economies it has no survey for at all."New value: +"How the row was produced. On an economy: \"survey\" carries the full inequality block; \"interpolation\", \"extrapolation\", and \"CMD estimation\" are gap-filled and carry none, the last being what PIP publishes for economies it has no survey for at all. On an aggregate: \"actual\", \"nowcast\", or \"projection\"."

addedOutput schema / properties / estimates / items / properties / isAggregate

Added value: +{
+  "description": "True on a PIP aggregate — World, a region, an income group, or a lending group — whose median, distributional block, survey fields, welfareType, and reportingLevel are null.",
+  "type": "boolean"
+}

changedOutput schema / properties / estimates / items / properties / isInterpolated / description

Previous value: -"True on the interpolated and extrapolated rows. Read estimationType instead of relying on this alone — a \"CMD estimation\" row is also gap-filled but reports false here."New value: +"True on the interpolated and extrapolated rows. Read estimationType instead of relying on this alone — a \"CMD estimation\" row is also gap-filled but reports false here. Null on aggregate rows."

changedOutput schema / properties / estimates / items / properties / isInterpolated / type
```
Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]
```

changedOutput schema / properties / estimates / items / properties / median / description

Previous value: -"Median daily welfare per person in PPP dollars."New value: +"Median daily welfare per person in PPP dollars. Null on aggregate rows, which PIP publishes without one."

addedOutput schema / properties / estimates / items / properties / popInPoverty

Added value: +{
+  "description": "Number of people below the poverty line, as PIP publishes it on aggregate rows. Null on economy rows, where population × headcount gives it.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / estimates / items / properties / regionCode / description

Previous value: -"PIP region code (e.g. SAS, NAC, SSA)."New value: +"PIP region code of the economy (e.g. SAS, NAC, SSF); null on an aggregate row."

changedOutput schema / properties / estimates / items / properties / regionCode / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / estimates / items / properties / regionName / description

Previous value: -"PIP region name."New value: +"PIP region name of the economy; null on an aggregate row."

changedOutput schema / properties / estimates / items / properties / regionName / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / estimates / items / properties / reportingLevel / description

Previous value: -"Coverage of this estimate: national, urban, or rural."New value: +"Coverage of this estimate: national, urban, or rural. Null on an aggregate row."

changedOutput schema / properties / estimates / items / properties / reportingLevel / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / estimates / items / properties / welfareType / description

Previous value: -"Whether the underlying survey measures income or consumption. The two are not directly comparable across economies."New value: +"Whether the underlying survey measures income or consumption. The two are not directly comparable across economies. Null on an aggregate row, which spans both."

changedOutput schema / properties / estimates / items / properties / welfareType / type
```
Previous value: -"string"New value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / estimates / items / required

Previous value: -[
-  "countryCode",
-  "countryName",
-  "regionCode",
-  "regionName",
-  "reportingYear",
-  "reportingLevel",
-  "welfareType",
-  "povertyLine",
-  "headcount",
-  "povertyGap",
-  "povertySeverity",
-  "watts",
-  "mean",
-  "median",
-  "gini",
-  "mld",
-  "polarization",
-  "decileShares",
-  "population",
-  "surveyYear",
-  "surveyAcronym",
-  "surveyComparability",
-  "comparableSpell",
-  "estimationType",
-  "isInterpolated"
-]New value: +[
+  "countryCode",
+  "countryName",
+  "regionCode",
+  "regionName",
+  "reportingYear",
+  "reportingLevel",
+  "welfareType",
+  "povertyLine",
+  "headcount",
+  "povertyGap",
+  "povertySeverity",
+  "watts",
+  "mean",
+  "median",
+  "gini",
+  "mld",
+  "polarization",
+  "decileShares",
+  "population",
+  "popInPoverty",
+  "surveyYear",
+  "surveyAcronym",
+  "surveyComparability",
+  "comparableSpell",
+  "estimationType",
+  "isInterpolated",
+  "isAggregate"
+]

changedOutput schema / properties / notice / description

Previous value: -"Context for an empty result set, for a page past the end of the results, for a page size reduced to the page cap, or for a result carrying gap-filled rows with no inequality data."New value: +"Context for an empty result set, for a page past the end of the results, for a page size reduced to the page cap, for a result carrying gap-filled or aggregate rows with no inequality data, and for economies fill_gaps false left out."

Changed15 schema fields changedSep 12, 2026

changedInput schema / properties / per_page / description

Previous value: -"Results per page (default: server default, max: 1000). \"all\" countries across \"all\" years runs to a few thousand rows."New value: +"Results per page (default: server default, max: 1000). \"all\" countries across \"all\" years runs to several thousand rows. One page holds at most 70 estimates, which keeps a response within about 50 KB; a larger value, the server default included, is reduced to that cap, disclosed in notice, and echoed as appliedFilters.perPage, and totalPages is counted at the reduced size."

changedInput schema / properties / poverty_line / description

Previous value: -"Poverty line in PPP dollars per person per day — any threshold, not only the published ones. Omitted uses the international poverty line of the PIP release currently served, so the applied value is echoed back on every row as povertyLine rather than assumed here. The poverty line does not affect the inequality fields, which describe the whole distribution."New value: +"Poverty line in PPP dollars per person per day, at the applied PPP vintage — any threshold, not only the published ones. Omitted uses the international poverty line for that vintage, so the applied value is echoed back on every row as povertyLine rather than assumed here. The poverty line does not affect the inequality fields, which describe the whole distribution."

addedInput schema / properties / ppp_version

Added value: +{
+  "anyOf": [
+    {
+      "const": "",
+      "type": "string"
+    },
+    {
+      "description": "A PPP vintage year.",
+      "pattern": "^\\d{4}$",
+      "type": "string"
+    }
+  ],
+  "description": "PPP vintage to express every dollar figure in — the poverty line, mean, and median — as a four-digit year (\"2021\", \"2017\"). It must be one of the vintages PIP's current data release is published at; any other value fails with the available vintages named. Omitted uses the newest vintage of that release. The vintage and release applied are echoed as appliedFilters.pppVersion and appliedFilters.releaseVersion."
+}

changedOutput schema / properties / appliedFilters / properties / perPage / description

Previous value: -"Results per page used, including the server default."New value: +"Results per page actually served — the requested size or server default, reduced to the page cap when larger. totalPages is counted at this size."

addedOutput schema / properties / appliedFilters / properties / pppVersion

Added value: +{
+  "description": "PPP vintage every dollar figure in these estimates is expressed in, whether requested or resolved as the newest vintage of the release.",
+  "type": "string"
+}

addedOutput schema / properties / appliedFilters / properties / releaseVersion

Added value: +{
+  "description": "PIP data release the estimates come from, as its YYYYMMDD stamp — the newest release PIP lists. Survey and gap-filled rows share it.",
+  "type": "string"
+}

addedOutput schema / properties / appliedFilters / properties / requestedPerPage

Added value: +{
+  "description": "Page size asked for, requested or server default, present only when it exceeded the page cap and perPage was reduced.",
+  "type": "number"
+}

changedOutput schema / properties / appliedFilters / required

Previous value: -[
-  "countries",
-  "fillGaps",
-  "page",
-  "perPage"
-]New value: +[
+  "countries",
+  "pppVersion",
+  "releaseVersion",
+  "fillGaps",
+  "page",
+  "perPage"
+]

changedOutput schema / properties / currentPage / description

Previous value: -"Current page number."New value: +"Page number requested — past totalPages when the request ran off the end."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `country_not_found`: PIP does not recognize one or more of the country codes. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `upstream_unavailable`: PIP answered with a server error, which an aggregate country code also produces. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `country_not_found`: PIP does not recognize one or more of the country codes. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `ppp_version_unavailable`: ppp_version names a PPP vintage PIP's current data release is not published at. `upstream_unavailable`: PIP answered with a server error, which an aggregate country code also produces. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "country_not_found",
-  "invalid_parameter",
-  "upstream_unavailable"
-]New value: +[
+  "country_not_found",
+  "invalid_parameter",
+  "ppp_version_unavailable",
+  "upstream_unavailable"
+]

addedOutput schema / properties / estimates / items / properties / comparableSpell

Added value: +{
+  "description": "The span of years the comparable series behind this row covers, as PIP labels it (\"2022\", \"2011 - 2022\"). Null on gap-filled rows.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / estimates / items / properties / surveyComparability

Added value: +{
+  "description": "PIP's series comparability code within the economy: 0 is its oldest comparable series and the code steps up each time comparability breaks, so two survey rows of one economy compare over time only when they share it. Null on gap-filled rows.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / estimates / items / required

Previous value: -[
-  "countryCode",
-  "countryName",
-  "regionCode",
-  "regionName",
-  "reportingYear",
-  "reportingLevel",
-  "welfareType",
-  "povertyLine",
-  "headcount",
-  "povertyGap",
-  "povertySeverity",
-  "watts",
-  "mean",
-  "median",
-  "gini",
-  "mld",
-  "polarization",
-  "decileShares",
-  "population",
-  "surveyYear",
-  "surveyAcronym",
-  "estimationType",
-  "isInterpolated"
-]New value: +[
+  "countryCode",
+  "countryName",
+  "regionCode",
+  "regionName",
+  "reportingYear",
+  "reportingLevel",
+  "welfareType",
+  "povertyLine",
+  "headcount",
+  "povertyGap",
+  "povertySeverity",
+  "watts",
+  "mean",
+  "median",
+  "gini",
+  "mld",
+  "polarization",
+  "decileShares",
+  "population",
+  "surveyYear",
+  "surveyAcronym",
+  "surveyComparability",
+  "comparableSpell",
+  "estimationType",
+  "isInterpolated"
+]

changedOutput schema / properties / notice / description

Previous value: -"Context for an empty result set, or for a result carrying gap-filled rows with no inequality data."New value: +"Context for an empty result set, for a page past the end of the results, for a page size reduced to the page cap, or for a result carrying gap-filled rows with no inequality data."

Changed22 schema fields changedSep 12, 2026
- removedOutput schema / properties / estimates / items / properties / gini / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / gini / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / headcount / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / headcount / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / mean / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / mean / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / median / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / median / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / mld / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / mld / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / polarization / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / polarization / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / population / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / population / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / povertyGap / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / povertyGap / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / povertySeverity / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / povertySeverity / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / surveyYear / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / surveyYear / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / estimates / items / properties / watts / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / estimates / items / properties / watts / type
```
Added value: +[
+  "number",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "estimates",
+      "appliedFilters",
+      "totalCount",
+      "currentPage",
+      "totalPages"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `country_not_found`: PIP does not recognize one or more of the country codes. `invalid_parameter`: PIP rejected the value supplied for a query parameter other than country. `upstream_unavailable`: PIP answered with a server error, which an aggregate country code also produces. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "country_not_found",
+            "invalid_parameter",
+            "upstream_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "estimates",
-  "appliedFilters",
-  "totalCount",
-  "currentPage",
-  "totalPages"
-]

AddedAug 10, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent behavior, but the description adds substantial transparency: estimationType variants, null inequality fields for gap-filled rows, aggregate row behavior, PPP vintage selection, pagination reduction, and documented gaps in source data. There is no contradiction with the annotations.

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?

Core purpose and return values are front-loaded, and each subsequent sentence contributes new operational or data-quality information. The length is justified by the tool's complexity; no filler or redundant restatement of the schema is present.

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 nine-parameter tool with output schema, the description covers edge cases that would otherwise be opaque: survey versus filled estimates, aggregate projections, unsupported aggregate IDs, PPP vintage errors, and pagination limits. The definition is complete enough for correct selection and use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though the schema already covers all parameters, the description adds crucial semantic detail: valid aggregate codes, rejected codes like IDA and SSA, welfare_type behavior when economies publish both measures, MRV resolution under fill_gaps, and per_page cap reduction. This materially improves correct invocation.

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 first sentence names the exact dataset (World Bank Poverty and Inequality Platform), the resources it queries (economies and PIP aggregates), and the data returned. It also clearly distinguishes this tool from the sibling worldbank_get_data by identifying PIP as a separate dataset from the WDI series.

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?

The description explicitly says to use this tool for inequality and distribution questions and clarifies when worldbank_get_data is the different alternative. This gives an agent concrete guidance for selecting among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All worldbank-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Get World Bank Poverty and Inequality Estimates

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources