gdelt-mcp-server

Name: gdelt-mcp-server
Author: cyanheads

Server Details

Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 100.0% over 44 days
Last Tested: 2026-09-30 15:35
Transport: Streamable HTTP · MCP 2025-11-25
URL
Repository: cyanheads/gdelt-mcp-server
GitHub Stars: 6
Server Listing: @cyanheads/gdelt-mcp-server

TDQS

A4.5/5.0

Scored 2026-09-24 20:35 across 9 tools

Disambiguation5/5

Each tool targets a distinct resource or action: coverage analysis (timeline, breakdown, tone distribution), article search, theme lookup, TV search, TV clips, TV context, and station listing. Even the overlapping tone distribution vs. timeline tone mode are explicitly differentiated as snapshot vs. time series, leaving no ambiguity.

Naming Consistency5/5

All tools follow a consistent gdelt_ + verb + noun pattern, using verbs 'get', 'search', and 'list' predictably. The naming is uniform and immediately conveys the tool's function, making the set easy to navigate.

Tool Count5/5

With 9 tools, the server is well-scoped for its purpose of news monitoring and analysis. It covers article search, TV search, theme lookup, and multiple coverage analytics without bloat, and each tool serves a clear role.

Completeness4/5

The surface covers core workflows: article search (with a noted 3-month limitation), TV search with clips and context, theme lookup, and coverage analytics. Minor gaps exist, such as no historical article search beyond 3 months and no direct article-by-ID retrieval, but these are largely API constraints rather than missing tool design.

Available Tools

9 tools

gdelt_get_coverage_breakdownGet GDELT Coverage BreakdownA

Read-only

Inspect

Break down news coverage volume over time by source language or source country, returning a multi-series time series (one series per language or country). Shows which countries or languages drove early vs. late coverage — useful for tracing how a story propagated geographically or across language communities. Returns up to 10 series by total volume and aggregates the rest into an "Other" bucket, naming every series it folded in there under otherSeriesLabels — pass any of those labels back as the series input to get that series complete, ranked or not. Values are normalized: each point is the topic's share of media output, not an absolute article count. Small media markets with concentrated coverage therefore rank above large markets with diverse output — a high value means the topic dominated that source's coverage, not that it published the most articles. Use breakdownBy "country" with the signal-detection chain to map geographic attention, or "language" to detect non-English media surges.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes).
`series`	No	Exact series labels to additionally return in full, e.g. ["Portuguese", "Vietnamese"]. Take them verbatim from otherSeriesLabels (the series folded into "Other") or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, on top of the usual top-10 overview; a label that matches nothing is rejected rather than silently skipped. Omit to get the overview alone.
`timespan`	No	Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.
`breakdownBy`	Yes	Breakdown dimension: "language" for source language time series, "country" for source country time series.
`endDatetime`	No	End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected.
`startDatetime`	No	Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when breakdown data was returned.
`topSeries`	No	Top 10 series by total coverage volume.
`totalCount`	No	Total number of series returned before truncation to top 10.
`breakdownBy`	No	Breakdown dimension used for this response.
`endDatetime`	No	Echoed end datetime when provided (YYYYMMDDHHMMSS).
`startDatetime`	No	Echoed start datetime when provided (YYYYMMDDHHMMSS).
`dateResolution`	No	Temporal resolution of data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.
`selectedSeries`	No	Complete, untruncated time series for each label requested via the series input, in the order requested. Omitted when series was not supplied.
`otherAggregated`	No	Combined time series for all series beyond the top 10. Omitted when all series fit.
`otherSeriesLabels`	No	Label of every series folded into otherAggregated, ranked by total volume — the identities the "Other" bucket would otherwise dissolve. Pass any of them to the series input to retrieve that series' complete data. Omitted when all series fit in the top 10.

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral traits: the top-10 series limit, the 'Other' aggregation bucket, the otherSeriesLabels mechanism, and the normalization of values as share-of-media-output rather than absolute counts. It also explains the counterintuitive ranking consequence for small media markets, which is essential for correct interpretation.

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 long but every sentence carries unique information: purpose, use case, series behavior, normalization semantics, and dimension-specific guidance. It is front-loaded with the core purpose and then layers behavioral details logically, with no filler or repetition of schema content.

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

Completeness5/5

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

Given the tool's complexity, the presence of an output schema, and rich annotations, the description covers everything an agent needs: what the tool does, how to interpret results, how to handle series labels, and which breakdown dimension to choose. Nothing critical is missing for correct invocation and result interpretation.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains how 'series' labels should be sourced verbatim from otherSeriesLabels, that unmatched labels are rejected rather than skipped, and that values are normalized shares. This goes well beyond the baseline and materially improves correct parameter usage.

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?

The description states a specific verb ('break down'), a clear resource ('news coverage volume over time'), and the two dimensions ('source language or source country'). It also distinguishes itself from the sibling gdelt_get_coverage_timeline by emphasizing multi-series breakdown and geographic/language propagation analysis.

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 gives explicit guidance on when to use 'country' vs 'language' breakdowns ('map geographic attention' vs 'detect non-English media surges') and explains how to use otherSeriesLabels for deeper series retrieval. It doesn't explicitly name sibling tools as alternatives, but the context is clear enough for an agent to select this tool appropriately.

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

gdelt_get_coverage_timelineGet GDELT Coverage TimelineA

Read-only

Inspect

