> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # GDELT Cloud v2 MCP Tools > Complete MCP parameter reference for generated Events, Stories, Entities, and geo discovery ## Overview The `gdelt_cloud_*` MCP wrappers expose the public API v2 product catalog: * structured Events: `conflict` and `cameoplus` * clustered Stories with article evidence * Event and Story summaries * Entities linked to Events and Stories * country-scoped `admin1` discovery * **Facilities** — the unified physical-asset directory (`facilities_search`, `facilities_get`, `facilities_by_owner`; plan-gated, Analyst+) * Monitoring **Briefs** — `create_brief`, `list_briefs`, `get_brief` (plan-gated; see [Monitoring Briefs](#monitoring-briefs)) Use plain English country names in examples and user-facing calls. ISO-3 and legacy FIPS aliases are accepted, but normalized outputs use country names. `region` and `continent` expand to ISO-3 country lists on the API backend. Event tools match those countries against Event location plus actor-origin countries. Story tools use the same country-list expansion through linked Event primary location only. Event, Story, and Entity list tools default to the exact past 24 hours. Narrow with geography, category, subcategory, civilian-targeting filters, date windows up to 30 days, and semantic search rather than public confidence modes. `subcategory` requires its parent category. Detail tools (`get_event`, `get_story`, and Story articles) resolve known IDs directly. List and detail tools preserve API-enriched visual context by default: top source-article sharing images, source-domain avatars, and linked Entity thumbnails when available. These fields are for product rendering and analyst orientation; absence of an image is not evidence about the underlying Event, Story, or Entity. ## Wrapper Parameters | Wrapper | Parameter | Required | Description | | ----------------------- | ---------------: | ----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gdelt_cloud_tool_list` | none | no | Lists available GDELT Cloud nested tools. | | `gdelt_cloud_tool_get` | `tool_name` | conditional | Single nested tool name to inspect. | | `gdelt_cloud_tool_get` | `tool_names` | conditional | List of nested tool names to inspect together. | | `gdelt_cloud_tool_get` | `category` | no | Optional Event parent category such as `TECHNOLOGY`, `INFRASTRUCTURE`, `Protests`, or `Battles`; when present, Event/Story/Entity taxonomy tools return only that category's scoped `subcategory` enum. | | `gdelt_cloud_tool_call` | `tool_name` | yes | Exact nested tool name to execute. | | `gdelt_cloud_tool_call` | `tool_arguments` | no | Object containing the selected nested tool's parameters. | ## Shared Date Parameters Range-capable tools accept `start_date`, `end_date`, and `days`. | Parameter | Required | Description | | ------------ | -------: | ----------------------------------------------------------------------------------------------------- | | `start_date` | no | Inclusive start date in `YYYY-MM-DD`. With `end_date`, defines an explicit window of at most 30 days. | | `end_date` | no | Inclusive end date in `YYYY-MM-DD`. Defaults to current UTC date when omitted with `days`. | | `days` | no | Window size from 1 to 30. Used to complete the range when either date is omitted. | Precedence: * `start_date` + `end_date`: use the explicit inclusive range. * `start_date` + `days`: compute `end_date`. * `end_date` + `days`: compute `start_date`. * `days` only: trailing window ending current UTC date. On list tools, the default `days=1` returns the exact past 24 hours. ## `search_events` Use for incident-level structured records: protests, attacks, diplomatic actions, infrastructure projects, economic policy events, and other coded Events. | Parameter | Required | Description | | ------------------------------ | -------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start_date` | no | Inclusive start date, max 30-day window. | | `end_date` | no | Inclusive end date, max 30-day window. | | `days` | no | Window size, 1-30. Default 7. | | `country` | no | Plain English country name; broad location-or-actor-origin matching. | | `region` | no | Plain English region such as `Middle East` or `Western Africa`; expands to an ISO-3 country list and matches Event location plus actor-origin countries. | | `continent` | no | Plain English continent such as `Asia` or `Europe`; expands to an ISO-3 country list and matches Event location plus actor-origin countries. | | `admin1` | no | State/province/admin1 location filter. Discover with `list_admin1`. | | `event_family` | no | Deprecated legacy filter: `conflict` or `cameoplus`. Prefer `category`, which implies the family. | | `category` | no | Single product category enum: a Conflict event type such as `Battles`, `Protests`, or `Explosions/Remote violence`, or a CAMEO+ domain such as `POLITICAL`, `CRIME`, or `INFRASTRUCTURE`. | | `categories` | no | Multi-select product categories. Values are OR'd together and serialized to the API as `category=Battles,CRIME`. | | `subcategory` | no | Specific Event subtype. Requires `category` or `categories`; for Conflict categories, use sub-event types such as `Armed clash`, `Peaceful protest`, or `Air/drone strike`. For CAMEO+ categories, use stable event codes such as `TE01` or `IN03`; older label text is accepted as a compatibility alias. | | `domain` | no | Deprecated legacy CAMEO+ domain filter. Prefer `category` for new integrations. | | `search` | no | Semantic search text; not a keyword-only filter. | | `has_fatalities` | no | Boolean fatality filter. | | `civilian_targeting` | no | Boolean Conflict filter. `true` keeps Events where civilians are coded as the primary target. | | Metric `_min` / `_max` filters | no | Canonical metric ranges: `significance`, `confidence`, `goldstein_scale`, `goldstein_severity`, `magnitude`, `systemic_importance`, `propagation_potential`, `market_sensitivity`. | | `sort` | no | `significance` default, or `recent`. | | `limit` | no | Number of Event cards, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | | `include_images` | no | Keep API-enriched article sharing images, source-domain avatars, and linked Entity thumbnails when available. Default `true`. | ```json theme={null} { "tool_name": "search_events", "tool_arguments": { "category": "INFRASTRUCTURE", "propagation_potential_min": 0.6, "continent": "Asia", "search": "new data center projects", "start_date": "2026-04-11", "end_date": "2026-04-17", "sort": "significance" } } ``` ## `summarize_events` Use for dashboards and trend charts before drilling into records. Summary tools do not accept `search`; use `search_events` first for semantic retrieval, then summarize with structured filters. For time-series plots, call with `group_by=date` across a meaningful recent window such as `days=14` or `days=30`. Each returned bucket is one chronological observation with count fields plus metric aggregates such as Goldstein, magnitude, systemic importance, propagation potential, market sensitivity, significance, confidence, articles, and fatalities. Use `gdelt_cloud_tool_get(tool_name="search_events", category="TECHNOLOGY")` to retrieve the scoped `subcategory` enum before calling. Use `group_by=subcategory` when you want observed live buckets and counts after choosing a parent category. For example, `summarize_events(category="Battles", group_by="subcategory")` returns ACLED sub-event buckets such as `Government regains territory`; then call `search_events(category="Battles", subcategory="Government regains territory")` for the underlying Event cards. Metric filters apply before aggregation. `significance` and `confidence` apply across Event families; CAMEO+ detail filters only match scored CAMEO+ Events; Goldstein filters match Conflict and CAMEO+ `POLITICAL` Events. `goldstein_severity` is absolute intensity, not signed valence. | Parameter | Required | Description | | ------------------------------ | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `group_by` | no | `date`, `country`, `region`, `continent`, `category`, or `subcategory`. Default `date`. | | `start_date` | no | Inclusive start date, max 30-day window. | | `end_date` | no | Inclusive end date, max 30-day window. | | `days` | no | Window size, 1-30. Default 30. | | `country` | no | Plain English country name. | | `region` | no | Plain English region; expands to an ISO-3 country list and summarizes matching Event locations plus actor-origin countries. | | `continent` | no | Plain English continent; expands to an ISO-3 country list and summarizes matching Event locations plus actor-origin countries. | | `admin1` | no | State/province/admin1 location filter. | | `event_family` | no | Deprecated legacy filter: `conflict` or `cameoplus`. Prefer `category`, which implies the family. | | `category` | no | Single product category enum: a Conflict event type or a CAMEO+ domain. | | `categories` | no | Multi-select product categories. Values are OR'd together and serialized to the API as comma-separated `category`. | | `subcategory` | no | Event subtype. Requires `category` or `categories`; use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes such as `TE01` for CAMEO+ categories. Validation errors include recoverable values. | | `domain` | no | Deprecated legacy CAMEO+ domain filter. Prefer `category` for new integrations. | | `has_fatalities` | no | Boolean fatality filter. | | `civilian_targeting` | no | Boolean Conflict filter for civilian-targeting Events. | | Metric `_min` / `_max` filters | no | Same canonical metric ranges as `search_events`, applied before summary aggregation. | | `limit` | no | Maximum buckets, 1-500. Default 50. | ## `get_event` | Parameter | Required | Description | | ---------------- | -------: | ----------------------------------------------------------------------------------------------------- | | `event_id` | yes | Known Event ID returned by `search_events` or linked from a Story. | | `include_images` | no | Keep API-enriched article sharing images and linked Entity thumbnails when available. Default `true`. | ## `search_stories` Use for narrative clusters, article evidence, and story-first questions. | Parameter | Required | Description | | -------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start_date` | no | Inclusive start date, max 30-day window. | | `end_date` | no | Inclusive end date, max 30-day window. | | `days` | no | Window size, 1-30. Default 7. | | `country` | no | Plain English country name; matches Stories through linked Event primary location. | | `region` | no | Plain English region; expands to an ISO-3 country list and matches Stories through linked Event primary location. | | `continent` | no | Plain English continent; expands to an ISO-3 country list and matches Stories through linked Event primary location. | | `admin1` | no | Location-only admin1 filter. | | `category` | no | Linked Event category filter, such as `Battles`, `Protests`, `POLITICAL`, or `CRIME`. | | `categories` | no | Multi-select linked Event categories. Values are OR'd together and serialized to the API as `category=Battles,CRIME`. | | `subcategory` | no | Linked-Event subcategory. Requires `category` or `categories` and must belong to at least one selected linked-Event category. Use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes for CAMEO+ categories. | | `story_category` | no | Legacy Story cluster category, such as `conflict_security`. | | `event_category` | no | Deprecated alias for `category` on Story linked-Event filters. | | `event_categories` | no | Deprecated alias for `categories` on Story linked-Event filters. | | `domain` | no | Deprecated legacy linked CAMEO+ domain filter. Prefer `category`. | | `search` | no | Semantic search text; not a keyword-only filter. | | `has_events` | no | `true` narrows to Stories with at least one linked structured Event. `false` (default) returns all matching Stories. | | `has_fatalities` | no | Boolean filter for Stories linked to fatal Events. | | `civilian_targeting` | no | Boolean filter for Stories linked to Conflict Events where civilians are the primary target. | | `article_count_min` | no | Minimum Story article count. | | `article_count_max` | no | Maximum Story article count. | | `sort` | no | `significance` default, or `recent`. | | `limit` | no | Number of Story cards, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | | `include_images` | no | Keep API-enriched article sharing images, source-domain avatars, and linked Entity thumbnails when available. Default `true`. | ## `summarize_stories` Use for dashboards and coverage trends before drilling into Story records. Summary tools do not accept `search`; use `search_stories` first for semantic retrieval, then summarize with structured filters. For trend plots and Brief benchmark panels, call with `group_by=date` across a recent history window. Story summaries expose story/article counts and linked-Event metric aggregates; they should not be confused with distinct Event totals. For `group_by=category` and `group_by=subcategory`, Story summary buckets use linked Event taxonomy. That makes them useful for coverage rollups such as `category="Battles", group_by="subcategory"` while preserving broad narrative coverage for date/geography summaries. | Parameter | Required | Description | | -------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `group_by` | no | `date`, `country`, `region`, `continent`, `category`, or `subcategory`. Default `date`. | | `start_date` | no | Inclusive start date, max 30-day window. | | `end_date` | no | Inclusive end date, max 30-day window. | | `days` | no | Window size, 1-30. Default 30. | | `country` | no | Plain English country name. | | `region` | no | Plain English region; expands to an ISO-3 country list and summarizes Stories through linked Event primary location. | | `continent` | no | Plain English continent; expands to an ISO-3 country list and summarizes Stories through linked Event primary location. | | `admin1` | no | Location-only admin1 filter. | | `category` | no | Linked Event category filter, such as `Battles`, `Protests`, `POLITICAL`, or `CRIME`. | | `categories` | no | Multi-select linked Event categories. Values are OR'd together and serialized to the API as comma-separated `category`. | | `subcategory` | no | Linked-Event subcategory. Requires `category` or `categories` and must belong to at least one selected linked-Event category. Use ACLED sub-event labels for Conflict categories and stable CAMEO+ event codes for CAMEO+ categories. | | `story_category` | no | Legacy Story cluster category, such as `conflict_security`. | | `event_category` | no | Deprecated alias for `category` on Story linked-Event filters. | | `event_categories` | no | Deprecated alias for `categories` on Story linked-Event filters. | | `domain` | no | Deprecated legacy linked CAMEO+ domain filter. Prefer `category`. | | `has_events` | no | `true` narrows to Stories with at least one linked structured Event. `false` (default) returns all matching Stories. | | `has_fatalities` | no | Boolean linked-fatality filter. | | `civilian_targeting` | no | Boolean linked civilian-targeting filter. | | `article_count_min` | no | Minimum Story article count. | | `article_count_max` | no | Maximum Story article count. | | `limit` | no | Maximum buckets, 1-500. Default 50. | ## `get_story` | Parameter | Required | Description | | ---------------- | -------: | ----------------------------------------------------------------------------------------------------- | | `story_id` | yes | Known Story ID returned by `search_stories` or linked from an Event. | | `include_images` | no | Keep API-enriched article sharing images and linked Entity thumbnails when available. Default `true`. | ## `get_story_articles` | Parameter | Required | Description | | ---------------- | -------: | ------------------------------------------------------------------------------------------------ | | `story_id` | yes | Known Story ID. | | `limit` | no | Number of source articles, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | | `include_images` | no | Keep source-article sharing images and source-domain avatar URLs when available. Default `true`. | ## `search_entities` | Parameter | Required | Description | | -------------------- | -------: | -------------------------------------------------------------------------------------- | | `search` | no | Entity name search string. | | `type` | no | `person` or `organization`. | | `start_date` | no | Inclusive start date, max 30-day window. | | `end_date` | no | Inclusive end date, max 30-day window. | | `days` | no | Window size, 1-30. Default 30. | | `event_family` | no | Deprecated linked-evidence filter. Prefer `category`, which implies the family. | | `category` | no | Linked Event category filter for Entity evidence. | | `categories` | no | Multi-select linked Event categories serialized as comma-separated `category`. | | `subcategory` | no | Linked Event subcategory. Requires `category` or `categories`. | | `domain` | no | Deprecated legacy linked CAMEO+ domain filter. Prefer `category` for new integrations. | | `has_fatalities` | no | Filter to Entities linked to fatal Event evidence. | | `civilian_targeting` | no | Filter to Entities linked to Conflict evidence where civilians are the primary target. | | `sort` | no | `significance` default, or `recent` for latest linked evidence. | | `limit` | no | Number of Entity cards, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | | `include_images` | no | Keep Wikipedia thumbnail/avatar URLs on Entity cards when available. Default `true`. | ## `get_entity` | Parameter | Required | Description | | ---------------- | -------: | ------------------------------------------------------------------------------------------ | | `entity_id` | yes | Known Entity ID returned by `search_entities`, Event refs, or Story refs. | | `start_date` | no | Inclusive start date for linked references, max 30-day window. | | `end_date` | no | Inclusive end date for linked references, max 30-day window. | | `days` | no | Window size, 1-30. Default 30. | | `limit` | no | Linked Story/Event references to include, 1-50. Default 10. | | `include_images` | no | Keep Wikipedia thumbnail/avatar URLs on the Entity profile when available. Default `true`. | ## `list_admin1` | Parameter | Required | Description | | --------- | -------: | --------------------------------------------------------------------------- | | `country` | yes | One plain English country name. ISO-3 and legacy FIPS aliases are accepted. | ## Energy Data Tools Use Energy tools for Global Energy Monitor registry questions: capacity, status, asset location, ownership, parent entities, and cross-tracker owner portfolios. Energy registry facts are structural; pair them with Events or Stories only when the user asks how current developments affect physical infrastructure. ### `energy_search_owners` Resolve a company, ministry, state owner, person, or investment vehicle to a canonical GEM Entity ID before portfolio analysis. | Parameter | Required | Description | | ----------------- | -------: | --------------------------------------------------------------------------------------- | | `q` | no | Search GEM ownership entities by name, abbreviation, GEM Entity ID, or external ID. | | `entity_id` | no | Exact GEM Entity ID lookup. | | `country` | no | One or more country names or ISO-3 codes; matches registration or headquarters country. | | `region` | no | Region filter over registration or headquarters country. | | `continent` | no | Continent filter over registration or headquarters country. | | `entity_type` | no | One or more GEM owner entity types, such as `company`, `government`, or `person`. | | `publicly_listed` | no | Filter to publicly listed or non-listed owner entities. | | `limit` | no | Owner records per page, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | ### `energy_get_owner` Fetch one GEM ownership entity by `entity_id`, including registration/headquarters metadata, parent GEM entities, external IDs, source metadata, and a portfolio summary across energy assets. | Parameter | Required | Description | | ------------------ | -------: | -------------------------------------------------------------------------------------------------------------------- | | `entity_id` | yes | GEM Entity ID returned by `energy_search_owners` or asset owner arrays. | | `include_exposure` | no | Request admin-gated exposure summaries from the risk/exposure preview. Non-admin callers receive a 403 from the API. | ### `energy_assets_by_owner` Pivot from a GEM Entity ID to every asset where that entity appears in owners, operators, or parents arrays. | Parameter | Required | Description | | ---------------------------------- | -------: | ----------------------------------------------------------------------------------- | | `owner_entity_id` | yes | GEM Entity ID. Use `energy_search_owners` first when the ID is unknown. | | `country` / `region` / `continent` | no | Optional geography filters over the returned portfolio. | | `tracker` | no | Optional tracker filter, such as `coal_plants`, `coal_mines`, `wind`, or `nuclear`. | | `status` | no | Optional asset-status filter. | | `operating_only` | no | When true, keeps operating assets. | | `limit` | no | Maximum asset rows. | ## Facilities Data Tools Use Facilities tools for the unified physical-asset directory — GEM energy assets, World Port Index ports, and Epoch AI data centers on one keyed surface, each resolved to its owner entities on the spine. Answer "what facilities of type X exist in country Y", "what does operator Z own", or "which facilities sit near this event" (bbox / near). Plan-gated: the underlying `/api/v2/facilities` routes require the `can_use_facilities` entitlement (Analyst plan and up) and otherwise return `403 PLAN_REQUIRED`. ### `facilities_search` Search the directory by name, type/class, source silo, geography, owner, status, and capacity. | Parameter | Required | Description | | ------------------------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `q` | no | Case-insensitive substring match on the facility name. | | `type` | no | One or more leaf facility types (`coal_plant`, `oil_gas_plant`, `nuclear_plant`, `geothermal_plant`, `bioenergy_plant`, `hydropower_plant`, `solar_farm`, `wind_farm`, `coal_mine`, `oil_gas_field`, `coal_terminal`, `lng_terminal`, `gas_pipeline`, `oil_pipeline`, `lng_carrier`, `port`, `data_center`). | | `facility_class` | no | Coarse class: `power`, `extraction`, `transport_logistics`, `digital_infrastructure`. | | `source` | no | Source silo(s): `gem`, `maritime_ports`, `epoch`. | | `country` / `region` / `continent` | no | Geography filters (same semantics as `search_events`). | | `owner_entity_id` | no | Spine entity\_id (`e_...`) — facilities this entity owns. | | `owner_search` | no | Case-insensitive substring match on the owner name. | | `status` | no | Operating-status value(s): `operating`, `construction`, `proposed`, `retired`, … | | `capacity_mw_min` / `capacity_mw_max` | no | Capacity bounds in MW (power facilities + data centers). | | `has_geo` / `has_owner` | no | Restrict to facilities with coordinates / with a resolved spine owner. | | `bbox` | no | Geographic viewport `lat_min,lon_min,lat_max,lon_max`. | | `near` | no | Proximity `lat,lon,radius_km`. | | `sort` | no | `name` (default), `capacity_desc`, `capacity_asc`, `recent`, `country`. | | `limit` | no | Cards per page, 1-100. Default 25. | | `cursor` | no | Pagination cursor from `pagination.next_cursor`. | ### `facilities_get` Fetch one facility by its stable `facility_id`, including source attributes, owners (with spine entity\_ids), and reversible cross-silo merge history. | Parameter | Required | Description | | ------------- | -------: | ----------------------------------------------- | | `facility_id` | yes | The `f_...` id from a `facilities_search` card. | ### `facilities_by_owner` Pivot from a spine entity\_id to every facility that entity owns across all silos — the owner → portfolio join. | Parameter | Required | Description | | ---------------------------------- | -------: | ----------------------------------------------------------------------- | | `owner_entity_id` | yes | Spine entity\_id (`e_...`). Resolve a name via `unified_entity_search`. | | `type` | no | Optionally scope the portfolio to one or more facility types. | | `country` / `region` / `continent` | no | Optional geography filters over the portfolio. | | `has_geo` | no | When true, only mappable facilities (with coordinates). | | `sort` | no | Facility sort order (default `capacity_desc`). | | `limit` | no | Maximum facility rows. | ## Monitoring Briefs A **Monitoring Brief** is a short, source-backed memo answering *What changed? Why does it matter? What evidence supports it? What should I watch next?* — quantified against a baseline and grounded in clickable GDELT Cloud evidence. **Brief tools are plan-gated.** `create_brief`, `list_briefs`, and `get_brief` require a plan with Briefs access (`can_use_briefs`). On a plan without it these tools are **hidden from the tool list** and any call returns a `BRIEF_ACCESS_DENIED` error; once a plan's included Brief runs are used up, `create_brief` returns `BRIEF_LIMIT_REACHED`. Brief runs are metered separately and do **not** consume the plan's query-unit quota. ### `create_brief` Create and kick off a Monitoring Brief. **Non-blocking** — returns immediately while the agent runs (\~5–10 minutes); poll `get_brief(brief_id)` for status and content. | Parameter | Required | Description | | ----------------- | -------: | ---------------------------------------------------------------------------------------------------------- | | `scope_text` | yes | One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs. | | `time_window` | no | Recent window analysed: `6h`, `24h`, `72h`, `7d`, or `30d`. Default `24h`. | | `baseline_window` | no | Earlier comparison window for change detection: `7d`, `14d`, or `30d`. Default `14d`. | | `audience` | no | Framing/length: `executive` (default), `analyst`, or `operator`. | | `depth` | no | Density: `skim`, `standard` (default), or `detailed`. | | `countries` | no | ISO-3 country codes to scope the Brief, e.g. `["YEM","SAU"]`. | | `regions` | no | Region names to scope the Brief. | | `sectors` | no | Business/mission sectors to emphasise. | | `public_link` | no | When `true`, also mint a public, shareable report URL. Default `false` (private). | | `title` | no | Optional title; auto-generated from `scope_text` if omitted. | ```json theme={null} { "tool_name": "create_brief", "tool_arguments": { "scope_text": "Monitor Red Sea maritime disruption risk to shipping across Yemen, the Red Sea, and the Gulf of Aden.", "time_window": "7d", "baseline_window": "30d", "audience": "executive", "countries": ["YEM", "SAU"] } } ``` Returns the new Brief `id`, `status` (`queued`), `title`, and report URLs. ### `list_briefs` List the caller's Monitoring Briefs with status and basic metadata (`id`, `title`, `status`, `created_at`, report URLs). No parameters. ### `get_brief` Fetch one Brief: `status`, the structured JSON `document`, `citations`, the evidence `appendix`, and report URLs. | Parameter | Required | Description | | ---------- | -------: | --------------------------------------------------------- | | `brief_id` | yes | The Brief id returned by `create_brief` or `list_briefs`. | Statuses progress `queued` → `generating` → `building` → `ready` (or `failed`). ## Response Objects `gdelt_cloud_tool_call` returns an MCP call result whose structured content is the same REST-shaped response object returned by the selected v2 API endpoint. List tools return `success`, `data`, and `pagination`; detail tools return one `data` object; summary tools return `group_by` and summary buckets. ### Event card Returned by `search_events` and `get_event`. ```json theme={null} { "success": true, "data": [ { "id": "conflict_20260417_example", "url": "https://gdeltcloud.com/story/example-story", "primary_story_url": "https://gdeltcloud.com/story/example-story", "family": "conflict", "title": "Example event title", "summary": "Short generated event summary.", "image_url": "https://example.com/source-image.jpg", "event_date": "2026-04-17", "category": "Protests", "subcategory": "Peaceful protest", "domain": "CONFLICT", "event_code": "ACLED-123", "geo": { "country": "France", "region": "Europe", "continent": "Europe", "admin1": "Ile-de-France", "location": "Paris", "latitude": 48.8566, "longitude": 2.3522 }, "geo_context": { "location_country": "France", "actor_origin_countries": ["France"] }, "actors": [ { "name": "Protesters", "country": "France", "role": "actor1" } ], "metrics": { "significance": 0.72, "goldstein_scale": -2, "magnitude": null, "systemic_importance": null, "propagation_potential": null, "market_sensitivity": null, "confidence": 0.91, "article_count": 4 }, "has_fatalities": false, "fatalities": 0, "story_refs": [ { "id": "story_20260417_example", "url": "https://gdeltcloud.com/story/example-story", "title": "Example story", "story_date": "2026-04-17", "article_count": 4 } ], "entity_refs": [ { "id": "Paris", "name": "Paris", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Paris", "image_url": "https://upload.wikimedia.org/paris.jpg", "avatar_url": "https://upload.wikimedia.org/paris.jpg" } ], "top_articles": [ { "url": "https://example.com/article", "title": "Example article", "domain": "example.com", "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.com&sz=64", "image_url": "https://example.com/source-image.jpg", "rank": 1 } ] } ], "pagination": { "limit": 25, "cursor": null, "next_cursor": "25" } } ``` | Field | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Stable v2 Event identifier. | | `url`, `primary_story_url` | Public GDELT Cloud Story URL for citation when the Event has a linked Story. | | `family` | `conflict` or `cameoplus`. | | `title`, `summary`, `event_date` | Generated Event headline, summary, and date. | | `image_url` | First available top-article sharing image promoted to the Event card. | | `category`, `subcategory`, `domain`, `event_code` | Product taxonomy and source/generated code fields. | | `geo` | Primary Event location with `country`, `region`, `continent`, `admin1`, `location`, `latitude`, and `longitude`. | | `geo_context` | Shows the location country and actor-origin countries that explain broad geo matches. | | `actors` | Event actors with `name`, normalized `country`, and `role`. | | `metrics` | Event significance plus Goldstein, CAMEO+, confidence, and article evidence metrics. | | `has_fatalities`, `fatalities` | Fatality flag and count. | | `civilian_targeting`, `civilian_targeting_label` | Conflict civilian-targeting flag and ACLED label. | | `story_refs`, `entity_refs`, `top_articles` | Linked Story, linked Entity, and top 3 source article evidence. Entity refs may include `image_url`/`avatar_url`; article refs may include `domain_avatar_url` and `image_url`. | ### Story card Returned by `search_stories` and `get_story`. ```json theme={null} { "success": true, "data": { "id": "story_20260417_example", "url": "https://gdeltcloud.com/story/example-story", "title": "Example story title", "image_url": "https://example.com/source-image.jpg", "story_date": "2026-04-17", "category": "infrastructure", "subcategory": null, "geo": { "country": "Japan", "region": "East Asia", "continent": "Asia", "admin1": "Tokyo", "location": "Tokyo", "latitude": 35.6762, "longitude": 139.6503 }, "geo_context": { "location_country": "Japan", "actor_origin_countries": ["Japan", "United States"] }, "metrics": { "significance": 0.82, "article_count": 12, "linked_event_count": 2, "max_linked_event_significance": 0.76 }, "has_events": true, "has_fatalities": false, "fatalities": 0, "linked_events": [ { "id": "cameoplus_20260417_example", "title": "Example linked Event" } ], "entity_refs": [ { "id": "Tokyo", "name": "Tokyo", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Tokyo", "image_url": "https://upload.wikimedia.org/tokyo.jpg", "avatar_url": "https://upload.wikimedia.org/tokyo.jpg" } ], "top_articles": [ { "url": "https://example.com/article", "title": "Example article", "domain": "example.com", "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.com&sz=64", "image_url": "https://example.com/source-image.jpg", "rank": 1 } ] } } ``` | Field | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `id`, `url` | Stable Story id and public GDELT Cloud Story URL. | | `title`, `story_date` | Cluster headline and date. | | `image_url` | First available top-article sharing image promoted to the Story card. | | `category`, `subcategory` | Story and linked-Event taxonomy context. | | `geo`, `geo_context` | Primary linked-Event geography and actor-origin countries. | | `metrics` | Story significance, article count, linked Event count, and max linked Event significance. | | `has_events`, `linked_events` | Whether structured Events link to the Story and up to 10 linked Event refs. | | `has_fatalities`, `fatalities` | Whether linked Events include fatalities, plus total linked fatalities. | | `entity_refs`, `top_articles` | Linked Entities and top 3 source articles, with optional Entity thumbnails, article images, and domain avatars. | ### Event summary bucket Returned by `summarize_events`. ```json theme={null} { "success": true, "group_by": "country", "data": [ { "key": "France", "group_by": "country", "event_count": 12, "conflict_event_count": 4, "cameoplus_event_count": 8, "fatality_event_count": 2, "fatalities": 6, "fatality_event_rate": 0.1667, "country_count": 1, "region_count": 1, "article_count": 40, "avg_article_count": 3.333, "min_article_count": 1, "max_article_count": 12, "avg_significance": 0.42, "max_significance": 0.91, "min_significance": 0.05, "avg_goldstein_scale": -3.8, "metrics": { "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 }, "goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 }, "goldstein_severity": { "avg": 4.2, "min": 0.5, "max": 8 }, "cameoplus": { "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 }, "systemic_importance": { "avg": 0.52, "min": 0.11, "max": 0.9 }, "propagation_potential": { "avg": 0.47, "min": 0.07, "max": 0.81 }, "market_sensitivity": { "avg": 0.31, "min": 0.03, "max": 0.75 } }, "confidence": { "avg": 0.83, "min": 0.44, "max": 0.98 }, "article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 }, "fatalities": { "events": 2, "rate": 0.1667, "total": 6 } }, "metric_stats": { "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 } } } ] } ``` ### Story summary bucket Returned by `summarize_stories`. ```json theme={null} { "success": true, "group_by": "date", "data": [ { "key": "2026-04-17", "group_by": "story_date", "story_count": 5, "article_count": 25, "avg_article_count": 5, "min_article_count": 2, "max_article_count": 11, "stories_with_events": 4, "story_only_count": 1, "linked_event_count": 7, "min_linked_event_count": 0, "avg_linked_event_count": 1.4, "max_linked_event_count": 3, "stories_with_fatalities": 1, "fatalities": 2, "fatality_story_rate": 0.2, "avg_significance": 0.5, "max_significance": 0.88, "min_significance": 0.12, "metrics": { "significance": { "avg": 0.5, "max": 0.88, "min": 0.12 }, "article_count": { "total": 25, "avg": 5, "min": 2, "max": 11 }, "linked_events": { "count": { "total": 7, "avg": 1.4, "min": 0, "max": 3, "stories_with_events": 4, "story_only_count": 1 }, "significance": { "avg": 0.62, "min": 0.18, "max": 0.94 }, "goldstein_scale": { "avg": -3.2, "min": -7.5, "max": 1.5, "avg_severity": 3.8 }, "goldstein_severity": { "avg": 3.8, "min": 0.8, "max": 7.5 }, "magnitude": { "avg": 5.5, "min": 1.1, "max": 8.4 }, "systemic_importance": { "avg": 0.44, "min": 0.12, "max": 0.77 }, "propagation_potential": { "avg": 0.41, "min": 0.09, "max": 0.72 }, "market_sensitivity": { "avg": 0.39, "min": 0.04, "max": 0.68 }, "confidence": { "avg": 0.81, "min": 0.51, "max": 0.96 } }, "recency_score": { "avg": 1 }, "fatalities": { "stories": 1, "rate": 0.2, "total": 2 } }, "metric_stats": { "significance": { "avg": 0.5, "max": 0.88, "min": 0.12 } } } ] } ``` | Summary field | Description | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `key`, `group_by` | Bucket value and concrete grouping label. | | `event_count`, `story_count` | Number of Events or Stories in the bucket. | | `conflict_event_count`, `cameoplus_event_count` | Event-family counts. | | `article_count`, `avg_article_count`, `min_article_count`, `max_article_count` | Evidence volume. | | `fatality_event_count`, `stories_with_fatalities`, `fatalities`, rates | Fatality coverage. | | `country_count`, `region_count` | Distinct geography counts represented in the bucket. | | `stories_with_events`, `story_only_count` | Story buckets split by whether they link to one or more structured Events. | | `linked_event_count`, `min_linked_event_count`, `avg_linked_event_count`, `max_linked_event_count` | Story-to-Event link coverage for Story buckets. This is not a distinct Event total. | | `metrics`, `metric_stats` | Nested aggregate statistics; `metric_stats` is an alias of `metrics`. | ### Articles, Entities, Admin1, And Standard error `get_story_articles` returns Article objects with `id`, `url`, `title`, `domain`, `article_date`, `rank`, and `role`, plus pagination. `search_entities` returns Entity cards with `id`, `url`, `name`, `type`, `wikipedia_url`, and `metrics`. `get_entity` adds `story_refs`, `event_refs`, and admin-gated `entity_tone` when requested by API clients. `list_admin1` returns `success`, normalized `country`, an `admin1` array, and `source`. Energy owner tools return GEM ownership records with `entity_id`, `name`, registration/headquarters fields, parent IDs, external IDs, `portfolio_url`, `detail_url`, and `portfolio_summary`. `energy_get_owner(include_exposure=true)` can also include admin-gated exposure summaries. ```json theme={null} { "success": false, "error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania", "code": "INVALID_CONTINENT", "details": { "param": "continent", "invalid_value": "Atlantis", "accepted_values": ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"], "example": "?continent=Asia" } } ``` Category/subcategory validation errors include `accepted_values`, `nearest_values` when practical, and a corrected example so agents can recover in the next call. A subcategory without its parent category returns a compact parent-required error. ## Output Notes * Country output is plain English. * Geo output includes `country`, `region`, `continent`, `admin1`, `location`, `latitude`, and `longitude` when available. * Event geography filters match location country or actor-origin country. Dashboard clients should compare `geo.location_country` and `geo_context.actor_origin_countries` to label a result as a location match, actor match, or both. * Event and Story cards include top 3 inline articles. * Full Story article lists are paginated through `get_story_articles`. * `metrics.goldstein_scale` is the only public Goldstein metric on Event cards. It is present for Conflict Events and CAMEO+ `POLITICAL` Events where meaningful, and null for non-political CAMEO+ Events. * CAMEO+ detail metric filters (`magnitude`, `systemic_importance`, `propagation_potential`, `market_sensitivity`) only match scored CAMEO+ Events. `significance` and `confidence` are cross-family filters. * Those four are **rubric scores** — the coder reads concrete sub-factors off the source text and a fixed published formula turns them into the value. Read them as ordinal ranking signals, not measurements, probabilities, or predicted price moves. `magnitude` is comparable **within a domain only** and is `null` when no severity observable was found (`null` means unknown, never `0`). * Event significance is a **family-scoped weighted blend**, renormalized so every family spans a true 0–1: each event's raw total is divided by the maximum its own family can reach (Conflict `1.00`, CAMEO+ `POLITICAL` `0.90`, other CAMEO+ domains `0.65`). All events: Goldstein severity `0.25`, article evidence `0.05`, confidence `0.05`. Conflict only: fatalities `0.55` (log-scaled by body count, saturating around 100 deaths), civilian targeting `0.10`. CAMEO+ only: magnitude `0.20`, systemic importance `0.15`, propagation potential `0.10`, market sensitivity `0.10`. When `magnitude` is unmeasured, both its term and its `0.20` weight are dropped. * Default ranking is canonical `significance`; use `recent` when freshness matters more than importance.