curl.
Walk through a real question
Connect, ask broadly, drill down, check the citations — one question end to end.
How the tools are organised
There is no singletool_list. Tools are grouped into categories, and each category exposes its
own three-tool trio:
gdelt_cloud_tool_list / _tool_get / _tool_call, the
vessel tools through maritime_tool_*, and so on.
Start from the user’s intent and the smallest useful workflow. Use gdelt_cloud for Events,
Stories, unified identities, countries, Situations and Monitors. Prefer unified identities and
facilities for cross-source identity and physical sites; use energy, filings, gleif, macro
and other specialists when their deeper source records answer the question.
gdelt_cloud_tool_list accepts an optional section: news, identity, countries,
situations, or monitors. Omit it for the complete core catalog. Energy owners are discovered
and called through energy_tool_*, like the rest of the energy catalog.
Mutations use gdelt_cloud_tool_write. A read or Monitor preview never saves a subscription.
This is progressive discovery, and it exists for a specific reason: there are far more underlying
tools than any model should carry in its context, and their value lists alone run past a thousand
entries. Advertising three tools per category instead means a model fetches one schema, on demand,
for the one tool it is about to use.
_tool_get before the first _tool_call to a tool you have not used
in this conversation. Guessing a parameter name is the most common failure mode, and the server
rejects unknown filters rather than silently ignoring them — which is the right behaviour, but only
helps if you read the error.
Every category and every tool
The full surface, generated from the same declaration the docs and the API reference share.
Results in chat and in code
Execution wrappers acceptresponse_mode="compact" (default) or "full". Compact keeps record
identifiers, returned links, selected imagery, evidence, filters, pagination and coverage; any
shortening is disclosed. Registry coverage keeps publication and completeness decisions, every
source identity and its limits, and exact served/missing dates. Repeated build and adjudication
audit reports are omitted with an omitted_registry_audit_reports count. Full preserves the
bounded API response, including those audit reports. Neither mode fetches extra pages.
Use returned GDELT Cloud Event, Story, Situation, entity and facility links for product records.
Original publisher links support underlying reporting; registry facts retain their dataset attribution.
A missing image or link is not a reason to invent one. Partial coverage is not a zero result.
Research results belong in native chat: linked titles, selected returned images, compact comparison tables and client-native charts where supported. Favor category/subcategory and the four core Event metrics; magnitude is category-relative and the other three scores are not forecast probabilities. Font, color, icons and image size are controlled by the client. Missing images leave a complete text answer. Maps, when supported by the client, must use returned coordinates and precision rather than place/business listings.
App blocks are reserved for account navigation and Monitor workflows. gdelt_cloud_monitor_form opens an editable setup form using the parameters discovered for preview_monitor. It previews the actual scope through the same authenticated API; it never saves or sends by itself. Ordinary read-wrapper previews remain native chat. Only account help and the editable Monitor form use app components; exact rendering depends on the client.
To propose a Monitor, preview the actual scope, review the matches and coverage, then confirm saving
paused or starting scheduled checks. Delivery can use email, webhook, or both, subject to the API’s
validation and plan access. Preview sends no notification and creates no Monitor. Website signup and sign-in happen during the OAuth/account journey. Account help provides sign-in and connection documentation; the MCP does not promote subscriptions or initiate purchases.
Connecting supplies a concise overview of every data group, record types, Event taxonomy and metrics. For deeper relationships and analytical guidance, read the free resource gdelt://guides/connection-orientation or request gdelt_research_system_prompt. Both return the same detailed guide. Exact schemas and specialist workflows remain available on demand; a simple lookup does not require loading the whole guide.
Guidance on demand
Initialization instructions establish intent, structured-data selection and evidence handling. The compatible research prompt points to shared skills and resources instead of repeating a long manual. Ask a concrete question; your agent should discover the relevant schema and workflow, then ask a focused follow-up only when it changes the scope or next action.Facilities, minerals and AI compute
Find U.S. mineral facilities, inspect GEM overlap, read country reserves and follow participant identities through REST and MCP.
What is metered
A_tool_call costs the same as the REST call it makes and appears in the same usage reporting.
_tool_list and _tool_get are discovery and are not metered. An endpoint your entitlement does not
include returns an error naming what it needs — never an empty result, which would be
indistinguishable from missing data.
Beyond GDELT Cloud data
Web research is optional support for a GDELT Cloud task: initial orientation, corroboration, or reading a relevant source page. It must not replace missing structured evidence or serve as a standalone web-search proxy. Prediction-market tools provide separately attributed market context. Those are vendor contracts rather than our data, and they are described in External tools.Integrations
Claude, Claude Code, ChatGPT, Codex, LangChain.
Plugins
Claude Code, Codex and Cursor: both servers and eight skills, in one command.
Skills
Packaged workflows the server can load on demand.