reliefweb-mcp-server

Search ReliefWeb Reports

reliefweb_search_reports

Read-onlyIdempotent

Search humanitarian reports on ReliefWeb with filtering by country, disaster, format, theme, language, source, and date. Returns paginated summaries — use reliefweb_get_report to fetch full body text. Report body is excluded from results (10–100KB each); call get_report when document content is needed. Every report is reachable by default — reports have no archived class, so include_archived has no effect here. Note: each call counts against the 1,000 calls/day quota.

Input Schema

TableJSON Schema

Name	Required	Description
`sort`	No	Sort order. Use date.original:desc for newest first (default), date.original:asc for oldest first, score:desc for relevance.
`text`	No	Full-text search query. Matches against title, body, and key metadata fields. Use plain natural language or keywords.
`limit`	No	Number of results to return (1–1000, default 10). Use a smaller value for targeted lookups; larger for bulk research. Each call counts against the 1,000-calls/day quota.
`theme`	No	Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Shelter and Non-Food Items, Protection). Open-ended — matches theme.name exactly as ReliefWeb spells it.
`filter`	No	Raw ReliefWeb filter object for compound conditions not covered by named params. Example: {"operator": "AND", "conditions": [{"field": "format.name", "value": "Map"}, {"field": "language.code", "value": "fr"}]}.
`format`	No	Content format filter. One of: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned. Case, spacing, and punctuation are ignored; any other value is rejected with the valid list.
`offset`	No	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through large result sets.
`source`	No	Organization short name (e.g., UNHCR, OCHA, WFP). Filters on source.shortname.
`country`	No	ISO 3166-1 alpha-3 country code (e.g., SYR, AFG, UKR). Filters to content tagged with this country.
`date_to`	No	Latest publication date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC.
`language`	No	ISO 639-1 language code (e.g., en, fr, es, ar). Filters on language.code.
`date_from`	No	Earliest publication date. Filters on date.original (source publication date). A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC.
`disaster_id`	No	ReliefWeb numeric disaster ID. Filters to reports linked to a specific disaster. Get the ID from reliefweb_search_disasters.
`include_archived`	No	No effect on reports. Reports have no archived class — every report is already in scope, whatever this is set to. Kept so existing calls that pass it keep working; it is meaningful on reliefweb_search_jobs, reliefweb_search_training, and reliefweb_search_disasters.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`items`	No	Matching reports (summaries only — use reliefweb_get_report for full body).
`notice`	No	Present only when the page is empty. Names the match count and the last reachable offset when the query matched records; otherwise echoes the filters applied and suggests how to broaden.
`totalCount`	No	Total reports matching the query before pagination.
`appliedFilters`	No	The resolved filter set the query actually ran with, after normalization and defaults. Echoes back so the agent can confirm how its inputs were interpreted.

Schema Changelog

Changes observed during successful MCP inspections.

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": [
+      "items",
+      "appliedFilters",
+      "totalCount"
+    ]
+  },
+  {
+    "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: `unknown_format`: The format value does not name a ReliefWeb report format. `invalid_query`: ReliefWeb rejected the query — an unrecognized sort field, an invalid raw filter object, or a malformed date. `upstream_error`: The ReliefWeb API was unreachable, timed out, or returned a server error. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_format",
+            "invalid_query",
+            "upstream_error"
+          ],
+          "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: -[
-  "items",
-  "appliedFilters",
-  "totalCount"
-]

Changed5 schema fields changedAug 7, 2026

changedInput schema / properties / format / description

Previous value: -"Content format filter. Valid values: Situation Report, Assessment, Analysis, Map, Infographic, Manual and Guideline, News and Press Release, Policy Document, Appeal, Financial Report, Evaluation and Lessons Learned, Other."New value: +"Content format filter. One of: News and Press Release, Situation Report, Map, Infographic, Analysis, Other, Assessment, Manual and Guideline, Appeal, UN Document, Evaluation and Lessons Learned. Case, spacing, and punctuation are ignored; any other value is rejected with the valid list."

changedInput schema / properties / include_archived / description

Previous value: -"Include archived and to-review content in addition to published. Uses preset=analysis. Off by default."New value: +"No effect on reports. Reports have no archived class — every report is already in scope, whatever this is set to. Kept so existing calls that pass it keep working; it is meaningful on reliefweb_search_jobs, reliefweb_search_training, and reliefweb_search_disasters."

changedInput schema / properties / theme / description

Previous value: -"Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Shelter and NFI, Protection). Matches theme.name."New value: +"Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Shelter and Non-Food Items, Protection). Open-ended — matches theme.name exactly as ReliefWeb spells it."

changedOutput schema / properties / appliedFilters / properties / format / description

Previous value: -"Format name filter applied."New value: +"Format name filter applied, in its canonical ReliefWeb spelling."

changedOutput schema / properties / appliedFilters / properties / preset / description

Previous value: -"ReliefWeb preset the query used: latest (default) or analysis when include_archived."New value: +"ReliefWeb preset the query used. Always latest for reports — no preset changes which reports match."

Changed7 schema fields changedAug 7, 2026

addedInput schema / properties / date_from / anyOf

Added value: +[
+  {
+    "const": "",
+    "type": "string"
+  },
+  {
+    "description": "Calendar date (2024-01-15) or full ISO 8601 datetime (2024-01-15T00:00:00+00:00).",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
+    "type": "string"
+  }
+]

changedInput schema / properties / date_from / description

