gdelt-mcp-server

Search GDELT GKG Themes

gdelt_search_themes

Read-only

Find GDELT Global Knowledge Graph (GKG) theme identifiers for the theme: operator that gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown accept in query. Searches the identifiers in the GDELT GKG theme lookup, which carries no labels or descriptions: every query word must begin one of the _-separated parts of an identifier or run across consecutive parts, or all the words joined must, so "drought" finds NATURAL_DISASTER_DROUGHT, "cyberattack" finds CYBER_ATTACK, "plant disease" finds TAX_PLANTDISEASE, and "wb water" narrows to World Bank water themes. There is no stemming or synonym matching — "displacement" does not reach DISPLACED — except one fallback: when nothing matches, the search retries once with a trailing s dropped from each word of four or more letters, and says so. Matches rank an exact identifier first, then by the count the lookup lists — a static prevalence figure, not a live article total — and each carries a paste-ready operator such as theme:TAX_DISEASE_OUTBREAK. Page with offset and limit (up to 100 matches per page; a larger limit runs at 100).

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum matches returned in this response (1–100; a value up to 1000 runs at 100, and the response says so in limitClamp).
`query`	Yes	Words to find in theme identifiers (e.g. "drought", "cyber attack", "refugee"), a family prefix with a word ("wb water", "crisislex"), or a whole identifier to confirm it is listed ("TAX_DISEASE_OUTBREAK"). Case-insensitive; a leading theme: is ignored; every word must match, or all the words joined must ("plant disease" matches TAX_PLANTDISEASE). Must contain at least one letter or digit.
`offset`	No	Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Maximum matches this page holds — the requested limit, or 100 when a larger one was clamped.
`notice`	No	Search outcome: that the plural fallback supplied the matches and which words it tried, or, when nothing matched, how to retry. Absent when the query as given matched.
`offset`	No	Zero-based offset of this page.
`matches`	No	Matches on this page: an exact identifier match first, then by count descending, then by identifier.
`limitClamp`	No	Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value.
`nextOffset`	No	Offset for the next page with the same query. Absent when this is the final page.
`totalCount`	No	Total themes matching the query — the same figure as totalMatches.
`totalMatches`	No	Total themes matching the query, across all pages.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 14, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum matches returned in this response (1–100)."New value: +"Maximum matches returned in this response (1–100; a value up to 1000 runs at 100, and the response says so in limitClamp)."

changedInput schema / properties / limit / maximum
```
Previous value: -100New value: +1000
```

changedOutput schema / properties / limit / description

Previous value: -"Maximum matches requested for this page."New value: +"Maximum matches this page holds — the requested limit, or 100 when a larger one was clamped."

addedOutput schema / properties / limitClamp

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value.",
+  "properties": {
+    "applied": {
+      "description": "The per-call cap the call ran with instead.",
+      "type": "number"
+    },
+    "parameter": {
+      "description": "The count input that was clamped.",
+      "enum": [
+        "maxRecords",
+        "limit"
+      ],
+      "type": "string"
+    },
+    "requested": {
+      "description": "The value the call asked for.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "parameter",
+    "requested",
+    "applied"
+  ],
+  "type": "object"
+}

AddedSep 24, 2026

TDQS

A4.4/5.0

Behavior5/5

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

With only readOnlyHint/openWorldHint annotations, the description carries the behavioral burden and does so richly: the lookup has no labels or descriptions, matching requires words to begin an identifier part or span consecutive parts, there is no stemming or synonym matching except a single trailing-s fallback that is self-reported, ranking is exact-first then by a static prevalence count (explicitly not a live article total), and output is a paste-ready operator. Pagination and the 100-cap clamp are also disclosed.

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?

One dense paragraph, front-loaded with the purpose and consumer tools, then matching rules, ranking, and paging in a sensible order. Nearly every sentence adds substance, but the limit/offset restatement near the end duplicates the schema and adds length without new information.

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?

An output schema exists, so return values need no prose, and the description still covers the non-obvious contract points an agent needs: case-insensitivity, leading theme: being ignored, the joined-words match rule, the fallback, ranking rationale, and page sizing. Nothing material is left for the agent to guess.

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 description coverage is 100% and the schema already documents limit clamping (1–100, larger runs at 100) and offset paging via nextOffset. The description largely restates those facts ('up to 100 matches per page; a larger limit runs at 100'), adding only marginally more than the structured fields. Baseline 3 is appropriate.

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 ('Find GDELT GKG theme identifiers') and immediately ties it to the concrete output consumers: the theme: operator accepted by gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown. This distinguishes it cleanly from every sibling, which consume these identifiers rather than produce them.

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 clearly frames the use case — resolve a theme: operator before calling the four named search/aggregation siblings — and explains the retrieval contract in detail. What's missing is explicit when-not guidance (e.g. what to do if no match is found, or whether to skip this and query articles directly), so it's strong context without exclusions.

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

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