Retrieve a time series showing when news coverage of a topic spiked, or how average tone shifted over time. Use mode "volume" for normalized coverage intensity (% of all global coverage per timestep). Use mode "volume_with_articles" for the same signal plus the top articles that drove each spike — this is the primary signal-detection mode: a single call reveals both the spike and its cause, avoiding a follow-up gdelt_search_articles call. Use mode "tone" for average sentiment score per timestep (negative = hostile/fearful, positive = celebratory). Date resolution is inferred from returned intervals: 15 minutes or hours for short windows, days for longer ones. In volume_with_articles mode the text surface shows the first 3 article links per timestep next to that timestep's true article count; name a timestep's date in points to render its full list. Note: DOC API covers only the last 3 months.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No	Timeline mode: "volume" returns normalized coverage % per timestep, "volume_with_articles" returns volume plus top articles per spike (best for signal detection), "tone" returns average sentiment score per timestep.	volume
`query`	Yes	Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes), tone<.
`points`	No	Timestep dates whose complete article list should be rendered in the text surface, e.g. ["2024-01-05T12:00:00Z"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored.
`timespan`	No	Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.
`smoothing`	No	Smoothing window in timesteps (0 = none, 1–5 = moving average width). Reduces noise for spotty topics.
`endDatetime`	No	End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected.
`startDatetime`	No	Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected.

Output Schema

ParametersJSON Schema

Name	Required	Description
`mode`	No	Timeline mode used for this response.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when timeline data was returned.
`series`	No	One or more time series (typically one for volume/tone, one per label for breakdowns).
`totalCount`	No	Total number of data points across all series.
`endDatetime`	No	Echoed end datetime when provided (YYYYMMDDHHMMSS).
`startDatetime`	No	Echoed start datetime when provided (YYYYMMDDHHMMSS).
`dateResolution`	No	Temporal resolution of the data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.
`expandedPoints`	No	Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way.

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses rich behavioral details: date resolution is inferred from intervals, the text surface shows first 3 article links per timestep, named points render full lists, unmatched dates are rejected, and DOC API coverage is limited to 3 months. No contradiction with annotations.

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

Conciseness4/5

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

The description is a single dense paragraph of ~150 words. Every clause adds operational value (mode semantics, resolution inference, rendering behavior, limitation), but it is longer than a minimal definition. It remains scannable and free of filler, so it earns a 4 rather than a 5.

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

Completeness5/5

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

For a 7-parameter tool with an output schema and several siblings, the description covers the main decision axes: which mode to choose, how timestep granularity is determined, how to reveal full article lists, and the DOC API time window. The output schema handles return structure, so no further return-value detail is needed.

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

Parameters4/5

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

All 7 parameters already carry detailed schema descriptions (100% coverage), so the baseline is 3. The description adds cross-parameter context—how mode changes the signal returned, how points affects rendering, and the 3-month limitation—so it earns a 4. It does not repeat field-level explanations already present in the schema.

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?

The description opens with a specific verb-resource pair ('Retrieve a time series') and then defines the three modes and what each returns. It explicitly contrasts with gdelt_search_articles, making the tool's role distinct from siblings like gdelt_get_coverage_breakdown or gdelt_get_tone_distribution.

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 maps each mode to a concrete use case ('primary signal-detection mode', 'normalized coverage intensity', 'average sentiment score') and recommends volume_with_articles to avoid a follow-up search. It does not explicitly state when to prefer this tool over the breakdown/tone-distribution siblings, but the mode guidance is strong and actionable.

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

gdelt_get_tone_distributionGet GDELT Tone DistributionA

Read-only

Inspect

Get the tonal distribution of articles matching a query as a histogram (bins approximately -30 to +30). Unlike a single average tone score, the histogram reveals whether coverage is uniformly negative, bimodal (some articles extremely positive and some extremely negative), or clustered near neutral. Each bin includes representative article URLs. Distinct from gdelt_get_coverage_timeline (mode: tone) — this is a snapshot distribution across all matching articles, not a time series. Use gdelt_get_coverage_timeline with mode "tone" to see how sentiment shifted over time.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes).
`timespan`	No	Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months.
`endDatetime`	No	End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected.
`startDatetime`	No	Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when no articles matched in the window — how to broaden the query or extend the window. Absent when tone data was returned.
`summary`	No	Summary statistics derived from the histogram. Each value is omitted when the histogram cannot support it — all of them on an empty result.
`histogram`	No	Tone histogram sorted from most negative to most positive bin.
`totalCount`	No	Total number of articles across all histogram bins.
`endDatetime`	No	Echoed end datetime when provided (YYYYMMDDHHMMSS).
`startDatetime`	No	Echoed start datetime when provided (YYYYMMDDHHMMSS).
`effectiveQuery`	No	Echoed query string for use in follow-up calls.

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint. The description adds behavioral context: the histogram bin range (~-30 to +30), that bins include representative article URLs, and that it is a snapshot rather than a time series. This goes beyond the annotations and helps the agent understand the shape of the response. A slight gap is not describing any pagination or volume limits, but given the output schema exists, this is adequate.

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 well-structured and front-loaded: it states the core function first, then explains the added value of a histogram, then differentiates from the sibling and gives a usage directive. Every sentence contributes meaning; no filler or repetition. It is concise for the information it conveys.

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

Completeness5/5

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

With an output schema present, the description does not need to explain return values. It covers the query syntax, time constraints, and differentiation from the timeline tool. All necessary information for correct invocation is present, and the description addresses the main usage decision an agent must make.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds value by referencing the query syntax of gdelt_search_articles and mentioning that timespan is ignored when start/end datetime are set. This supplements the schema without redundancy, earning a score above the baseline.

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?

The description clearly states the tool returns a tonal distribution histogram for articles matching a query, and explicitly contrasts it with a single average tone score and with the timeline sibling. It specifies the resource (articles) and the output format (histogram with bins and representative URLs), making the purpose unmistakable.

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

Usage Guidelines5/5

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

It explicitly names the sibling tool gdelt_get_coverage_timeline and explains when to use it instead: to see sentiment over time, versus this snapshot distribution. It also clarifies that the query syntax follows gdelt_search_articles, giving the agent direct guidance on parameter construction.

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

gdelt_get_tv_clipsGet GDELT TV ClipsA

Read-only

Inspect

Retrieve the top matching TV news clips for a query from the Internet Archive's Television News Archive: fetches up to 3,000 and returns as many as fit a 48,000-byte response — the rest are counted in withheldCount, with a continuation to reach them. Each clip includes show name, station, air timestamp, a 15-second transcript excerpt, and a direct link to view the full one-minute clip. Use after gdelt_search_tv to read the actual transcript content driving a coverage spike. GDELT answers TV windows in whole clock hours; clips it returns from outside an explicit startDatetime/endDatetime window are dropped, and continuing a cut response at maxRecords 3000 leaves room for them. 3,000 is a hard per-call ceiling and GDELT offers no cursor: when a query fills it or a response comes back cut, re-query narrower startDatetime/endDatetime windows — the response hands back the exact windows to use. Archive coverage spans 2009–October 2024.

ParametersJSON Schema

Name	Required	Description	Default
`sort`	No	Sort order: relevance (default), dateDesc (newest first), dateAsc (oldest first).	relevance
`query`	Yes	Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".
`stations`	No	Station 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.
`timespan`	No	Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.
`maxRecords`	No	Maximum number of clips to fetch (1–3000); the response carries as many of them as fit its 48,000-byte budget. 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead.
`endDatetime`	No	End 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.
`startDatetime`	No	Start 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.

Output Schema

ParametersJSON Schema

Name	Required	Description
`clips`	No	Matching TV clips sorted per the sort parameter.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to target the 2009–October 2024 archive or verify station IDs. When GDELT returned clips aired outside the requested window (it answers whole clock hours), how many were dropped. When the response was cut to its 48,000-byte budget, how many clips it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more clips may exist — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget.
`totalCount`	No	Number of clips returned.
`withheldCount`	No	In-window clips GDELT returned that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting clips dropped for falling outside the window. Absent when every in-window clip fit.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.
`continuationWindows`	No	Windows to re-run this query against, one at a time, when more clips are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned clip, reaching back to the second it aired, so clips from that second come back again — de-duplicate by archiveUrl — or, when resuming there cannot reach a new clip, one window skipping past that second. Otherwise — maxRecords at its 3000 ceiling, or a relevance cut — the queried window split in two, on a clock hour when one falls inside it; the halves share no second. Absent when no window is known, or none would reach further.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only provide readOnlyHint and openWorldHint, but the description goes far beyond them, detailing response-size limits (48,000-byte budget), continuation behavior (withheldCount), window-based clip dropping, the hard per-call ceiling of 3000, absence of a cursor, and the re-query strategy. This level of behavioral disclosure is exceptional and fully prepares the agent for real API behavior.

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

Conciseness4/5

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

The description is long, but every sentence earns its place. It opens with the core purpose, then logically flows through limits, content, usage context, window semantics, ceiling, and coverage span. It is front-loaded with the most important facts and avoids redundancy. While it could be tightened slightly, the complexity of the tool justifies the length.

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

Completeness5/5

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

Given the tool's complexity (7 parameters, output schema, annotations), the description covers all critical operational aspects: response contents, pagination via withheldCount, the 48KB limit, the 3000 hard ceiling, window dropping, re-query guidance, station requirements, and data coverage period. It even explains the relationship to sibling tools. An agent can call this correctly without external documentation.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining parameter interplay: maxRecords' true nature as a ceiling (not a page size), the requirement to pair startDatetime/endDatetime and rejection of one-sided input, the need for a station (either via stations or query), and the timespan precedence rule. This goes beyond simple schema field documentation.

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?