Previous value: -"Earliest publication date (ISO 8601, e.g., 2024-01-15T00:00:00+00:00). Filters on date.original (source publication date)."New value: +"Earliest publication date. Filters on date.original (source publication date). A bare calendar date such as 2024-01-15 is accepted and resolves to start of that day in UTC; a datetime carrying any offset is resolved to UTC."

removedInput schema / properties / date_from / type
```
Removed value: -"string"
```

addedInput schema / properties / date_to / anyOf

Added value: +[
+  {
+    "const": "",
+    "type": "string"
+  },
+  {
+    "description": "Calendar date (2024-01-31) or full ISO 8601 datetime (2024-01-31T23:59:59+00:00).",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})?)?$",
+    "type": "string"
+  }
+]

changedInput schema / properties / date_to / description

Previous value: -"Latest publication date (ISO 8601). Pair with date_from for a date range."New value: +"Latest publication date. Pair with date_from for a date range. A bare calendar date resolves to end of that day in UTC, so the range covers it in full; a datetime carrying any offset is resolved to UTC."

removedInput schema / properties / date_to / type
```
Removed value: -"string"
```

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when results are empty — echoes the filters applied and suggests how to broaden. Absent on successful result pages."New value: +"Present only when the page is empty. Names the match count and the last reachable offset when the query matched records; otherwise echoes the filters applied and suggests how to broaden."

Changed2 schema fields changedJun 16, 2026

addedOutput schema / properties / appliedFilters

Added value: +{
+  "additionalProperties": false,
+  "description": "The resolved filter set the query actually ran with, after normalization and defaults. Echoes back so the agent can confirm how its inputs were interpreted.",
+  "properties": {
+    "country": {
+      "description": "Country code as normalized (uppercased ISO3).",
+      "type": "string"
+    },
+    "dateFrom": {
+      "description": "Earliest publication date filter applied.",
+      "type": "string"
+    },
+    "dateTo": {
+      "description": "Latest publication date filter applied.",
+      "type": "string"
+    },
+    "disasterId": {
+      "description": "Disaster ID filter applied.",
+      "type": "number"
+    },
+    "format": {
+      "description": "Format name filter applied.",
+      "type": "string"
+    },
+    "language": {
+      "description": "Language code filter applied.",
+      "type": "string"
+    },
+    "limit": {
+      "description": "Result limit the query used.",
+      "type": "number"
+    },
+    "offset": {
+      "description": "Pagination offset the query used.",
+      "type": "number"
+    },
+    "preset": {
+      "description": "ReliefWeb preset the query used: latest (default) or analysis when include_archived.",
+      "type": "string"
+    },
+    "rawFilter": {
+      "description": "True when a raw compound filter object was merged into the query.",
+      "type": "boolean"
+    },
+    "sort": {
+      "description": "Sort order the query used (resolved, including the default).",
+      "type": "string"
+    },
+    "source": {
+      "description": "Source short name filter applied.",
+      "type": "string"
+    },
+    "text": {
+      "description": "Full-text query the search used.",
+      "type": "string"
+    },
+    "theme": {
+      "description": "Theme name filter applied.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "sort",
+    "preset",
+    "limit",
+    "offset"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "items",
-  "totalCount"
-]New value: +[
+  "items",
+  "appliedFilters",
+  "totalCount"
+]

Changed3 schema fields changedMay 30, 2026

changedInput schema / properties / offset / description

Previous value: -"Zero-based offset for pagination. Use with limit and totalCount from the response to page through large result sets."New value: +"Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through large result sets."

removedOutput schema / properties / message

Removed value: -{
-  "description": "Recovery hint when results are empty — echoes the filters applied and suggests how to broaden. Absent on successful result pages.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when results are empty — echoes the filters applied and suggests how to broaden. Absent on successful result pages.",
+  "type": "string"
+}

First observedMay 29, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it notes that report bodies are excluded from results (with size estimates), that include_archived has no effect on reports, and that each call counts against a 1,000/day quota. This gives the agent important operational constraints not evident from annotations.

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?

The description is concise given the tool's complexity (14 parameters, many with nuanced behavior). It front-loads the core purpose and quickly notes the key limitation (no body text, use get_report). Every sentence serves a purpose—mentioning pagination, quota, and include_archived behavior. It's structured logically but could be slightly tightened to avoid repeating 'each call counts' twice, though that repetition reinforces an important constraint.

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?

This is a complex tool with 14 parameters, nested objects, and an output schema. The description covers the essential operational details: what the tool returns (paginated summaries without body text), when to use the sibling get_report, the archiving caveat, the quota impact, and how to page. The output schema likely describes the response structure, so the description doesn't need to enumerate return fields. It's complete for an agent to correctly invoke it.

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

Parameters3/5

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

Schema coverage is 100% and every parameter has a description. The description adds modest extra value beyond the schema—for instance, it explains that the text parameter matches against title, body, and metadata, and it clarifies the behavior of date_from/date_to with timezone resolution. However, most parameter details are already in the schema, so the baseline of 3 is appropriate; the description doesn't significantly elevate parameter understanding beyond what's in the schema.

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 description clearly states the tool searches humanitarian reports with specific filters (country, disaster, format, theme, language, source, date) and returns paginated summaries. It distinguishes itself from sibling tools by explicitly mentioning reliefweb_get_report for full body text, which separates search from retrieval.

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?

It provides solid guidance on when to use this tool versus reliefweb_get_report (when full body is needed) and explains that include_archived has no effect on reports, directing users to sibling tools where it is meaningful. However, it doesn't explicitly state when to prefer this over reliefweb_search_disasters or other search tools, though the 'search reports' focus implicitly covers it.

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

All reliefweb-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.