Skip to main content

​
The server does not expose one tool per endpoint

There are 115 tools. Advertising them all would spend a large part of a model’s context describing an API before it has been asked anything, and the value lists alone run past a thousand entries. So each category exposes three thin tools instead — 45 in total — and the model walks down only the branch it needs: {category} is the category name from the table below — so the events tools are reached with gdelt_cloud_tool_list, gdelt_cloud_tool_get and gdelt_cloud_tool_call, and the maritime ones with maritime_tool_list and so on. Every dispatcher call keeps the nested tool inputs inside tool_arguments:
The trio is per category, not global. There is no single tool_list. Picking the category is the first decision, which is why each one below says when to reach for it.
The practical consequence for a model: fetch the schema with _tool_get before the first call to a tool it has not used in this conversation. Guessing a parameter name is the single most common failure, and the server rejects unknown filters rather than ignoring them.

​
Core sections and response modes

gdelt_cloud_tool_list(section="identity") filters discovery; omit section for the whole catalog. Sections:
  • news: Events, Stories and summaries. Related: media_intel for tone and share of voice.
  • identity: Unified identities and dossiers. Related: filings, energy and GLEIF for native source records; facilities for sites.
  • countries: Country context and geography. Related: macro for native economic series.
  • situations: Persistent topic research and linked evidence; creation changes state.
  • monitors: Preview or manage saved monitoring; delivery and mutations use the write wrapper.
The schema returned by _tool_get describes the underlying API payload. Current Horizon tools can also return a presentation envelope; preserve returned identifiers, source coverage, filters and pagination when processing results. A displayed sample is not a complete inventory. Use each advertised wrapper schema for its supported arguments. Mutations use gdelt_cloud_tool_write, separately from the read-only trio. Account navigation and resource/prompt compatibility tools are advertised in addition to the category wrappers. Web research is supporting only: orientation, corroboration or source-page extraction for a GDELT Cloud task, with required purpose and task_context. Basic depth only, five search results or three extraction URLs maximum. Use at most two searches and one extraction batch per task; standalone web research is outside this MCP’s purpose.

​
Categories

​
GDELT Cloud

gdelt_cloud · Core Structured GDELT Cloud events and real-world dynamics — what happened, who did it, where, how often. Clustered stories, Situations, country context, publication activity and Monitors. For any named person, organization, place or facility, resolve first with unified_entity_search (country_match=strict), inspect the candidates, then call the destination tool with the selected id. Cite public GDELT Cloud Story/Entity URLs when returned; never fabricate URLs. Parameters and value lists are the endpoint’s own: see Events · Stories · Situations · Entities · Unified Search · Geography · Monitors · Atlas Intelligence in the API reference, or fetch them at call time with gdelt_cloud_tool_get.

​
Media Intelligence

media_intel · Core How an entity is covered by the press — tone over time and share of voice against a peer set. Plan-gated; preserve the denominator and unavailable coverage. Related: gdelt_cloud for reported Events and Stories. Parameters and value lists are the endpoint’s own: see Media Intelligence in the API reference, or fetch them at call time with media_intel_tool_get.

​
Facilities

facilities · Core The unified physical-asset directory — power plants, mines, mineral processing, factories, ports and data centers, with contributing source observations and resolved participant roles. Read published coverage and geographic evidence; ownership alone does not identify a site. Plan-gated (can_use_facilities). Related: energy and Epoch for native details. Parameters and value lists are the endpoint’s own: see Facilities in the API reference, or fetch them at call time with facilities_tool_get.

​
Government

gov · Open Feeds US federal awards and foreign-influence registrations, resolved onto the entity spine. Parameters and value lists are the endpoint’s own: see Government in the API reference, or fetch them at call time with gov_tool_get.

​
Political Offices

offices · Open Feeds Public political offices and who held them, with the office start/end dates the publisher states (valid time), resolved onto the entity spine. Actor context for geopolitical analysis, not a PEP or sanctions screen. Reach the holders of an office through office= on the gdelt_cloud event and story tools. Parameters and value lists are the endpoint’s own: see Political Offices in the API reference, or fetch them at call time with offices_tool_get.

​
Filings

filings · Open Feeds SEC EDGAR — the filing index, XBRL financials, and relations extracted from filing text. Parameters and value lists are the endpoint’s own: see Filings in the API reference, or fetch them at call time with filings_tool_get.

​
Legal Entities

gleif · Open Feeds The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships and LEI↔ISIN mappings. Parameters and value lists are the endpoint’s own: see Reference Data in the API reference, or fetch them at call time with gleif_tool_get.

​
Energy

energy · Open Feeds Global Energy Monitor assets and the ownership registry over them. Parameters and value lists are the endpoint’s own: see Energy in the API reference, or fetch them at call time with energy_tool_get.

​
AI Compute

epoch · Open Feeds Epoch AI — models, hardware, data centers, companies, chip sales and selected GPU-cluster and chip ownership/use/component observations. Preserve participant roles, native units and uncertainty. CC-BY 4.0; plan-gated. Related: facilities for unified sites; gdelt_cloud for linked entity context. Parameters and value lists are the endpoint’s own: see AI Compute in the API reference, or fetch them at call time with epoch_tool_get.

