Skip to main content

​
Overview

The gdelt_system_prompt provides AI assistants with concise guidance for using the GDELT Cloud API tools effectively. It covers the data model, available tools, response size control, filters, and recommended workflows.
This prompt requires no parameters and returns a complete system message ready for use with any LLM.

​
When to Use

Use gdelt_system_prompt when:
  • Initializing an AI agent that will query GDELT data
  • Building a research assistant with GDELT capabilities
  • Creating a chatbot that needs GDELT expertise
  • Setting up automated GDELT analysis workflows

​
Prompt Structure

The system prompt is compact (~80 lines) and covers five key areas:
1

Data Model

How GDELT Cloud data is organized: news articles are grouped into GDELT events, events are clustered into Media Events (stories), and Entities (people and organizations) are linked across stories via Wikipedia.
2

Response Size Control

Critical guidance on managing token usage with the detail, limit, and offset parameters. Includes a token-count reference table so agents can estimate response sizes before calling tools.
DetailMedia EventsClusterEntity
summary~120 tok/cluster~500 tok~300 tok
standard~500 tok/cluster~1,500 tok~1,200 tok
full~1,000 tok/cluster~3,000+ tok~1,500 tok
Agents should start with detail=summary and small limit values, then zoom into specific items as needed.
3

Tool Descriptions

Concise descriptions of the four API tools with their key parameters:
ToolPurpose
get_media_eventsDiscover top news stories — filter by category, country, event type, location
get_media_event_clusterDeep-dive into a single story — articles, entities, metrics
get_entityGEG entity profile — linked stories, co-occurrences, timeline
get_domainNews domain profile — stats, top entities, recent articles
4

CAMEO Code Resources

Where to find reference codes using the three resource tools:
  • cameo-country-codes — ISO-3 codes for actor filtering (USA, GBR, CHN)
  • cameo-event-codes — Event taxonomy (14=Protest, 18=Assault, 19=Fight)
  • goldstein-scale — Event intensity scale (-10 to +10)
5

Workflow Guidance

A recommended scan → zoom → enrich pattern:
  1. Scan — get_media_events with detail=summary to discover what’s happening
  2. Zoom — get_media_event_cluster to deep-dive into a specific story
  3. Enrich — get_entity or get_domain for background on key players or sources

​
Usage Examples

from fastmcp import Client
from fastmcp.client.auth import BearerAuth
import os

async with Client(
    "https://gdelt-cloud-mcp.fastmcp.app/mcp",
    auth=BearerAuth(token=os.environ["GDELT_API_KEY"])
) as client:
    # Get the prompt
    prompt_result = await client.get_prompt("gdelt_system_prompt")
    
    for message in prompt_result.messages:
        print(message.content)

​
Integration Pattern

from langchain_openai import ChatOpenAI

# Fetch system prompt from MCP
gdelt_prompt = await mcp_client.get_prompt("gdelt-cloud", "gdelt_system_prompt")
gdelt_text = "\n\n".join(msg.content for msg in gdelt_prompt)

# Combine with your own instructions
system_prompt = f"""You are a GDELT research assistant.

{gdelt_text}

Additional instructions:
- Always cite sources using article URLs
- Start with summary detail level for discovery
- Explain your reasoning for filter choices
"""

# Create agent with tools + prompt
agent = create_agent(
    model=ChatOpenAI(model="gpt-4", temperature=0),
    tools=gdelt_tools,
    system_prompt=system_prompt
)

​
Best Practices

Combine with your own context — The system prompt provides GDELT expertise. Add your own instructions for task-specific behavior (tone, output format, citations, etc.).
Fetch at initialization — Always fetch the latest version at agent startup rather than hard-coding, as the prompt may be updated as GDELT Cloud evolves.
Response size matters — The prompt emphasizes starting with detail=summary and small limits. This prevents agents from consuming excessive tokens on discovery calls.

​
Response Format

Returns a Message object (or list of Message objects) with:
​
role
string
required
Message role, typically “assistant” or “system”
​
content
string
required
The complete system prompt text (~80 lines)

​
Next Steps

Get Media Events

Discover top news stories with the primary discovery tool

LangChain Integration

Full example of building a LangChain agent with GDELT tools

Code References

CAMEO country codes, event codes, and Goldstein scale

Authentication

Set up API key authentication for MCP access