The description opens with a specific verb ('Retrieve') and a precise resource ('top matching TV news clips... from the Internet Archive's Television News Archive'). It clearly distinguishes the tool from siblings by stating it is used to read actual transcript content after gdelt_search_tv, and it lists the exact data elements returned (show, station, timestamp, transcript excerpt, link). No ambiguity remains about what the tool does.

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 states when to use the tool: 'Use after gdelt_search_tv to read the actual transcript content driving a coverage spike.' It also provides practical handling for edge cases (cut responses, 3000 ceiling) with instructions to re-query narrower windows. It does not explicitly name alternative tools it should be contrasted with, but the workflow is clear and the limitation guidance is actionable.

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

gdelt_get_tv_contextGet GDELT TV ContextA

Read-only

Inspect

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.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine".
`stations`	No	Station 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.
`timespan`	No	Time window, e.g. "1m", "6m". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.
`endDatetime`	No	End 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.
`startDatetime`	No	Start 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

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`words`	No	Co-occurring terms sorted by score descending.
`notice`	No	Guidance when no clips matched, so there is no vocabulary to report — the resolved timespan window, the October 2024 archive cutoff, and how to broaden the query or check station coverage. Absent when terms were returned.
`totalCount`	No	Number of clips from which co-occurrences were computed. Absent when the upstream API does not return a clip count.
`effectiveQuery`	No	Echoed 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it specifies the output scoring scale (0–100, where 100 = the query term itself) and the data range (2009–October 2024). No contradictions with 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 three sentences, front-loaded with the primary purpose, then output details, then use cases, and finally data range. Every sentence earns its place with no redundancy or fluff.

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?

The description covers the core behavior, output format, usage scenarios, and data range. It does not explicitly mention the station requirement, but that is thoroughly documented in the schema. With an output schema present, the description is complete enough for an agent to invoke 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 coverage is 100%, with all five parameters having detailed descriptions. The description itself does not add parameter-level meaning beyond what the schema provides, but it does reinforce the data range constraint. Given full schema coverage, the baseline of 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?

The description states a specific verb and resource: 'Get the top co-occurring words and phrases from TV news clips matching a query'. It clearly differentiates this from sibling tools like tone distribution or coverage breakdown by focusing on vocabulary framing. The output format is also specified, making the tool's function unmistakable.

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 provides explicit use cases: 'understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms'. It does not explicitly name alternative tools, but the context is clear enough for an agent to infer when this tool is appropriate versus siblings like gdelt_get_tone_distribution.

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

gdelt_list_tv_stationsList GDELT TV StationsA

Read-only

Inspect

List the television stations available for TV search with their market, network, monitoring start date, and monitoring end date — every station by default, or only those matching the optional stations, network, and market filters (each an exact, case-insensitive match; combined with AND). activeCount and totalCount count the returned stations. Stations with an end date within the last 24 hours are flagged as active; stations with earlier end dates are discontinued. Use before querying to verify a station was active during the target time period, or to discover valid station IDs for the stations parameter in other TV tools. Most station monitoring ended October 2024 when the Internet Archive TV feed stopped updating.

ParametersJSON Schema

Name	Required	Description
`market`	No	Market to narrow to (e.g. "National", "San Francisco"), matched as a whole value case-insensitively after trimming — "National" does not match "NationalSpecialty". Values come from the market field of the unfiltered list. Blank is ignored.
`network`	No	Network to narrow to (e.g. "CNN", "ABC"), matched as a whole value case-insensitively after trimming — "FOX" does not match "FOXNEWS". Values come from the network field of the unfiltered list. Blank is ignored.
`stations`	No	Station IDs to return (e.g. ["CNN", "FOXNEWS", "MSNBC"]) — the IDs the stations parameter of the other TV tools takes. Matches any listed ID, exactly and case-insensitively after trimming; IDs that match no station are named in the notice. Blank entries are ignored; omit it or pass [] to include every station.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Filter outcome: names the filters when no station matched, and names requested station IDs that are not in the catalog or that another filter excluded. Absent when every requested ID was returned and the result is not empty.
`stations`	No	Stations matching every supplied filter — all stations when none is given — sorted by station ID.
`totalCount`	No	Number of stations returned — the whole catalog when no filter is given.
`activeCount`	No	Number of returned stations currently flagged as active.

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral context: activeCount/totalCount semantics, the active-vs-discontinued flag based on end date within 24 hours, and the important note that most station monitoring ended October 2024. These details help the agent interpret results correctly.

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 front-loaded with the core purpose and fields, then efficiently covers filters, counts, active status, usage, and historical context in five sentences. Every sentence contributes new, non-redundant information; no filler is present.

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

Completeness5/5

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

For a read-only listing tool with optional filters and an output schema, the description covers purpose, filter semantics, count behavior, active/discontinued logic, practical use, and the monitoring cutoff context. An agent has everything needed to decide when to call it and how to interpret responses.

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?

The input schema already provides 100% coverage with detailed, example-rich descriptions for market, network, and stations. The description adds only the AND-combination behavior and default-to-all behavior, which is useful but not a major lift beyond what the schema provides. 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?

The description uses a specific verb and resource ('List the television stations available for TV search') and clearly enumerates the returned fields (market, network, monitoring start/end date). It is immediately distinguishable from sibling tools like gdelt_search_tv or gdelt_get_tv_clips, which serve different purposes.

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 the tool: 'Use before querying to verify a station was active during the target time period, or to discover valid station IDs for the stations parameter in other TV tools.' It does not provide explicit when-not-to-use guidance, but the clear usage context earns a solid 4.

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

gdelt_search_articlesSearch GDELT ArticlesA

Read-only

Inspect

Search the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Fetches up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL, and returns as many as fit a 48,000-byte response — the rest are counted in withheldCount, with a continuation to reach them. Query supports full GDELT syntax: phrases ("bird flu"), boolean OR ((flu OR pandemic)), source country (sourcecountry:china), source language (sourcelang:spanish), domain (domain:who.int), GKG theme (theme:TAX_DISEASE_OUTBREAK — find identifiers with gdelt_search_themes), tone filter (tone<-5 for negative), proximity (near20:"flu virus"), and repeat (repeat3:"outbreak"). 250 is a hard per-call ceiling and GDELT offers no cursor: when a query fills it or a response comes back cut, re-query narrower startDatetime/endDatetime windows — the response hands back the exact windows to use. Note: this API covers only the most recent 3 months — use gdelt_search_tv for historical TV transcripts back to 2009.

ParametersJSON Schema

Name	Required	Description	Default
`sort`	No	Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency).	relevance
`query`	Yes	Search query. Supports GDELT operators: phrases ("bird flu"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:TAX_DISEASE_OUTBREAK (GKG theme identifiers come from gdelt_search_themes), tone<-5, near20:"flu virus", repeat3:"outbreak".
`timespan`	No	Time window relative to now, minimum "15min"; other examples: "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window.
`maxRecords`	No	Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead.
`endDatetime`	No	End of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must be supplied together with startDatetime; supplying only one of the two is rejected.
`startDatetime`	No	Start of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must be supplied together with endDatetime; supplying only one of the two is rejected.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget.
`articles`	No	Matching articles sorted per the sort parameter.
`timespan`	No	Echoed timespan parameter when provided.
`totalCount`	No	Number of articles returned in this response.
`withheldCount`	No	Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.
`continuationWindows`	No	Windows to re-run this query against, one at a time, when more articles are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further.

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, it discloses a 48,000-byte response budget, withheldCount with a continuation for overflow, a hard 250-per-call ceiling, the absence of a cursor, and how cut responses should be handled. This is substantive operational context that determines whether the agent trusts result counts.

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 long but appropriately so: scope, returned fields and truncation behavior, query syntax, pagination strategy, and the historical alternative each take one focused block. It is front-loaded with the core purpose and contains no filler or vague marketing language.

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

Completeness5/5

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

Given an output schema, rich input schema, and annotations covering side effects, the description covers the remaining operational essentials: time-window limits, result truncation and continuation, hard ceilings, and query syntax. An agent has enough to invoke it correctly and plan around GDELT's no-cursor limitation.

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%, and each parameter is already well documented with operators, formats, defaults, and constraints, so the description does not need to compensate. The prose mostly restates the 250 ceiling and window-splitting behavior that the maxRecords schema description already contains, adding little new per-parameter meaning.

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?

The first sentence names the action ('Search'), the resource ('last 3 months of global news coverage'), the backing API ('GDELT DOC API'), and the language scope (65+), then lists the concrete fields returned. It explicitly contrasts with gdelt_search_tv at the end, so the tool is distinguishable from its nearest sibling without opening schemas.

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

Usage Guidelines5/5

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

The description states both when to use this tool (recent 3-month news search) and when not to ('use gdelt_search_tv for historical TV transcripts back to 2009'). It also gives a concrete strategy for the pagination-limited case (re-query narrower startDatetime/endDatetime windows) and points to gdelt_search_themes for theme identifier lookup.

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

gdelt_search_themesSearch GDELT GKG ThemesA

Read-only

Inspect

Find GDELT Global Knowledge Graph (GKG) theme identifiers for the theme: operator that gdelt_search_articles, gdelt_get_coverage_timeline, gdelt_get_tone_distribution, and gdelt_get_coverage_breakdown accept in query. Searches the identifiers in the GDELT GKG theme lookup, which carries no labels or descriptions: every query word must begin one of the _-separated parts of an identifier or run across consecutive parts, or all the words joined must, so "drought" finds NATURAL_DISASTER_DROUGHT, "cyberattack" finds CYBER_ATTACK, "plant disease" finds TAX_PLANTDISEASE, and "wb water" narrows to World Bank water themes. There is no stemming or synonym matching — "displacement" does not reach DISPLACED — except one fallback: when nothing matches, the search retries once with a trailing s dropped from each word of four or more letters, and says so. Matches rank an exact identifier first, then by the count the lookup lists — a static prevalence figure, not a live article total — and each carries a paste-ready operator such as theme:TAX_DISEASE_OUTBREAK. Page with offset and limit.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum matches returned in this response (1–100).
`query`	Yes	Words to find in theme identifiers (e.g. "drought", "cyber attack", "refugee"), a family prefix with a word ("wb water", "crisislex"), or a whole identifier to confirm it is listed ("TAX_DISEASE_OUTBREAK"). Case-insensitive; a leading theme: is ignored; every word must match, or all the words joined must ("plant disease" matches TAX_PLANTDISEASE). Must contain at least one letter or digit.
`offset`	No	Zero-based offset into the ranked matches. Use nextOffset from the preceding response with the same query to retrieve the next page.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Maximum matches requested for this page.
`notice`	No	Search outcome: that the plural fallback supplied the matches and which words it tried, or, when nothing matched, how to retry. Absent when the query as given matched.
`offset`	No	Zero-based offset of this page.
`matches`	No	Matches on this page: an exact identifier match first, then by count descending, then by identifier.
`nextOffset`	No	Offset for the next page with the same query. Absent when this is the final page.
`totalCount`	No	Total themes matching the query — the same figure as totalMatches.
`totalMatches`	No	Total themes matching the query, across all pages.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond that: exact matching rules, the no-stemming/synonym limitation, the trailing-s retry fallback, ranking logic (exact identifier first, then static prevalence count), the paste-ready operator format, and pagination via offset/limit. It also discloses that the lookup carries no labels or descriptions and that the count is static, not live. No contradictions.

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 dense and every sentence carries essential information. It is front-loaded with purpose and consumers, then logically progresses through matching rules, fallback, ranking, operator format, and pagination. No filler or repetition; appropriate length given the complexity.

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

Completeness5/5

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

For a tool with intricate matching logic and an existing output schema, the description covers all operational aspects an agent needs: query formulation, edge cases, fallback, ranking, and pagination. The presence of an output schema means return-value details are handled elsewhere, so the description is complete for correct invocation and response interpretation.

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

Parameters5/5

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

Despite 100% schema description coverage, the description enriches all parameters. It explains query semantics with concrete examples (case-insensitivity, leading 'theme:' ignored, word joining, family prefixes), clarifies that limit bounds the response, and that offset works with the return metadata. It goes well beyond the schema's parameter descriptions.

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?

The description states a precise verb and resource: it finds GDELT GKG theme identifiers for the theme: operator. It explicitly names the sibling tools that accept these identifiers, distinguishing its role as a lookup helper rather than a search or analysis tool. The purpose is unmistakable and well-differentiated.

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

Usage Guidelines5/5

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

It clearly explains when to use it: to obtain theme: identifiers for the listed sibling tools. It also gives detailed query construction rules, matching semantics, and the fallback behavior, so an agent knows exactly how to invoke it and interpret results. It implicitly covers when not to use it (when you need article text, timeline data, etc.) by naming the consumers.

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

gdelt_search_tvSearch GDELT TV NewsA

Read-only

Inspect

Search US television news closed captions (2009–October 2024, 150+ stations) for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic. Use the stations parameter to select networks (e.g. ["CNN", "FOXNEWS", "MSNBC"]) — the TV API requires at least one station, supplied either there or as a station: selector inside query. TV query also supports in-query operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper 360", context:"vaccine". Important: most station monitoring ended October 2024 — use gdelt_list_tv_stations to verify active date ranges before querying recent events.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum timeline points returned in this response (1–500).
`query`	Yes	Search query for TV transcript content. Supports TV operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". Boolean OR and phrase operators also work.
`offset`	No	Zero-based point offset into the deterministic date-then-station ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page.
`dateres`	No	Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution.
`stations`	No	Up to 10 station IDs to filter to (e.g. ["CNN", "FOXNEWS", "MSNBC"]). 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 station IDs.
`timespan`	No	Time window, e.g. "1m", "6m", "1y". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024.
`normalize`	No	When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts.
`smoothing`	No	Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics.
`endDatetime`	No	End 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.
`startDatetime`	No	Start 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.

Output Schema

ParametersJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Maximum points requested for this page.
`notice`	No	Guidance when the query matched no TV coverage — the resolved timespan window, the October 2024 archive cutoff, and how to check station coverage. Absent when coverage was returned.
`offset`	No	Zero-based offset of this point page.
`series`	No	Station series represented in this point page.
`timeRange`	No	Date range spanned by this returned point page. Omitted when the page is empty.
`nextOffset`	No	Offset for the next page using the same query inputs. Absent when this is the final page.
`normalized`	No	True when values are normalized coverage percentages.
`totalCount`	No	Number of station series returned.
`totalPoints`	No	Total points available across all matched station series before pagination.
`dateResolution`	No	Temporal resolution of data points — as GDELT reported it, as requested via dateres, or inferred from the returned intervals. Omitted when none of those can establish it.
`effectiveQuery`	No	Echoed query string for use in follow-up calls.

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already mark it read-only, and the description adds substantial behavior beyond that: results are bounded and paged, per-station airtime is returned, and most station monitoring ended October 2024. It also warns agents to verify active date ranges before querying recent events, which is important operational context.

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?

Four sentences, front-loaded with purpose and return shape, then usage constraints and an important caveat. Every sentence carries operational value and there is no filler or redundant restating of the schema.

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

Completeness5/5

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

Given the output schema exists and parameter schema descriptions are thorough, the description supplies the operational glue: TV-specific query operators, required station handling, data range limits, and paging. Nothing critical appears missing for correct invocation.

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 every parameter with meaningful detail. The description adds useful cross-cutting guidance about station requirements, paging, and data coverage, but it does not need to repeat individual parameter semantics.

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?

States a specific verb ('Search'), resource ('US television news closed captions'), time/station scope, and return type ('bounded, paged per-station time series'). This clearly distinguishes it from sibling tools like gdelt_search_articles and gdelt_list_tv_stations.

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?

Clearly explains the mandatory stations requirement and how to satisfy it via the stations parameter or a station: selector, and names gdelt_list_tv_stations for verifying active date ranges. It does not explicitly contrast with gdelt_search_articles or the clip/context tools, so it stops short of full when/when-not routing.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesSep 24, 2026

Changedgdelt_get_coverage_breakdown1 field changed

changedInput schema / properties / query / description

Previous value: -"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:."New value: +"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes)."

Changedgdelt_get_coverage_timeline1 field changed

changedInput schema / properties / query / description

Previous value: -"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:, tone<."New value: +"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes), tone<."

Changedgdelt_get_tone_distribution1 field changed

changedInput schema / properties / query / description

Previous value: -"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:."New value: +"Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme: (GKG theme identifiers come from gdelt_search_themes)."

Changedgdelt_search_articles1 field changed

changedInput schema / properties / query / description

Previous value: -"Search query. Supports GDELT operators: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:DISEASE_OUTBREAK, tone<-5, near20:\"flu virus\", repeat3:\"outbreak\"."New value: +"Search query. Supports GDELT operators: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:TAX_DISEASE_OUTBREAK (GKG theme identifiers come from gdelt_search_themes), tone<-5, near20:\"flu virus\", repeat3:\"outbreak\"."

Addedgdelt_search_themes

9 tool updatesSep 24, 2026

Changedgdelt_get_coverage_breakdown5 fields changed

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dateResolution",
-      "topSeries",
-      "effectiveQuery",
-      "breakdownBy",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "topSeries",
+      "effectiveQuery",
+      "breakdownBy",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of data points — 15min, hour, or day."New value: +"Temporal resolution of data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_series`: A label passed in the series input matches no series in a non-empty breakdown. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_breakdown_data",
-  "unknown_series",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "unknown_series",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no breakdown data was returned. Absent on successful responses."New value: +"Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when breakdown data was returned."

Changedgdelt_get_coverage_timeline5 fields changed

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dateResolution",
-      "series",
-      "effectiveQuery",
-      "mode",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "series",
+      "effectiveQuery",
+      "mode",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of the data points — 15min, hour, or day."New value: +"Temporal resolution of the data points — 15min, hour, or day — inferred from the spacing of the returned timesteps. Omitted when fewer than two distinct timesteps came back."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_point`: A date passed in the points input matches no timestep in a non-empty timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_timeline_data",
-  "unknown_point",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "unknown_point",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no timeline data was returned. Absent on successful responses."New value: +"Guidance when the query matched no coverage in the window — how to broaden the query or extend the window. Absent when timeline data was returned."

Changedgdelt_get_tone_distribution8 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_tone_data",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no tone data was returned. Absent on successful responses."New value: +"Guidance when no articles matched in the window — how to broaden the query or extend the window. Absent when tone data was returned."

changedOutput schema / properties / summary / description

Previous value: -"Summary statistics derived from the histogram."New value: +"Summary statistics derived from the histogram. Each value is omitted when the histogram cannot support it — all of them on an empty result."

changedOutput schema / properties / summary / properties / neutralPct / description

Previous value: -"Percentage of articles in the near-neutral range (bins -2 to +2)."New value: +"Percentage of articles in the near-neutral range (bins -2 to +2). Omitted when the histogram counts no articles."

changedOutput schema / properties / summary / properties / peakNegativeBin / description

Previous value: -"Tone bin with the highest count among negative bins (bin < 0)."New value: +"Tone bin with the highest count among negative bins (bin < 0). Omitted when no negative bin was returned."

changedOutput schema / properties / summary / properties / peakPositiveBin / description

Previous value: -"Tone bin with the highest count among positive bins (bin > 0)."New value: +"Tone bin with the highest count among positive bins (bin > 0). Omitted when no positive bin was returned."

removedOutput schema / properties / summary / required

Removed value: -[
-  "peakNegativeBin",
-  "peakPositiveBin",
-  "neutralPct"
-]

Changedgdelt_get_tv_clips6 fields changed

changedInput schema / properties / maxRecords / description

Previous value: -"Maximum number of clips to return (1–3000). 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of clips to fetch (1–3000); the response carries as many of them as fit its 48,000-byte budget. 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead."

changedOutput schema / properties / continuationWindows / description

Previous value: -"The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 3000 ceiling. The halves overlap by one second so no clip falls through the seam; a clip aired on that second can come back in both, so de-duplicate by archiveUrl. Absent unless the ceiling was reached with a window that is both known and wide enough to divide."New value: +"Windows to re-run this query against, one at a time, when more clips are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned clip, reaching back to the second it aired, so clips from that second come back again — de-duplicate by archiveUrl — or, when resuming there cannot reach a new clip, one window skipping past that second. Otherwise — maxRecords at its 3000 ceiling, or a relevance cut — the queried window split in two, on a clock hour when one falls inside it; the halves share no second. Absent when no window is known, or none would reach further."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_clips",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Disclosure that the maxRecords cap was reached and more clips may exist, naming the route to them — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."New value: +"Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to target the 2009–October 2024 archive or verify station IDs. When GDELT returned clips aired outside the requested window (it answers whole clock hours), how many were dropped. When the response was cut to its 48,000-byte budget, how many clips it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more clips may exist — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget."

addedOutput schema / properties / withheldCount

Added value: +{
+  "description": "In-window clips GDELT returned that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting clips dropped for falling outside the window. Absent when every in-window clip fit.",
+  "type": "number"
+}

Changedgdelt_get_tv_context3 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_context",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no context was found. Absent on successful responses."New value: +"Guidance when no clips matched, so there is no vocabulary to report — the resolved timespan window, the October 2024 archive cutoff, and how to broaden the query or check station coverage. Absent when terms were returned."

Removedgdelt_get_tv_trending

Changedgdelt_list_tv_stations9 fields changed

addedInput schema / properties / market

Added value: +{
+  "description": "Market to narrow to (e.g. \"National\", \"San Francisco\"), matched as a whole value case-insensitively after trimming — \"National\" does not match \"NationalSpecialty\". Values come from the market field of the unfiltered list. Blank is ignored.",
+  "type": "string"
+}

addedInput schema / properties / network

Added value: +{
+  "description": "Network to narrow to (e.g. \"CNN\", \"ABC\"), matched as a whole value case-insensitively after trimming — \"FOX\" does not match \"FOXNEWS\". Values come from the network field of the unfiltered list. Blank is ignored.",
+  "type": "string"
+}

addedInput schema / properties / stations

Added value: +{
+  "description": "Station IDs to return (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]) — the IDs the stations parameter of the other TV tools takes. Matches any listed ID, exactly and case-insensitively after trimming; IDs that match no station are named in the notice. Blank entries are ignored; omit it or pass [] to include every station.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / activeCount / description

Previous value: -"Number of stations currently flagged as active."New value: +"Number of returned stations currently flagged as active."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data, including an empty station catalog. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_stations",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

addedOutput schema / properties / notice

Added value: +{
+  "description": "Filter outcome: names the filters when no station matched, and names requested station IDs that are not in the catalog or that another filter excluded. Absent when every requested ID was returned and the result is not empty.",
+  "type": "string"
+}

changedOutput schema / properties / stations / description

Previous value: -"All TV stations sorted by station ID."New value: +"Stations matching every supplied filter — all stations when none is given — sorted by station ID."

changedOutput schema / properties / totalCount / description

Previous value: -"Total number of stations in the list."New value: +"Number of stations returned — the whole catalog when no filter is given."

Changedgdelt_search_articles6 fields changed

changedInput schema / properties / maxRecords / description

Previous value: -"Maximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."

changedOutput schema / properties / continuationWindows / description

Previous value: -"The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. Absent unless the ceiling was reached with a window that is both known and wide enough to divide."New value: +"Windows to re-run this query against, one at a time, when more articles are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_articles",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Disclosure that the maxRecords cap was reached and more articles may exist, naming the route to them — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."New value: +"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget."

addedOutput schema / properties / withheldCount

Added value: +{
+  "description": "Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.",
+  "type": "number"
+}

Changedgdelt_search_tv6 fields changed

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dateResolution",
-      "timeRange",
-      "series",
-      "normalized",
-      "totalPoints",
-      "offset",
-      "limit",
-      "effectiveQuery",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "series",
+      "normalized",
+      "totalPoints",
+      "offset",
+      "limit",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of data points."New value: +"Temporal resolution of data points — as GDELT reported it, as requested via dateres, or inferred from the returned intervals. Omitted when none of those can establish it."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_tv_coverage",
-  "invalid_date_range",
-  "offset_out_of_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "invalid_date_range",
+  "offset_out_of_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no TV coverage was found. Absent on successful responses."New value: +"Guidance when the query matched no TV coverage — the resolved timespan window, the October 2024 archive cutoff, and how to check station coverage. Absent when coverage was returned."

changedOutput schema / properties / timeRange / description

Previous value: -"Date range spanned by this returned point page."New value: +"Date range spanned by this returned point page. Omitted when the page is empty."

7 tool updatesSep 22, 2026

Changedgdelt_get_coverage_breakdown1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_coverage_timeline1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tone_distribution1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tv_clips1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tv_context1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_search_articles1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_search_tv1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

9 tool updatesSep 19, 2026

Changedgdelt_get_coverage_breakdown1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_coverage_timeline1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tone_distribution1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tv_clips1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tv_context1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_get_tv_trending1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_trending`: No trending topics returned — the endpoint returned an empty list. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_trending`: No trending topics returned — the endpoint returned an empty list. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_list_tv_stations1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_search_articles1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Changedgdelt_search_tv1 field changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

4 tool updatesAug 31, 2026

Changedgdelt_get_coverage_breakdown2 fields changed

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of data points."New value: +"Temporal resolution of data points — 15min, hour, or day."

changedOutput schema / properties / dateResolution / enum

Previous value: -[
-  "hour",
-  "day"
-]New value: +[
+  "15min",
+  "hour",
+  "day"
+]

Changedgdelt_get_coverage_timeline2 fields changed

changedOutput schema / properties / dateResolution / description

Previous value: -"Temporal resolution of the data points — hour for short windows, day for longer."New value: +"Temporal resolution of the data points — 15min, hour, or day."

changedOutput schema / properties / dateResolution / enum

Previous value: -[
-  "hour",
-  "day"
-]New value: +[
+  "15min",
+  "hour",
+  "day"
+]

Changedgdelt_search_articles2 fields changed

changedInput schema / properties / sort / description

Previous value: -"Sort order: relevance (default), date (newest first), social (most socially shared)."New value: +"Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency)."

changedInput schema / properties / sort / enum

Previous value: -[
-  "date",
-  "relevance",
-  "social"
-]New value: +[
+  "relevance",
+  "dateDesc",
+  "dateAsc",
+  "toneDesc",
+  "toneAsc",
+  "hybridRel"
+]

Changedgdelt_search_tv17 fields changed

addedInput schema / properties / dateres

Added value: +{
+  "description": "Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution.",
+  "enum": [
+    "hour",
+    "day",
+    "week",
+    "month",
+    "year"
+  ],
+  "type": "string"
+}

addedInput schema / properties / limit

Added value: +{
+  "default": 500,
+  "description": "Maximum timeline points returned in this response (1–500).",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / normalize / description

Previous value: -"When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw coverage volume."New value: +"When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts."

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based point offset into the deterministic date-then-station ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / stations / description

Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]). 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 station IDs."New value: +"Up to 10 station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]). 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 station IDs."

