reliefweb-mcp-server

Search ReliefWeb Jobs

reliefweb_search_jobs

Read-onlyIdempotent

Search humanitarian job listings on ReliefWeb by country, organization, career category, theme, and experience level. Returns current open positions — expired postings are excluded by default. Use include_archived=true to search the full history of postings, which is far larger than the open set. Use text search for role titles and job descriptions.

Input Schema

TableJSON Schema

Name	Required	Description
`sort`	No	Sort order. Use date.created:desc for newest postings first (default), date.closing:asc to surface roles closing soonest, or score:desc for relevance.
`text`	No	Full-text search query. Matches against job title, body, and key metadata fields.
`limit`	No	Number of results to return (1–1000, default 10). Each call counts against the 1,000-calls/day quota.
`theme`	No	Sector or cross-cutting theme (e.g., Health, Food and Nutrition, Protection). Filters on theme.name.
`offset`	No	Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results.
`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 jobs tagged with this country.
`experience`	No	Experience level (e.g., 0-2 years, 3-4 years, 5-9 years). Filters on experience.name.
`career_category`	No	Humanitarian career track (e.g., Programme and Project Management, Information and Communications Technology, Logistics and Telecommunications). Filters on career_categories.name.
`include_archived`	No	Search expired postings alongside the open ones. Uses preset=analysis. Off by default — the open set is a small fraction of the archive, so turn this on for labour-market history rather than for a hiring snapshot.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`items`	No	Matching job listings.
`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 jobs 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: `invalid_query`: ReliefWeb rejected the query — typically an unrecognized sort field. `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": [
+            "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"
-]

Changed3 schema fields changedAug 7, 2026

addedInput schema / properties / include_archived

Added value: +{
+  "description": "Search expired postings alongside the open ones. Uses preset=analysis. Off by default — the open set is a small fraction of the archive, so turn this on for labour-market history rather than for a hiring snapshot.",
+  "type": "boolean"
+}

addedOutput schema / properties / appliedFilters / properties / preset

Added value: +{
+  "description": "ReliefWeb preset the query used: latest (open postings only, default) or analysis when include_archived.",
+  "type": "string"
+}

changedOutput schema / properties / appliedFilters / required

Previous value: -[
-  "sort",
-  "limit",
-  "offset"
-]New value: +[
+  "sort",
+  "preset",
+  "limit",
+  "offset"
+]

Changed1 schema field changedAug 7, 2026

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when results are empty — echoes filters applied and suggests how to broaden."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."

Changed1 schema field changedJul 13, 2026

addedInput schema / properties / sort

Added value: +{
+  "description": "Sort order. Use date.created:desc for newest postings first (default), date.closing:asc to surface roles closing soonest, or score:desc for relevance.",
+  "type": "string"
+}

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": {
+    "careerCategory": {
+      "description": "Career category name filter applied.",
+      "type": "string"
+    },
+    "country": {
+      "description": "Country code as normalized (uppercased ISO3).",
+      "type": "string"
+    },
+    "experience": {
+      "description": "Experience level filter applied.",
+      "type": "string"
+    },
+    "limit": {
+      "description": "Result limit the query used.",
+      "type": "number"
+    },
+    "offset": {
+      "description": "Pagination offset the query used.",
+      "type": "number"
+    },
+    "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",
+    "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 to page through results."New value: +"Zero-based offset for pagination. Use with limit and the totalCount enrichment field to page through results."

removedOutput schema / properties / message

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

addedOutput schema / properties / notice

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

First observedMay 29, 2026

TDQS

A4.5/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 useful behavioral context: expired postings are excluded by default, the archived set is 'far larger', and include_archived uses preset=analysis. These details go beyond annotations and clarify the default scope and the trade-off of turning on archiving.

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?

The description is four succinct sentences, all informative. It front-loads the main purpose and filters, then covers the default behavior, the archived option, and the text search hint. Every sentence earns its place with no filler.

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 search tool with ten well-documented parameters, an output schema, and annotations that cover safety, the description is complete. It resolves the key ambiguity between open and archived postings, provides scaling context, and gives practical usage guidance. Nothing an agent needs to call it correctly is missing.

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 parameters are fully documented. The description adds semantic value for include_archived by explaining its purpose (searching full history) and the scale difference, and for text by stating it matches titles and descriptions. These enrich the schema descriptions without redundancy.

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 verb 'Search' and the resource 'humanitarian job listings on ReliefWeb', identifies the filtering dimensions (country, organization, career category, theme, experience level), and explicitly notes that it returns current open positions with expired postings excluded by default. It distinguishes itself from sibling tools like get_job by implying a search over a set rather than a single record.

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?

Provides clear context for when to enable include_archived (for full history vs. current snapshot) and when to use text search (for role titles and job descriptions). However, it does not explicitly mention alternatives like get_job for fetching a single job by ID, so the routing to siblings is left implicit.

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.