Skip to main content
Glama

unhcr-refugees-mcp-server

UNHCR durable solutions

unhcr_get_solutions
Read-onlyIdempotent

Get durable solutions per year (1959 to the latest year) by country of origin and/or asylum: refugees who returned home, refugees resettled to a third country, refugees naturalised, and IDPs who returned. The asylum country means something different per column: the country refugees returned from, the country they were resettled to, the country that naturalised them; IDP returns sit on the origin country itself. Null means the figure was not collected for that country and year, not zero.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "unhcr_get_solutions"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoInline rows. Default 25; a larger value returns at most 2000 and says so. Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled.
stageNoStage the full result as a dataframe even when it fits inline, e.g. to join it with another unhcr_get_* result in unhcr_dataframe_query. Where dataframes are unavailable it is ignored, and the notice says so.
asylumNoCountry of asylum — where people sought or hold protection; for returns, the country they returned from — as ISO3 codes (DEU, TUR), case-insensitive, same rules and limit as origin. Omit to sum every asylum country into one row, or set expand to list each.
expandNoList every country, one row each, for a dimension that origin or asylum leaves unfiltered: origin, asylum, or both. Default none, where an unfiltered dimension is summed into one row. Expanding a dimension that origin or asylum already filters is rejected.none
originNoCountry of origin — where people fled from — as ISO3 codes (SYR, AFG), case-insensitive. ISO 3166 alpha-2 codes (SY) are rewritten to ISO3 and echoed in applied_scope. UNHCR's own codes (GFR) are rejected with the ISO3 to pass instead, and country names are rejected: resolve a name with unhcr_list_reference (topic countries, name_contains). Each listed code returns its own rows; codes are never summed together. At most 250 distinct codes, enough to list every country in UNHCR's country list. Omit to sum every origin into one row, or set expand to list each.
sort_byNoOrder of the full result before the inline cut. year (default) orders by year, then origin ISO3, then asylum ISO3; a count field orders largest first, nulls last.year
year_toNoLast year of the window. When omitted, the window runs to the latest published year (latest_year in the result). A year past the latest published year is clamped to it and the clamp is reported.
year_fromNoFirst year of the window. When omitted, the window starts at the dataset's first year. A year before the dataset's first year is clamped to it and the clamp is reported; a window entirely outside the dataset's years is rejected.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit that was applied.
rowsNoInline rows, sorted, up to limit.
errorNoPresent when the call failed. Absent on success.
shownNoRows returned inline.
noticeNoGuidance for this result: empty-result hints, year and limit clamps, where the full set was staged, or how to narrow.
datasetNoPresent when the full result was staged as a dataframe; read its columns with unhcr_dataframe_describe, then query it with unhcr_dataframe_query.
measureNostock: people in a situation on 31 December; flow: events during the year.
completeNoFalse when the server row cap stopped the upstream fetch; the notice says how many upstream rows were fetched and how to narrow.
footnotesNoUNHCR caveats matching rows of the full result, at most 20. Caveats on inline rows come before those only on rows past the cut; within each group, country-specific first, then in the order of the first row each matches.
truncatedNoTrue when rows were cut at limit.
data_notesNoHow to read the counts: stock or flow, rounding, the meaning of null, caveats.
total_rowsNoRows in the full result before the inline cut. When complete is false, the result is built from only the upstream rows fetched before the cap, so rows and summed counts can fall short of the complete result.
attributionNoAttribution UNHCR requires when these figures are reused.
latest_yearNoNewest year this dataset publishes.
applied_scopeNoThe scope actually sent upstream, including clamped years and code rewrites.
footnotes_totalNoCaveats matching the full result, before the cap.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / properties / asylum / anyOf
      Previous value: -[
      -  {
      -    "description": "One code, or several separated by commas or spaces, e.g. \"SYR\" or \"SYR, AFG\".",
      -    "maxLength": 1000,
      -    "type": "string"
      -  },
      -  {
      -    "description": "Codes as a list, e.g. [\"SYR\", \"AFG\"]; at most 50.",
      -    "items": {
      -      "maxLength": 100,
      -      "type": "string"
      -    },
      -    "maxItems": 50,
      -    "type": "array"
      -  }
      -]New value: +[
      +  {
      +    "description": "One code, or several separated by commas or spaces, e.g. \"SYR\" or \"SYR, AFG\".",
      +    "maxLength": 1750,
      +    "type": "string"
      +  },
      +  {
      +    "description": "Codes as a list, e.g. [\"SYR\", \"AFG\"].",
      +    "items": {
      +      "maxLength": 100,
      +      "type": "string"
      +    },
      +    "maxItems": 1000,
      +    "type": "array"
      +  }
      +]
    • changedInput schema / properties / asylum / description
      Previous value: -"Country of asylum — where people sought or hold protection; for returns, the country they returned from — as ISO3 codes (DEU, TUR), case-insensitive, same rules as origin. At most 50 codes. Omit to sum every asylum country into one row, or set expand to list each."New value: +"Country of asylum — where people sought or hold protection; for returns, the country they returned from — as ISO3 codes (DEU, TUR), case-insensitive, same rules and limit as origin. Omit to sum every asylum country into one row, or set expand to list each."
    • changedInput schema / properties / limit / default
      Previous value: -100New value: +25
    • changedInput schema / properties / limit / description
      Previous value: -"Requested inline rows, 1–1000000 (default 100); values above 500 are clamped to 500 with disclosure. Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled."New value: +"Inline rows. Default 25; a larger value returns at most 2000 and says so. Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled."
    • removedInput schema / properties / limit / maximum
      Removed value: -1000000
    • addedInput schema / properties / limit / multipleOf
      Added value: +1
    • changedInput schema / properties / origin / anyOf
      Previous value: -[
      -  {
      -    "description": "One code, or several separated by commas or spaces, e.g. \"SYR\" or \"SYR, AFG\".",
      -    "maxLength": 1000,
      -    "type": "string"
      -  },
      -  {
      -    "description": "Codes as a list, e.g. [\"SYR\", \"AFG\"]; at most 50.",
      -    "items": {
      -      "maxLength": 100,
      -      "type": "string"
      -    },
      -    "maxItems": 50,
      -    "type": "array"
      -  }
      -]New value: +[
      +  {
      +    "description": "One code, or several separated by commas or spaces, e.g. \"SYR\" or \"SYR, AFG\".",
      +    "maxLength": 1750,
      +    "type": "string"
      +  },
      +  {
      +    "description": "Codes as a list, e.g. [\"SYR\", \"AFG\"].",
      +    "items": {
      +      "maxLength": 100,
      +      "type": "string"
      +    },
      +    "maxItems": 1000,
      +    "type": "array"
      +  }
      +]
    • changedInput schema / properties / origin / description
      Previous value: -"Country of origin — where people fled from — as ISO3 codes (SYR, AFG), case-insensitive. ISO 3166 alpha-2 codes (SY) are rewritten to ISO3 and echoed in applied_scope. UNHCR's own codes (GFR) are rejected with the ISO3 to pass instead, and country names are rejected: resolve a name with unhcr_list_reference (topic countries, name_contains). Each listed code returns its own rows; codes are never summed together. At most 50 codes. Omit to sum every origin into one row, or set expand to list each."New value: +"Country of origin — where people fled from — as ISO3 codes (SYR, AFG), case-insensitive. ISO 3166 alpha-2 codes (SY) are rewritten to ISO3 and echoed in applied_scope. UNHCR's own codes (GFR) are rejected with the ISO3 to pass instead, and country names are rejected: resolve a name with unhcr_list_reference (topic countries, name_contains). Each listed code returns its own rows; codes are never summed together. At most 250 distinct codes, enough to list every country in UNHCR's country list. Omit to sum every origin into one row, or set expand to list each."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_country_code`: An origin or asylum value is not an ISO3 code in UNHCR's country list (after ISO2 normalization). `invalid_year_window`: year_from is later than year_to. `year_out_of_coverage`: The whole requested window lies outside the dataset's published years. `conflicting_scope`: expand names a dimension that origin or asylum already filters. `upstream_busy`: This server's UNHCR request queue cannot start the call's requests before its deadline, or UNHCR answered 429. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_country_code`: An origin or asylum value is not an ISO3 code in UNHCR's country list (after ISO2 normalization). `invalid_year_window`: year_from is later than year_to. `year_out_of_coverage`: The whole requested window lies outside the dataset's published years. `conflicting_scope`: expand names a dimension that origin or asylum already filters. `too_many_country_codes`: origin or asylum lists more distinct codes than one filter accepts. `upstream_busy`: This server's UNHCR request queue cannot start the call's requests before its deadline, or UNHCR answered 429. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_country_code",
      -  "invalid_year_window",
      -  "year_out_of_coverage",
      -  "conflicting_scope",
      -  "upstream_busy"
      -]New value: +[
      +  "unknown_country_code",
      +  "invalid_year_window",
      +  "year_out_of_coverage",
      +  "conflicting_scope",
      +  "too_many_country_codes",
      +  "upstream_busy"
      +]
    • changedOutput schema / properties / footnotes / description
      Previous value: -"UNHCR caveats matching rows of the full result, country-specific first; at most 20."New value: +"UNHCR caveats matching rows of the full result, at most 20. Caveats on inline rows come before those only on rows past the cut; within each group, country-specific first, then in the order of the first row each matches."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance for this result: empty-result hints, year clamps, where the full set was staged, or how to narrow."New value: +"Guidance for this result: empty-result hints, year and limit clamps, where the full set was staged, or how to narrow."
  2. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Rows returned inline, 1–500 (default 100). Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled."New value: +"Requested inline rows, 1–1000000 (default 100); values above 500 are clamped to 500 with disclosure. Sorting runs over the full result first; a larger result is staged as a dataframe where dataframes are enabled."
    • changedInput schema / properties / limit / maximum
      Previous value: -500New value: +1000000
  3. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds essential semantics beyond that: asylum country changes meaning per column, IDP returns map to the origin country, and null means not collected rather than zero.

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?

Three tight sentences, front-loaded with the purpose and then two high-value semantic caveats. There is no redundant restatement of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, annotations, and an output schema, the description supplies the key non-obvious semantics needed to interpret results correctly. It leaves routing versus sibling datasets implicit, which is a minor completeness gap.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds interpretive meaning for origin/asylum dimensions and null values that goes beyond the schema text, even though it does not restate limit/stage/sort details.

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?

States a specific verb and resource: 'Get durable solutions per year' with the four solution categories and year coverage. The distinctive dataset and listed components let an agent distinguish it from population/demographics/asylum siblings even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides implied usage through 'by country of origin and/or asylum' and the listed categories, but gives no explicit when-to-use/when-not or alternatives among the unhcr_get_* tools. An agent can infer it is for durable-solutions queries, but routing is not spelled out.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.