addedInput schema / properties / stations / maxItems
```
Added value: +10
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "dateResolution",
-      "timeRange",
-      "series",
-      "normalized",
-      "effectiveQuery",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dateResolution",
+      "timeRange",
+      "series",
+      "normalized",
+      "totalPoints",
+      "offset",
+      "limit",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / dateResolution / enum

Previous value: -[
-  "hour",
-  "day",
-  "month"
-]New value: +[
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year"
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `offset_out_of_range`: The requested point offset is at or beyond the end of a non-empty timeline. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_tv_coverage",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_rate_limited",
-  "gdelt_unavailable"
-]New value: +[
+  "no_tv_coverage",
+  "invalid_date_range",
+  "offset_out_of_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

addedOutput schema / properties / limit

Added value: +{
+  "description": "Maximum points requested for this page.",
+  "type": "number"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset for the next page using the same query inputs. Absent when this is the final page.",
+  "type": "number"
+}

addedOutput schema / properties / offset

Added value: +{
+  "description": "Zero-based offset of this point page.",
+  "type": "number"
+}

changedOutput schema / properties / series / description

Previous value: -"One coverage series per explicitly selected station."New value: +"Station series represented in this point page."

changedOutput schema / properties / series / items / properties / data / items / properties / value / description

Previous value: -"Coverage value (normalized % or raw count)."New value: +"Coverage value (normalized % or raw matching 15-second clip count)."

changedOutput schema / properties / timeRange / description

Previous value: -"Date range spanned by the returned data."New value: +"Date range spanned by this returned point page."

addedOutput schema / properties / totalPoints

Added value: +{
+  "description": "Total points available across all matched station series before pagination.",
+  "type": "number"
+}

9 tool updatesAug 30, 2026

Changedgdelt_get_coverage_breakdown3 fields changed

changedInput schema / properties / timespan / description

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_breakdown_data",
-  "unknown_series",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_breakdown_data",
+  "unknown_series",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_get_coverage_timeline3 fields changed

changedInput schema / properties / timespan / description

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_timeline_data",
-  "unknown_point",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_timeline_data",
+  "unknown_point",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_get_tone_distribution3 fields changed

changedInput schema / properties / timespan / description

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum 3 months."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_tone_data",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_tone_data",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_get_tv_clips2 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_clips",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_clips",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_get_tv_context2 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_context",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_context",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_get_tv_trending2 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_trending`: No trending topics returned — the endpoint returned an empty list. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_trending`: No trending topics returned — the endpoint returned an empty list. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_trending",
-  "gdelt_unavailable"
-]New value: +[
+  "no_trending",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_list_tv_stations2 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_stations",
-  "gdelt_unavailable"
-]New value: +[
+  "no_stations",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_search_articles3 fields changed

changedInput schema / properties / timespan / description

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_articles",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_articles",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Changedgdelt_search_tv3 fields changed

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_tv_coverage",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_tv_coverage",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

changedOutput schema / properties / series / description

Previous value: -"One series per station or combined national coverage."New value: +"One coverage series per explicitly selected station."

9 tool updatesAug 22, 2026

Changedgdelt_get_coverage_breakdown6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dateResolution",
+      "topSeries",
+      "effectiveQuery",
+      "breakdownBy",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_breakdown_data`: No breakdown data returned for the query. `unknown_series`: A label passed in the series input matches no series in this breakdown. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_breakdown_data",
+            "unknown_series",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "dateResolution",
-  "topSeries",
-  "effectiveQuery",
-  "breakdownBy",
-  "totalCount"
-]