​
Natural Resources

resources · Open Feeds USGS mineral production, reserves and qualified observations by commodity, source, reference year and shared country/region/continent filters. Request full-filter count facets with include_summary; individual values keep their native units and qualifiers. Parameters and value lists are the endpoint’s own: see Natural Resources in the API reference, or fetch them at call time with resources_tool_get.

​
Macro Finance

macro · Open Feeds FRED economic series, with true point-in-time vintages rather than the latest revision. Parameters and value lists are the endpoint’s own: see Macro Finance in the API reference, or fetch them at call time with macro_tool_get.

​
Risk and Screening

risk · Open Feeds Restricted-party lists, name screening, ownership-chain exposure and China development finance. Discover currently ingested original-publisher sources, including our OpenSanctions-derived crawler lane, with lists_catalog before selecting a source_key. List categories distinguish sanctions from debarment and other screening signals. Analytical coverage, not an audit-grade compliance control. Parameters and value lists are the endpoint’s own: see Screening and Reference · China in the API reference, or fetch them at call time with risk_tool_get.

​
Maritime

maritime · Open Feeds AIS-derived vessel flow — chokepoint transits, port dwell, dark gaps and last-known offices. Terrestrial AIS only, so coverage thins in open ocean. Parameters and value lists are the endpoint’s own: see Maritime in the API reference, or fetch them at call time with maritime_tool_get.

​
Prediction Markets

prediction_market · Vendor Kalshi contracts, read as a market-implied probability rather than a fact. A vendor surface reached through the same protocol — not GDELT Cloud data.

​
Web Research

web_research · Vendor Supporting web research only: orientation for GDELT Cloud tasks, corroboration or source extraction. Requires purpose and task_context. Basic depth; five results or three URLs maximum. At most two searches and one extraction batch per task. Standalone web research is unsupported.

​
Monitor workflow

Monitors live in the gdelt_cloud category. Fetch each nested schema before its first use, then call the progressive dispatcher with the nested parameters in tool_arguments:
gdelt_cloud_tool_call is READ-ONLY and cannot change anything. Everything that creates, updates, pauses, deletes, persists a run, or sends delivery runs through a separate dispatcher, gdelt_cloud_tool_write, which reaches exactly eight tools: create_monitor, update_monitor, delete_monitor, set_monitor_enabled, configure_monitor_delivery, test_monitor_delivery, batch_monitors, run_monitor_now.
If you are writing a host approval policy, gate gdelt_cloud_tool_write. Gating gdelt_cloud_tool_call stops no mutation — the server refuses write tools there by name — while leaving gdelt_cloud_tool_write ungated permits every state change the integration can make.
Follow the same canonical contract as REST:
  1. Resolve an entity name with unified_entity_search, and present ambiguous candidates instead of guessing.
  2. Call preview_monitor; an accepted Preview costs 1 QU, saves nothing, and sends no delivery.
  3. Read the representative rows. Entity coverage is mention/link evidence, not material involvement or actor attribution.
  4. Call create_monitor only after the subject and rows are acceptable. Scheduled checks cost 0 QU.
  5. Use update_monitor for any canonical partial update, set_monitor_enabled for pause/resume, or batch_monitors to enable, disable, or permanently delete up to 100 ids.
  6. Use configure_monitor_delivery to set/remove a webhook or rotate its secret, and test_monitor_delivery to send a test event. The signing secret appears only on initial webhook configuration or explicit rotation; save it then because later reads never return it.
  7. Use run_monitor_now to persist an immediate test run for 1 QU without sending delivery, advancing match state, or changing the schedule. Inspect retained runs with list_monitor_runs, get_monitor_run, and get_monitor_run_matches.
For exact replay, take every returned replay_request, choose search_events or search_stories from its endpoint, and pass its day-bounded REST parameters through that nested tool’s discovered schema. Follow pagination.next_cursor to exhaustion, then retain only rows whose exact_window_filter.field timestamp is greater than or equal to start_inclusive and strictly less than end_exclusive. The day-bounded request alone is deliberately wider than the exact half-open scheduler window. Preserve every returned entity, taxonomy, geography, semantic, and deduplication parameter; union multi-entity requests and deduplicate canonical ids. preview_monitor and create_monitor compile the same public Monitor body. sample_count and run result_count are execution counts, while the returned rows are bounded samples. When count_truncated / total_matches_is_lower_bound is true, the semantic count reached the reported candidate_limit and is a lower bound rather than an exhaustive corpus total. Multi-entity replay returns one request per entity and endpoint; union and deduplicate canonical ids. See Monitors and Monitor webhooks.

​
What is metered

A _tool_call costs the same as the REST call it makes, against the same plan limits, 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. Scheduled Monitor checks are the exception to ordinary endpoint metering: they cost 0 QU; each accepted preview_monitor execution costs 1 QU.