> ## 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.

# Progressive Discovery

> How agents discover, inspect, and call GDELT Cloud MCP tools

## Overview

GDELT Cloud MCP uses a Progressive Discovery interface. Agents do not call GDELT Cloud product tools directly. They first discover the catalog, inspect exact schemas, then execute a named tool through a single wrapper.

This keeps the public MCP surface small while still giving agents rich tool descriptions and typed parameter guidance.

## What The Agent Actually Sees

The public MCP surface is intentionally small. Agents see wrapper tools, not every nested product operation as a separate top-level tool.

| Category           | Top-Level Wrapper Tools Agents See                                                         |
| ------------------ | ------------------------------------------------------------------------------------------ |
| GDELT Cloud        | `gdelt_cloud_tool_list`, `gdelt_cloud_tool_get`, `gdelt_cloud_tool_call`                   |
| Macro finance      | `macro_finance_tool_list`, `macro_finance_tool_get`, `macro_finance_tool_call`             |
| Prediction markets | `prediction_market_tool_list`, `prediction_market_tool_get`, `prediction_market_tool_call` |
| Web research       | `web_research_tool_list`, `web_research_tool_get`, `web_research_tool_call`                |

Inside each `*_tool_call`, the agent passes a nested `tool_name` and `tool_arguments`.

## Public GDELT Cloud MCP Tools

The MCP server exposes these three GDELT Cloud wrapper tools:

| Tool                    | Purpose                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `gdelt_cloud_tool_list` | List the public v2 GDELT Cloud tools and when to use them.                             |
| `gdelt_cloud_tool_get`  | Fetch exact schema, descriptions, enums, and parameter guidance for one or more tools. |
| `gdelt_cloud_tool_call` | Execute a named v2 GDELT Cloud tool with nested `tool_arguments`.                      |

<Info>
  The legacy v1 MCP tool names are no longer exposed. v1 REST endpoints remain supported for direct API users, but agents should use the v2 MCP catalog documented here.
</Info>

## Workflow

<Steps>
  <Step title="Discover">
    Call `gdelt_cloud_tool_list` to see the available v2 GDELT Cloud product tools.
  </Step>

  <Step title="Inspect">
    Call `gdelt_cloud_tool_get` before first use of a tool. The schema contains practical descriptions, enum values, default behavior, and guidance on how analysts should use each parameter.
  </Step>

  <Step title="Execute">
    Call `gdelt_cloud_tool_call` with `tool_name` and nested `tool_arguments`.
  </Step>
</Steps>

<Info>
  Event, Story, and Entity search tools default to the exact past 24 hours. Agents should narrow with developer-facing filters such as `category`, `subcategory`, `civilian_targeting`, country/region/continent filters, date windows, `sort`, and pagination.
</Info>

## Example

```json theme={null}
{
  "tool_name": "search_events",
  "tool_arguments": {
    "category": "Battles",
    "subcategory": "Armed clash",
    "country": "Lebanon",
    "has_fatalities": true,
    "days": 7,
    "sort": "significance",
    "limit": 10
  }
}
```

## v2 Catalog

| v2 Tool              | Use When                                                             |
| -------------------- | -------------------------------------------------------------------- |
| `search_events`      | You need structured Conflict or CAMEO+ Event cards.                  |
| `summarize_events`   | You need dashboard-ready Event counts or trends.                     |
| `get_event`          | You know an Event ID and need the full card.                         |
| `search_stories`     | You need clustered narrative Stories and article evidence.           |
| `summarize_stories`  | You need Story rollups by date, geography, category, or subcategory. |
| `get_story`          | You know a Story ID and need details plus top articles.              |
| `get_story_articles` | You need the full paginated article list for a Story.                |
| `search_entities`    | You need to discover linked people or organizations.                 |
| `get_entity`         | You know an Entity ID and need its linked Stories and Events.        |
| `list_admin1`        | You need valid state/province/admin1 names for one country.          |

## External Enrichment Categories

GDELT Cloud structured Events and Stories should anchor the analysis. External MCP categories are encouraged as complements:

| Category              | Use For                                                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `macro_finance_*`     | Quotes, FX, commodities, rates, historical series, and macro indicators.                                               |
| `prediction_market_*` | Kalshi-backed event and market search, contract details, probabilities, status, and public market URLs when available. |
| `web_research_*`      | Corroboration, official statements, specialist sources, and reading source-article pages.                              |

For geopolitical, macro-finance, supply-chain, and location-security analysis, use GDELT Cloud first to establish the structured signal, then enrich or verify with macro finance, prediction markets, and web research where relevant.

## External Nested Tools

| Category           | Nested Tools                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prediction markets | `SEARCH_RELEVANT_MARKETS`, `SEARCH_EVENTS`, `SEARCH_MARKETS`, `GET_MARKET`                                                                                    |
| Web research       | `SEARCH_WEB`, `EXTRACT_WEB_PAGES`                                                                                                                             |
| Macro finance      | Discover current macro-finance provider-backed quote, historical series, FX, commodities, rates, and economic-indicator tools with `macro_finance_tool_list`. |

The web-research category exposes only `SEARCH_WEB` and `EXTRACT_WEB_PAGES`; crawl and map operations are intentionally not public.