unhcr-refugees-mcp-server

UNHCR asylum decisions

unhcr_get_asylum_decisions

Read-onlyIdempotent

Get asylum decisions per year (2000 to the latest year) by country of origin and/or asylum: recognized as refugees, complementary protection, rejected, and otherwise closed, with UNHCR's Refugee Recognition Rate and Total Protection Rate computed over substantive decisions (otherwise-closed cases excluded). By default all decision levels are summed and each row lists the levels it includes; appeal-stage decisions can concern people already decided at first instance, so split_by decision_level or filter decision_levels to FI for first-instance rates. Cases and persons are never added together.

Input Schema

Name	Required	Description	Default
`limit`	No	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.
`stage`	No	Stage 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.
`asylum`	No	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.
`expand`	No	List 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
`origin`	No	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.
`sort_by`	No	Order 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. Rates are not sortable, since rates on small rounded counts would crowd the top.	year
`year_to`	No	Last 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.
`split_by`	No	Procedure dimensions kept as separate rows: authority (government, UNHCR, or joint) and decision_level (first instance, administrative review, …). Every dimension left out is summed. Default [] sums all authorities and levels, as UNHCR does for its rates. Unit is always kept separate.
`year_from`	No	First 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.
`decision_levels`	No	Keep only these decision levels before summing, case-insensitive: NA new applications, FI first instance, AR administrative review, RA repeat/reopened, IN US Citizenship and Immigration Services, EO US Executive Office for Immigration Review, JR judicial review, SP subsidiary protection, FA first instance and appeal, TP temporary protection, TA temporary asylum, BL backlog, TR temporary leave to remain, CA cantonal regulations (Switzerland). ["FI"] gives first-instance decisions. Omit for every level.

Output Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`rows`	No	Inline rows, sorted, up to limit.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows returned inline.
`notice`	No	Guidance for this result: empty-result hints, year clamps, where the full set was staged, or how to narrow.
`dataset`	No	Present when the full result was staged as a dataframe; read its columns with unhcr_dataframe_describe, then query it with unhcr_dataframe_query.
`measure`	No	stock: people in a situation on 31 December; flow: events during the year.
`complete`	No	False when the server row cap stopped the upstream fetch; the notice says how many upstream rows were fetched and how to narrow.
`truncated`	No	True when rows were cut at limit.
`data_notes`	No	How to read the counts: stock or flow, rounding, the meaning of null, caveats.
`total_rows`	No	Rows 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.
`attribution`	No	Attribution UNHCR requires when these figures are reused.
`latest_year`	No	Newest year this dataset publishes.
`applied_scope`	No	The scope actually sent upstream, including clamped years and code rewrites.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

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
```

First observedOct 4, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld). The description adds substantive behavioral context beyond them: rates are computed over substantive decisions with otherwise-closed cases excluded, all decision levels are summed by default with each row listing its levels, and cases vs persons are never combined. This materially helps correct interpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the resource and scope, then defaults and the important caveat. Dense but every sentence earns its place; the multi-clause sentences are slightly heavy but not wasteful.

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?

With an output schema present, return values need no explanation. The description supplies the defaults, the rate-computation caveat, and the splitting nuance an agent needs to call this correctly, though pagination/limit behavior is left entirely to the schema.

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, but the description adds meaning the schema does not: the default summing of decision levels, the risk that appeal-stage rows double-count, and the interplay of split_by/decision_levels for first-instance rates. It does not walk through each parameter, but it enriches the most consequential ones.

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 asylum decisions per year ... by country of origin and/or asylum') and enumerates the decision categories returned, plus the derived rates. An agent can tell this apart from siblings like unhcr_get_asylum_applications without opening either schema.

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

Usage Guidelines4/5

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

Gives concrete conditional guidance: use split_by decision_level or filter decision_levels to FI to get first-instance rates, and notes that appeal-stage decisions overlap with first-instance populations. Does not explicitly name sibling tools or exclusions, but the when-to-use context is clear.

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

All unhcr-refugees-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.