Skip to main content
Glama

gdelt-mcp-server

by io.github.cyanheads

Get GDELT TV Context

gdelt_get_tv_context
Read-only

Get the top co-occurring words and phrases from TV news clips matching a query — the vocabulary framing a topic on television. Returns the most frequent non-stopword terms from matching clips, with relative frequency scores (0–100, where 100 = the query term itself). Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms. TV data spans 2009–October 2024.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".
stationsNoStation IDs to filter to (e.g. ["CNN", "FOXNEWS"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid IDs.
timespanNoTime window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.
endDatetimeNoEnd datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected.
startDatetimeNoStart datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected. TV data spans 2009–October 2024.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
wordsNoCo-occurring terms sorted by score descending.
noticeNoRecovery hint when no context was found. Absent on successful responses.
totalCountNoNumber of clips from which co-occurrences were computed. Absent when the upstream API does not return a clip count.
effectiveQueryNoEchoed query string for use in follow-up calls.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this read-only, so the description adds value by explaining the output: most frequent non-stopword terms with relative frequency scores where 100 equals the query term itself. It also discloses the TV data time span, which agents would not know from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, followed by useful output semantics and use cases. Every sentence contributes distinct information, and there is no filler or tautology.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema and output schema, the description sufficiently explains return semantics and intended use. It could mention the station requirement more prominently, but the schema already covers that detail, so the description is complete enough for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters including query operators, station requirements, and datetime constraints. The description adds no additional parameter-level meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb and resource: get top co-occurring words/phrases from TV news clips. It clearly differentiates from siblings like gdelt_get_tv_clips and gdelt_get_tone_distribution by describing the output as vocabulary framing, not clips or tones.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use it: understand narrative framing, identify related concepts, and generate follow-up search terms. It does not name alternative tools or state when not to use it, but the intended contexts are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All gdelt-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool serves a distinct purpose: search articles vs. search TV, coverage timelines vs. breakdowns vs. tone distributions, and TV-specific tools for clips, context, trending, and station listing. Even overlapping functions like get_coverage_timeline and get_tone_distribution are clearly differentiated by description.

Naming Consistency5/5

All tools follow the consistent pattern 'gdelt_<verb>_<object>' using snake_case, with verbs limited to get, search, and list. The naming is predictable and uniform, with no mixed conventions.

Tool Count5/5

Nine tools is a well-scoped number for the GDELT domain, covering both text and TV news APIs without redundancy. Each tool adds clear value, and the count is within the ideal 3-15 range.

Completeness5/5

The tool surface covers the core workflows: searching articles and TV transcripts, obtaining coverage timelines and breakdowns, analyzing tone distributions, retrieving TV clips and context, and listing stations. There are no obvious dead ends or missing operations for the stated purpose.

Resources