# `worldbank__worldbank_get_poverty`

**Get World Bank Poverty and Inequality Estimates**

Query poverty and inequality estimates from the World Bank Poverty and Inequality Platform (PIP) for one or more countries. 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 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 covers individual economies only, so regional and income-group aggregate codes are not accepted. Every row reports how it was produced. 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.

- Server: [World Bank](https://gateway.mcpharbor.dev/docs/servers/worldbank) (`dev.mcpharbor.gateway/worldbank`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/worldbank`
- Upstream tool: exposed by the provider; called through this gateway as `worldbank__worldbank_get_poverty`
- Provider terms: <https://data.worldbank.org/summary-terms-of-use> (verified 2026-09-19)
- Upstream API documentation: <https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation>
- Rate limit: 500 requests per minute
- Attribution required: "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Parameters

- `countries` (any, required): 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,...
- `fill_gaps` (boolean, optional): 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... Default: `true`.
- `page` (integer, optional): Pagination page number (1-based). Default: `1`.
- `per_page` (integer, optional): 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 ...
- `poverty_line` (number, optional): 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...
- `ppp_version` (any, optional): 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...
- `reporting_level` (any, optional): 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...
- `welfare_type` (any, optional): 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 ...
- `year` (string, optional): 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 cu...

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: worldbank__worldbank_get_poverty
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "countries": "example"
    },
    "name": "worldbank__worldbank_get_poverty"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Query poverty and inequality estimates from the World Bank Poverty and Inequality Platform (PIP) for one or more countries. 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 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 covers individual economies only, so regional and income-group aggregate codes are not accepted. Every row reports how it was produced. 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.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "countries": {
        "anyOf": [
          {
            "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"
          }
        ],
        "description": "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."
      },
      "fill_gaps": {
        "default": true,
        "description": "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.",
        "type": "boolean"
      },
      "page": {
        "default": 1,
        "description": "Pagination page number (1-based).",
        "maximum": 9007199254740991,
        "minimum": 1,
        "type": "integer"
      },
      "per_page": {
        "description": "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.",
        "maximum": 1000,
        "minimum": 1,
        "type": "integer"
      },
      "poverty_line": {
        "description": "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.",
        "maximum": 2700,
        "minimum": 0,
        "type": "number"
      },
      "ppp_version": {
        "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."
      },
      "reporting_level": {
        "anyOf": [
          {
            "const": "",
            "type": "string"
          },
          {
            "description": "Restrict to the national, urban, or rural estimate.",
            "enum": [
              "national",
              "urban",
              "rural"
            ],
            "type": "string"
          }
        ],
        "description": "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."
      },
      "welfare_type": {
        "anyOf": [
          {
            "const": "",
            "type": "string"
          },
          {
            "description": "Restrict to surveys measuring income, or to those measuring consumption.",
            "enum": [
              "income",
              "consumption"
            ],
            "type": "string"
          }
        ],
        "description": "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."
      },
      "year": {
        "description": "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.",
        "pattern": "^\\s*(?:\\d{4}|all|MRV)?\\s*$",
        "type": "string"
      }
    },
    "required": [
      "countries"
    ],
    "type": "object"
  },
  "name": "worldbank__worldbank_get_poverty",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "estimates",
          "appliedFilters",
          "totalCount",
          "currentPage",
          "totalPages"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "appliedFilters": {
        "additionalProperties": false,
        "description": "The effective parameters sent to PIP — confirms country code normalization and which filters were in force for these estimates.",
        "properties": {
          "countries": {
            "description": "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.",
            "type": "string"
          },
          "fillGaps": {
            "description": "Whether gap-filling was permitted for this query, including the server default of true.",
            "type": "boolean"
          },
          "page": {
            "description": "Page number requested.",
            "type": "number"
          },
          "perPage": {
            "description": "Results per page actually served — the requested size or server default, reduced to the page cap when larger. totalPages is counted at this size.",
            "type": "number"
          },
          "povertyLine": {
            "description": "Poverty line requested, omitted when the upstream default was used — in which case the applied value is on every row as povertyLine.",
            "type": "number"
          },
          "pppVersion": {
            "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"
          },
          "releaseVersion": {
            "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"
          },
          "reportingLevel": {
            "description": "Reporting-level filter applied, omitted when none.",
            "type": "string"
          },
          "requestedPerPage": {
            "description": "Page size asked for, requested or server default, present only when it exceeded the page cap and perPage was reduced.",
            "type": "number"
          },
          "welfareType": {
            "description": "Welfare-type filter applied, omitted when none.",
            "type": "string"
          },
          "year": {
            "description": "Year filter applied, omitted when none was requested.",
            "type": "string"
          }
        },
        "required": [
          "countries",
          "pppVersion",
          "releaseVersion",
          "fillGaps",
          "page",
          "perPage"
        ],
        "type": "object"
      },
      "currentPage": {
        "description": "Page number requested — past totalPages when the request ran off the end.",
        "type": "number"
      },
      "error": {
        "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. `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.",
                "examples": [
                  "country_not_found",
                  "invalid_parameter",
                  "ppp_version_unavailable",
                  "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"
      },
      "estimates": {
        "description": "Poverty and inequality estimates for this page, ordered by country, year, reporting level, then welfare type.",
        "items": {
          "additionalProperties": false,
          "description": "One country × year × reporting-level × welfare-type estimate.",
          "properties": {
            "comparableSpell": {
              "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"
              ]
            },
            "countryCode": {
              "description": "ISO3 country code.",
              "type": "string"
            },
            "countryName": {
              "description": "Economy name.",
              "type": "string"
            },
            "decileShares": {
              "anyOf": [
                {
                  "items": {
                    "type": "number"
                  },
                  "maxItems": 10,
                  "minItems": 10,
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Share of total income or consumption held by each decile, poorest first, summing to 1. Null on gap-filled rows."
            },
            "estimationType": {
              "description": "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.",
              "type": "string"
            },
            "gini": {
              "description": "Gini coefficient of the welfare distribution, 0 (perfect equality) to 1. Null on gap-filled rows — see estimationType.",
              "type": [
                "number",
                "null"
              ]
            },
            "headcount": {
              "description": "Share of the population below the poverty line, as a fraction (0.0814 = 8.14%).",
              "type": [
                "number",
                "null"
              ]
            },
            "isInterpolated": {
              "description": "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.",
              "type": "boolean"
            },
            "mean": {
              "description": "Mean daily welfare per person in PPP dollars.",
              "type": [
                "number",
                "null"
              ]
            },
            "median": {
              "description": "Median daily welfare per person in PPP dollars.",
              "type": [
                "number",
                "null"
              ]
            },
            "mld": {
              "description": "Mean log deviation, an inequality measure. Null on gap-filled rows.",
              "type": [
                "number",
                "null"
              ]
            },
            "polarization": {
              "description": "Wolfson polarization index. Null on gap-filled rows.",
              "type": [
                "number",
                "null"
              ]
            },
            "population": {
              "description": "Population the estimate covers — multiply by headcount for the number of people below the line.",
              "type": [
                "number",
                "null"
              ]
            },
            "povertyGap": {
              "description": "Mean shortfall below the poverty line across the whole population, as a fraction of the line — depth of poverty, not just its incidence.",
              "type": [
                "number",
                "null"
              ]
            },
            "povertyLine": {
              "description": "Poverty line the poverty measures were computed at, in PPP dollars per person per day, as applied upstream.",
              "type": "number"
            },
            "povertySeverity": {
              "description": "Squared poverty gap, weighting the poorest most heavily — inequality among those below the line.",
              "type": [
                "number",
                "null"
              ]
            },
            "regionCode": {
              "description": "PIP region code (e.g. SAS, NAC, SSA).",
              "type": "string"
            },
            "regionName": {
              "description": "PIP region name.",
              "type": "string"
            },
            "reportingLevel": {
              "description": "Coverage of this estimate: national, urban, or rural.",
              "type": "string"
            },
            "reportingYear": {
              "description": "Calendar year the estimate reports on.",
              "type": "number"
            },
            "surveyAcronym": {
              "description": "Short name of the underlying survey (empty on gap-filled rows and where PIP publishes none).",
              "type": "string"
            },
            "surveyComparability": {
              "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"
              ]
            },
            "surveyYear": {
              "description": "Year of the survey behind the estimate, fractional when the survey spans a fiscal year (2022.58). Null on gap-filled rows, which trace to no single survey.",
              "type": [
                "number",
                "null"
              ]
            },
            "watts": {
              "description": "Watts index, a distribution-sensitive measure.",
              "type": [
                "number",
                "null"
              ]
            },
            "welfareType": {
              "description": "Whether the underlying survey measures income or consumption. The two are not directly comparable across economies.",
              "type": "string"
            }
          },
          "required": [
            "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"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "notice": {
        "description": "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.",
        "type": "string"
      },
      "totalCount": {
        "description": "Total estimates before pagination.",
        "type": "number"
      },
      "totalPages": {
        "description": "Total number of pages.",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Get World Bank Poverty and Inequality Estimates"
}
```