Changedgdelt_get_coverage_timeline6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dateResolution",
+      "series",
+      "effectiveQuery",
+      "mode",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_timeline_data`: No timeline data returned for the query and time range. `unknown_point`: A date passed in the points input matches no timestep in this timeline. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_timeline_data",
+            "unknown_point",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "dateResolution",
-  "series",
-  "effectiveQuery",
-  "mode",
-  "totalCount"
-]

Changedgdelt_get_tone_distribution6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "histogram",
+      "summary",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_tone_data`: No tone histogram data returned for the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_tone_data",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "histogram",
-  "summary",
-  "effectiveQuery",
-  "totalCount"
-]

Changedgdelt_get_tv_clips6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "clips",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_clips",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "clips",
-  "effectiveQuery",
-  "totalCount"
-]

Changedgdelt_get_tv_context6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "words",
+      "effectiveQuery"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_context`: No context words found — no clips matched the query. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_context",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "words",
-  "effectiveQuery"
-]

Changedgdelt_get_tv_trending6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "topics",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_trending`: No trending topics returned — the endpoint returned an empty list. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_trending",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "topics",
-  "totalCount"
-]

Changedgdelt_list_tv_stations6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "stations",
+      "activeCount",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_stations`: The station list returned empty — API may be temporarily unavailable. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_stations",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "stations",
-  "activeCount",
-  "totalCount"
-]

Changedgdelt_search_articles6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "articles",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_articles",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "articles",
-  "effectiveQuery",
-  "totalCount"
-]

Changedgdelt_search_tv6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "dateResolution",
+      "timeRange",
+      "series",
+      "normalized",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_tv_coverage`: No TV coverage found for the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_tv_coverage",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "dateResolution",
-  "timeRange",
-  "series",
-  "normalized",
-  "effectiveQuery",
-  "totalCount"
-]

