Skip to main content

Named tools and optional discovery

The current public MCP exposes 117 named domain operations with direct typed arguments, plus local discovery, resources and account/Monitor helpers. Availability follows the connected account. Use connected tool descriptors for the current public release. Call familiar operations directly; client-native tool search or deferred loading controls which schemas enter context where supported. There is no required wrapper preflight. Optional get_data_catalog explains domains and relationships. get_data_catalog(domain="gdelt_cloud", section="identity") scopes core discovery; omitting section retains the complete core catalog. get_parameter_options returns bounded categorical choices and parent dependencies. get_event_taxonomy explains category/subcategory meanings; keep its default page size and scope to a known category when useful.
unified_entity_search resolves an identity: which entity does this name mean? search_entities discovers actors in reporting within date, geography, taxonomy and co-occurrence filters: who appears in this reporting? Both return compatible entity IDs; a quiet reporting window does not establish that an identity is absent.

Core sections and response modes

  • 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; creation, updates and delivery actions require authorization.
Choose the smallest useful workflow. Reuse a known schema; fetch optional metadata only when a choice is uncertain. Local discovery makes no data query. response_mode="compact" is the default chat projection: identifiers, evidence, returned URLs/images, coverage and filters remain explicit. A compact list page requests only the records it shows, so next_cursor continues after the last record shown; _mcp_projection reports requested_limit and applied_limit when it asked for fewer. response_mode="full" preserves the bounded API response at the requested limit. Neither mode retrieves other pages. A sample does not establish totals or complete coverage. Cite returned GDELT Cloud record links, original publisher evidence and dataset attribution. Missing links/images remain missing. Research uses native chat text, tables and client-supported charts; account navigation and the editable Monitor form are the dedicated app components.

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 (with country_match=strict when you know the country), inspect the candidates, then call the destination tool with the selected id. Cite public GDELT Cloud Story/Entity URLs when returned; never fabricate URLs. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Government

gov · Open Feeds US federal awards and foreign-influence registrations, resolved onto the entity spine. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Filings

filings · Open Feeds SEC EDGAR — the filing index, XBRL financials, and relations extracted from filing text. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options. gleif · Open Feeds The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships and LEI↔ISIN mappings. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Energy

energy · Open Feeds Global Energy Monitor assets and the ownership registry over them. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Macro Finance

macro · Open Feeds FRED economic series, with true point-in-time vintages rather than the latest revision. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Web Research

web_research · Supporting research 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. Use the advertised operation schema for exact inputs and output shapes. Discover unfamiliar choices with get_parameter_options.

Monitor workflow

  1. Resolve a named subject with unified_entity_search; clarify consequential ambiguity.
  2. For an editable review, call gdelt_cloud_monitor_form with validated preview_monitor parameters. Preview saves nothing and sends no delivery.
  3. Review matches, applied filters and coverage. Mention/link evidence is not material involvement or actor attribution.
  4. After explicit confirmation, call create_monitor; paused and running are separate choices.
  5. update_monitor changes settings; set_monitor_enabled pauses/resumes; batch_monitors performs the requested batch action. These are mutations with host approval.
  6. configure_monitor_delivery configures email/webhook delivery; test_monitor_delivery sends a test. Signing secrets belong in secure integration storage, not chat.
  7. run_monitor_now persists a manual test run, sends no notification, and does not advance the scheduled checkpoint. Inspect list_monitor_runs, get_monitor_run and get_monitor_run_matches.
Respect total_matches_is_lower_bound, count_truncated and candidate_limit. Result rows are bounded samples; returned counts are execution counts. Incomplete coverage cannot establish a quiet interval or completed checkpoint. For exact replay, retain each returned replay_request and its documented scope, filters and time basis. A widened day-bounded request alone is not the exact scheduler window. Honor exact_window_filter and pagination.next_cursor; do not invent unsupported recorded-time parameters. See Monitors and Monitor webhooks.

Supporting web research

supporting_web_search and extract_source_pages require purpose and task_context for a GDELT Cloud task. Basic depth only, at most five search results or three extraction URLs. Agent guidance limits a task to two searches and one extraction batch; stop earlier when sufficient. Standalone web research is unsupported.

Usage and access

Data operations use the same account access and usage admission as the underlying API. get_data_catalog, get_parameter_options and get_event_taxonomy are free local metadata. Access failures explain unavailability rather than returning misleading empty data. Monitor and saved-query tools cost what their REST call costs: setup, reads, edits and deletes are free, scheduled checks cost no Query Units, and a Preview or a manual run costs 1 QU when it executes.

Wrapper compatibility profile

Clients explicitly using the legacy wrapper profile discover each domain through these tools. They are not the current public named-tool surface. Authorized mutations use gdelt_cloud_tool_write in that profile. A read wrapper cannot execute mutations. Retired integrations are absent from both profiles.