4 tool updatesJul 16, 2026

Changedgdelt_get_coverage_breakdown3 fields changed

addedInput schema / properties / series

Added value: +{
+  "description": "Exact series labels to additionally return in full, e.g. [\"Portuguese\", \"Vietnamese\"]. Take them verbatim from otherSeriesLabels (the series folded into \"Other\") or topSeries[].label in a response, or from the label list an unknown_series error prints. Each one comes back complete under selectedSeries, on top of the usual top-10 overview; a label that matches nothing is rejected rather than silently skipped. Omit to get the overview alone.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / otherSeriesLabels

Added value: +{
+  "description": "Label of every series folded into otherAggregated, ranked by total volume — the identities the \"Other\" bucket would otherwise dissolve. Pass any of them to the series input to retrieve that series' complete data. Omitted when all series fit in the top 10.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / selectedSeries

Added value: +{
+  "description": "Complete, untruncated time series for each label requested via the series input, in the order requested. Omitted when series was not supplied.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A single language or country coverage series.",
+    "properties": {
+      "data": {
+        "description": "Time-ordered data points for this series.",
+        "items": {
+          "additionalProperties": false,
+          "description": "A single data point for this series.",
+          "properties": {
+            "date": {
+              "description": "Timestep in ISO 8601 format.",
+              "type": "string"
+            },
+            "value": {
+              "description": "Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "date",
+            "value"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "label": {
+        "description": "Series label (language name or country name).",
+        "type": "string"
+      }
+    },
+    "required": [
+      "label",
+      "data"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changedgdelt_get_coverage_timeline2 fields changed

addedInput schema / properties / points

Added value: +{
+  "description": "Timestep dates whose complete article list should be rendered in the text surface, e.g. [\"2024-01-05T12:00:00Z\"]. Take them verbatim from series[].data[].date in a prior response, or from the list an unknown_point error prints. Only affects volume_with_articles rendering — every timestep already carries its full article list in structuredContent regardless. Timesteps not named here show their first 3 links; a date matching no timestep is rejected rather than silently ignored.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / expandedPoints

Added value: +{
+  "description": "Timestep dates whose full article list is rendered in the text surface instead of the first 3, echoing the points input. Omitted when points was not supplied. Purely a rendering concern — structuredContent carries every article for every timestep either way.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changedgdelt_get_tv_clips3 fields changed

changedInput schema / properties / maxRecords / description

Previous value: -"Maximum number of clips to return (1–3000)."New value: +"Maximum number of clips to return (1–3000). 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead."

addedOutput schema / properties / continuationWindows

Added value: +{
+  "description": "The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 3000 ceiling. The halves overlap by one second so no clip falls through the seam; a clip aired on that second can come back in both, so de-duplicate by archiveUrl. Absent unless the ceiling was reached with a window that is both known and wide enough to divide.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One window to re-query with the same query string.",
+    "properties": {
+      "endDatetime": {
+        "description": "End of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      },
+      "startDatetime": {
+        "description": "Start of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "startDatetime",
+      "endDatetime"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no clips matched. Absent on successful responses."New value: +"Disclosure that the maxRecords cap was reached and more clips may exist, naming the route to them — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."

Changedgdelt_search_articles3 fields changed

changedInput schema / properties / maxRecords / description

Previous value: -"Maximum number of articles to return (1–250)."New value: +"Maximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."

addedOutput schema / properties / continuationWindows

Added value: +{
+  "description": "The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. Absent unless the ceiling was reached with a window that is both known and wide enough to divide.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One window to re-query with the same query string.",
+    "properties": {
+      "endDatetime": {
+        "description": "End of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      },
+      "startDatetime": {
+        "description": "Start of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "startDatetime",
+      "endDatetime"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no articles matched — echoes filters and suggests how to broaden. Absent on successful responses."New value: +"Disclosure that the maxRecords cap was reached and more articles may exist, naming the route to them — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."

1 tool updateJul 16, 2026

Changedgdelt_get_coverage_breakdown2 fields changed

changedOutput schema / properties / otherAggregated / items / properties / value / description

Previous value: -"Aggregated coverage volume for all remaining series."New value: +"Aggregated normalized coverage volume for all remaining series — a share of media output, not an absolute article count."

changedOutput schema / properties / topSeries / items / properties / data / items / properties / value / description

Previous value: -"Normalized coverage volume at this timestep."New value: +"Normalized coverage volume at this timestep — the topic's share of this source's media output, not an absolute article count."

7 tool updatesJul 16, 2026

Changedgdelt_get_coverage_breakdown4 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

Changedgdelt_get_coverage_timeline4 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

Changedgdelt_get_tone_distribution4 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must pair with startDatetime; supplying only one of the two is rejected."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must pair with endDatetime; supplying only one of the two is rejected."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

Changedgdelt_get_tv_clips5 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End 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."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start 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."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / stations / description

Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). Omit for all stations. Use gdelt_list_tv_stations to see valid IDs."New value: +"Station 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."

Changedgdelt_get_tv_context5 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End 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."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. TV data spans 2009–October 2024."New value: +"Start 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."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / stations / description

Previous value: -"Station IDs to filter to. Omit for all stations. Use gdelt_list_tv_stations to see valid IDs."New value: +"Station 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."

Changedgdelt_search_articles4 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240131235959). Must be used together with startDatetime."New value: +"End of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must be supplied together with startDatetime; supplying only one of the two is rejected."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240101000000). Must be used together with endDatetime."New value: +"Start of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must be supplied together with endDatetime; supplying only one of the two is rejected."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

Changedgdelt_search_tv5 fields changed

changedInput schema / properties / endDatetime / description

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End 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."

addedInput schema / properties / endDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / startDatetime / description

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start 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."

addedInput schema / properties / startDatetime / pattern
```
Added value: +"^\\d{14}$"
```

changedInput schema / properties / stations / description

Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]). Omit to get coverage across all available stations. Use gdelt_list_tv_stations to see valid station IDs."New value: +"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\", \"MSNBC\"]). 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 station IDs."

4 tool updatesJun 8, 2026

Changedgdelt_get_coverage_breakdown2 fields changed

addedOutput schema / properties / endDatetime

Added value: +{
+  "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

addedOutput schema / properties / startDatetime

Added value: +{
+  "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

Changedgdelt_get_coverage_timeline2 fields changed

addedOutput schema / properties / endDatetime

Added value: +{
+  "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

addedOutput schema / properties / startDatetime

Added value: +{
+  "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

Changedgdelt_get_tone_distribution2 fields changed

addedOutput schema / properties / endDatetime

Added value: +{
+  "description": "Echoed end datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

addedOutput schema / properties / startDatetime

Added value: +{
+  "description": "Echoed start datetime when provided (YYYYMMDDHHMMSS).",
+  "type": "string"
+}

Changedgdelt_get_tv_context3 fields changed

addedInput schema / properties / endDatetime

Added value: +{
+  "description": "End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime.",
+  "type": "string"
+}

addedInput schema / properties / startDatetime

Added value: +{
+  "description": "Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. TV data spans 2009–October 2024.",
+  "type": "string"
+}

changedInput schema / properties / timespan / description

Previous value: -"Time window, e.g. \"1m\", \"6m\". TV data spans 2009–October 2024."New value: +"Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024."

1 tool updateJun 4, 2026

Changedgdelt_get_tv_context2 fields changed

changedOutput schema / properties / totalCount / description

Previous value: -"Number of matching clips from which co-occurrences were computed."New value: +"Number of clips from which co-occurrences were computed. Absent when the upstream API does not return a clip count."

changedOutput schema / required

Previous value: -[
-  "words",
-  "effectiveQuery",
-  "totalCount"
-]New value: +[
+  "words",
+  "effectiveQuery"
+]

8 tool updatesMay 30, 2026

Changedgdelt_get_coverage_breakdown7 fields changed

changedOutput schema / properties / breakdownBy / description

Previous value: -"Breakdown dimension used."New value: +"Breakdown dimension used for this response."

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no data was returned. Absent on successful responses."New value: +"Recovery hint when no breakdown data was returned. Absent on successful responses."

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

removedOutput schema / properties / seriesCount

Removed value: -{
-  "description": "Total number of series before truncation to top 10.",
-  "type": "number"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total number of series returned before truncation to top 10.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "breakdownBy",
-  "dateResolution",
-  "topSeries",
-  "seriesCount"
-]New value: +[
+  "dateResolution",
+  "topSeries",
+  "effectiveQuery",
+  "breakdownBy",
+  "totalCount"
+]

Changedgdelt_get_coverage_timeline6 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

changedOutput schema / properties / mode / description

Previous value: -"Timeline mode used."New value: +"Timeline mode used for this response."

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no data was returned. Absent on successful responses."New value: +"Recovery hint when no timeline data was returned. Absent on successful responses."

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total number of data points across all series.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "mode",
-  "dateResolution",
-  "series"
-]New value: +[
+  "dateResolution",
+  "series",
+  "effectiveQuery",
+  "mode",
+  "totalCount"
+]

Changedgdelt_get_tone_distribution5 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no data was returned. Absent on successful responses."New value: +"Recovery hint when no tone data was returned. Absent on successful responses."

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total number of articles across all histogram bins.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "histogram",
-  "summary"
-]New value: +[
+  "histogram",
+  "summary",
+  "effectiveQuery",
+  "totalCount"
+]

Changedgdelt_get_tv_clips5 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Number of clips returned.",
+  "type": "number"
+}

removedOutput schema / properties / totalReturned

Removed value: -{
-  "description": "Number of clips returned.",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "query",
-  "clips",
-  "totalReturned"
-]New value: +[
+  "clips",
+  "effectiveQuery",
+  "totalCount"
+]

Changedgdelt_get_tv_context5 fields changed

removedOutput schema / properties / clipsAnalyzed

Removed value: -{
-  "description": "Number of matching clips from which co-occurrences were computed.",
-  "type": "number"
-}

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Number of matching clips from which co-occurrences were computed.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "words",
-  "clipsAnalyzed"
-]New value: +[
+  "words",
+  "effectiveQuery",
+  "totalCount"
+]

Changedgdelt_get_tv_trending2 fields changed

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no topics were returned. Absent on successful responses."New value: +"Recovery hint when no trending topics were returned. Absent on successful responses."

changedOutput schema / properties / totalCount / description

Previous value: -"Number of trending topics returned."New value: +"Total number of trending topics returned."

Changedgdelt_search_articles5 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string for use in follow-up calls.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Number of articles returned in this response.",
+  "type": "number"
+}

removedOutput schema / properties / totalReturned

Removed value: -{
-  "description": "Number of articles returned in this response.",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "articles",
-  "totalReturned",
-  "query"
-]New value: +[
+  "articles",
+  "effectiveQuery",
+  "totalCount"
+]

Changedgdelt_search_tv5 fields changed

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no coverage was found. Absent on successful responses."New value: +"Recovery hint when no TV coverage was found. Absent on successful responses."

removedOutput schema / properties / query

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Number of station series returned.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "dateResolution",
-  "timeRange",
-  "series",
-  "normalized"
-]New value: +[
+  "dateResolution",
+  "timeRange",
+  "series",
+  "normalized",
+  "effectiveQuery",
+  "totalCount"
+]

9 tool updatesMay 29, 2026
- First observedgdelt_get_coverage_breakdown
- First observedgdelt_get_coverage_timeline
- First observedgdelt_get_tone_distribution
- First observedgdelt_get_tv_clips
- First observedgdelt_get_tv_context
- First observedgdelt_get_tv_trending
- First observedgdelt_list_tv_stations
- First observedgdelt_search_articles
- First observedgdelt_search_tv

Related MCP Connectors

GDELT Global Events A
io.github.guptaprakhariitr
Geopolitical event detection, tone timeseries, actor trends from GDELT 2.0.
Research & Data Open Data
321
Webz.io News SearchOAuth
io.webz
Search global news in natural language. Filter by language, country, date, sentiment, and domain.
Search Open Data
12
Gdelt A
io.github.pipeworx-io
GDELT MCP — Global Database of Events, Language, and Tone (free, no auth)
Open Data Research & Data
4021
APITube News A
io.apitube
Real-time news search across 500,000+ sources in 60+ languages with sentiment and entities.
Search Entertainment & Media
21

Related MCP Servers

gdelt-events-mcp
Search Open Data Research & Data
guptaprakhariitr
F
license
Not graded
quality
D
maintenance
Enables macro/geopolitical event detection by wrapping the GDELT 2.0 API, providing tools for searching events, trending actors, and sentiment timeseries from global news.
Updated 4 months ago (2026-06-11 08:39 UTC)
1
-
GDELT MCP Server
Search Research & Data
MissionSquad
A
license
A
quality
D
maintenance
Provides access to the GDELT DOC 2.0 API for searching global news articles and images across 65 languages with customizable timespans and query options.
Updated a year ago (2025-10-24 06:01 UTC)
2
9 npm
2
MIT
gdelt-mcp
Search Open Data Research & Data
nadirdev1
A
license
Not graded
quality
B
maintenance
Enables AI assistants to search worldwide news articles, generate coverage timelines, and analyze topic trends through the GDELT DOC 2.0 API, with rate limiting, caching, and error handling.
Updated 7 days ago (2026-09-23 16:57 UTC)
228 npm
MIT
GDELT MCP
Search Research & Data
mjtahir02-alt
A
license
Not graded
quality
B
maintenance
A remote, read-only MCP server for global media intelligence using GDELT DOC 2.0 API, enabling search and analysis of multilingual news coverage, tone, and attention trends.
Updated 2 months ago (2026-07-16 10:44 UTC)
228 npm
MIT

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Server Details

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Related MCP Connectors

Related MCP Servers

Glama MCP Gateway

Resources