gdelt-mcp-server
Server Details
Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/gdelt-mcp-server
- GitHub Stars
- 1
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 9 of 9 tools scored.
Each tool targets a distinct aspect of GDELT data (coverage breakdown, timeline, tone distribution, TV clips, TV context, trending, station listing, article search, TV search). Descriptions explicitly clarify differences (e.g., gdelt_get_tone_distribution vs. gdelt_get_coverage_timeline with mode tone).
All tools follow a consistent 'gdelt_verb_noun' pattern with snake_case. Verbs are either get, list, or search, and nouns clearly indicate the resource or action. No mixed conventions.
With 9 tools, the server covers the core GDELT functionalities (coverage analysis, article search, TV content) without being too sparse or overly numerous. Each tool earns its place.
The tool set provides a comprehensive surface for news coverage analysis and TV transcript search. Minor gaps exist (e.g., no direct access to GKG or event data), but the server's scope is clear and the tools handle the primary use cases well.
Available Tools
9 toolsgdelt_get_coverage_breakdownGet GDELT Coverage BreakdownARead-onlyInspect
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; remaining series are aggregated into an "Other" bucket. Use breakdownBy "country" with the signal-detection chain to map geographic attention, or "language" to detect non-English media surges.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:. | |
| timespan | No | Time window relative to now, e.g. "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. Must pair with startDatetime. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Echoed query string. |
| notice | No | Recovery hint when no data was returned. Absent on successful responses. |
| topSeries | Yes | Top 10 series by total coverage volume. |
| breakdownBy | Yes | Breakdown dimension used. |
| seriesCount | Yes | Total number of series before truncation to top 10. |
| dateResolution | Yes | Temporal resolution of data points. |
| otherAggregated | No | Combined time series for all series beyond the top 10. Omitted when all series fit. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return limit of 10 series with remaining aggregated into 'Other' bucket, adding behavioral context beyond annotations (readOnlyHint, openWorldHint). 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste. Front-loaded with core action and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description need not detail return values. Covers purpose, usage hints, and behavioral limits. Adequate for a query-based breakdown tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds value for breakdownBy (use case) and query (reference to sibling tool). Other parameters not elaborated beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it breaks down news coverage volume by source language or country, returning multi-series time series. Differentiates from sibling tools like gdelt_get_coverage_timeline which likely provides overall timeline without breakdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use breakdownBy 'country' for geographic attention, 'language' for non-English surges. Suggests usage with signal-detection chain. Lacks explicit when-not-to-use compared to siblings.
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 TimelineARead-onlyInspect
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 automatically chosen based on timespan: hours for short windows, days for longer ones. Note: DOC API covers only the last 3 months.
| 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:, tone<. | |
| timespan | No | Time window relative to now, e.g. "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. Must pair with startDatetime. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| mode | Yes | Timeline mode used. |
| query | Yes | Echoed query string. |
| notice | No | Recovery hint when no data was returned. Absent on successful responses. |
| series | Yes | One or more time series (typically one for volume/tone, one per label for breakdowns). |
| dateResolution | Yes | Temporal resolution of the data points — hour for short windows, day for longer. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint. The description adds behavioral context: auto date resolution, mode-specific outputs, coverage intensity vs tone, and the 3-month window limitation. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then mode explanations, then technical details. It is fairly concise but could be slightly more compact; however, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, output schema, multiple modes), the description covers all essential aspects: purpose, mode usage, date handling, data limitation. The output schema is not described but exists, so no gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The description adds value by explaining mode semantics and recommending usage patterns, but the schema already captures parameter details well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a time series of news coverage spikes or tone shifts, with three distinct modes (volume, volume_with_articles, tone). It explicitly distinguishes from sibling tool gdelt_search_articles by noting that volume_with_articles avoids a follow-up call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each mode, recommends volume_with_articles as the primary signal-detection mode, and notes the 3-month limit. It contrasts with gdelt_search_articles, making the choice clear.
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 DistributionARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query using GDELT syntax. Same operators as gdelt_search_articles: phrases, boolean OR, sourcecountry:, sourcelang:, domain:, theme:. | |
| timespan | No | Time window relative to now, e.g. "24h", "7d", "1m". Ignored when startDatetime/endDatetime are set. Maximum 3 months. | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Echoed query string. |
| notice | No | Recovery hint when no data was returned. Absent on successful responses. |
| summary | Yes | Summary statistics derived from the histogram. |
| histogram | Yes | Tone histogram sorted from most negative to most positive bin. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior. The description adds value by explaining the histogram's structure and interpretative insights, but does not reveal any additional behavioral traits beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the core functionality and adds the critical distinction from a sibling. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. It explains the bin range, interpretative use, representative URLs, and how it differs from the timeline tool, making it complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage of parameters with descriptions. The description adds minimal extra semantic value, only referencing the query syntax similarity to a sibling tool. Baseline 3 is appropriate since schema covers the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets tonal distribution as a histogram with bins -30 to +30, and distinguishes it from a single average tone score. It also explicitly differentiates from the sibling tool gdelt_get_coverage_timeline (mode: tone), making the purpose highly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus the alternative (snapshot vs. time series), and even suggests using gdelt_get_coverage_timeline for sentiment over time. This is excellent contextual advice.
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 ClipsARead-onlyInspect
Retrieve the top matching TV news clips (up to 3,000) for a query from the Internet Archive's Television News Archive. 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. Archive coverage spans 2009–October 2024.
| 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"]). Omit for 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 return (1–3000). | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| clips | Yes | Matching TV clips sorted per the sort parameter. |
| query | Yes | Echoed query string. |
| notice | No | Recovery hint when no clips matched. Absent on successful responses. |
| totalReturned | Yes | Number of clips returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description adds value by detailing output fields (show name, station, timestamp, transcript excerpt, link) and archive date range (2009-Oct 2024). 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-loaded with the core purpose, followed by output details and usage guideline. No redundant information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, output schema), the description covers purpose, usage context, and key constraints (max 3000, archive range). Output schema exists, so return values are not required. Minor omission: no explicit mention of rate limits or error handling, but openWorldHint mitigates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds little beyond what the schema already provides (e.g., archive span, query operators). Baseline 3 applies as the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves top matching TV news clips up to 3,000 for a query, specifying verb (retrieve), resource (TV news clips), and scope. It distinguishes itself from siblings by explicitly mentioning use after gdelt_search_tv to read transcript content, which aligns with the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific use case: 'Use after gdelt_search_tv to read the actual transcript content driving a coverage spike.' This gives context and differentiation from other tools, but lacks explicit exclusions or when-not-to-use scenarios.
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 ContextARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. Omit for all stations. Use gdelt_list_tv_stations to see valid IDs. | |
| timespan | No | Time window, e.g. "1m", "6m". TV data spans 2009–October 2024. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Echoed query string. |
| words | Yes | Co-occurring terms sorted by score descending. |
| notice | No | Recovery hint when no context was found. Absent on successful responses. |
| clipsAnalyzed | Yes | Number of matching clips from which co-occurrences were computed. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint and openWorldHint annotations by explaining the output format: 'Returns the most frequent non-stopword terms from matching clips, with relative frequency scores (0–100, where 100 = the query term itself).' It also notes the data span. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences covering purpose, output, and use cases. No wasted words; front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description explains the return values (terms, frequency scores). It includes data time range and query syntax hints. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the description does not need to add much. It does mention the data span for timespan, but that is already in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves co-occurring words and phrases from TV news clips, specified as 'get the top co-occurring words and phrases from TV news clips matching a query.' It distinguishes itself from siblings like gdelt_get_tv_clips and gdelt_search_tv by focusing on vocabulary framing rather than clips or searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms.' It does not explicitly state when not to use or list alternatives, but the use cases are clear and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gdelt_get_tv_trendingGet GDELT TV TrendingARead-onlyInspect
Retrieve trending topics, keywords, and phrases currently dominating US television news across national networks. No query required — returns the top memes of the present news cycle. Updated every 15 minutes. Note: the GDELT TV archive feed stopped updating around October 2024; results from this endpoint reflect that most-recent archived data rather than a live feed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Recovery hint when no topics were returned. Absent on successful responses. |
| topics | Yes | Trending topics sorted by score descending. |
| totalCount | Yes | Number of trending topics returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant value beyond annotations by noting the 15-minute update cycle and the important limitation that the archive feed stopped updating around October 2024, meaning results reflect archived data. This directly helps the agent understand the tool's temporal scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first states the core function, the second adds critical context about update frequency and data source limitation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects, and an output schema), the description covers the purpose, update frequency, and data recency limitation. It is complete for an agent to understand when and how to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description appropriately adds no additional parameter semantics since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves trending topics, keywords, and phrases dominating US television news, with no query needed. It distinguishes itself from siblings like gdelt_search_tv by explicitly stating 'no query required' and focusing on current trending data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool vs alternatives like gdelt_search_tv or other siblings. It implies usage for getting trending topics without a query but lacks explicit guidance on when to avoid it or what to use instead.
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 StationsARead-onlyInspect
List all television stations available for TV search with their market, network, monitoring start date, and monitoring end date. 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| stations | Yes | All TV stations sorted by station ID. |
| totalCount | Yes | Total number of stations in the list. |
| activeCount | Yes | Number of stations currently flagged as active. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that stations are flagged active if end date is within last 24 hours, otherwise discontinued, and notes that most monitoring ended October 2024. This adds significant behavioral context beyond the readOnlyHint annotation, with 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first states purpose and output fields, second explains active/discontinued logic and usage, third adds historical context. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema, the description fully covers what the tool does, how to interpret results, when to use it, and a relevant historical update. Nothing essential is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for zero parameters is 4; the description does not need to add param info. No param-related details are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all TV stations with market, network, monitoring start/end dates, and explains the active/discontinued flag. This verb+resource definition distinguishes it from sibling tools focused on coverage, tone, clips, or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool before querying to verify station activity during a target time period or to discover valid station IDs for other TV tools. Provides clear when-to-use context and implies it is a prerequisite for station-specific tools.
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 ArticlesARead-onlyInspect
Search the last 3 months of global news coverage (65+ languages) using the GDELT DOC API. Returns up to 250 articles with URL, title, source domain, language, country, publication date, and social image URL. 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:DISEASE_OUTBREAK), tone filter (tone<-5 for negative), proximity (near20:"flu virus"), and repeat (repeat3:"outbreak"). Note: this API covers only the most recent 3 months — use gdelt_search_tv for historical TV transcripts back to 2009.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order: relevance (default), date (newest first), social (most socially shared). | relevance |
| query | Yes | 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". | |
| timespan | No | 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. | |
| maxRecords | No | Maximum number of articles to return (1–250). | |
| endDatetime | No | End of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240131235959). Must be used together with startDatetime. | |
| startDatetime | No | Start of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240101000000). Must be used together with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Echoed query string for use in follow-up calls. |
| notice | No | Recovery hint when no articles matched — echoes filters and suggests how to broaden. Absent on successful responses. |
| articles | Yes | Matching articles sorted per the sort parameter. |
| timespan | No | Echoed timespan parameter when provided. |
| totalReturned | Yes | Number of articles returned in this response. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds behavioral context: covers last 3 months, returns limited fields, and details query syntax support. No contradictions. Adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense but efficient, front-loading purpose and return fields, then detailing syntax. Each sentence adds value; no wasted words. Slightly long due to syntax list, but necessary for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (6 params, rich query syntax, date ranges) and presence of output schema (not shown but indicated), description covers key aspects: time limit, return fields, operator examples, parameter interactions. Complete for effective tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining query operators, note about start/end datetime pair requirement, and timespan limitation. Goes beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Search', resource 'GDELT DOC API' for global news coverage, and explicitly distinguishes from sibling tool gdelt_search_tv by noting the 3-month limit. Purpose is distinct and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit when-to-use (last 3 months of news) and when-not-to-use (historical TV transcripts), directing to gdelt_search_tv as alternative. This is excellent usage guidance.
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 NewsARead-onlyInspect
Search US television news closed captions (2009–October 2024, 150+ stations) for spoken mentions of a query. Returns a normalized per-station time series showing relative airtime devoted to the topic. Use the stations parameter to compare specific networks (e.g. ["CNN", "FOXNEWS", "MSNBC"]); omit to get combined national coverage. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| stations | No | 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. | |
| 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 coverage volume. | |
| smoothing | No | Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics. | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime. |
Output Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Echoed query string. |
| notice | No | Recovery hint when no coverage was found. Absent on successful responses. |
| series | Yes | One series per station or combined national coverage. |
| timeRange | Yes | Date range spanned by the returned data. |
| normalized | Yes | True when values are normalized coverage percentages. |
| dateResolution | Yes | Temporal resolution of data points. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only behavior consistent with annotations. Adds important context: data range (2009–October 2024), normalization behavior, smoothing parameter effect, and the critical limitation that most station monitoring ended. This goes beyond the annotations' readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying distinct and essential information. First sentence defines purpose, second explains stations usage, third lists query operators, fourth warns about data availability and suggests a sibling tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 exists), the description covers all major aspects: purpose, parameter usage, data range, operator syntax, and limitations. References sibling tool for station verification, ensuring the agent has context to avoid errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds value by explaining how to use stations for comparison, the effect of normalize, and the smoothing window. It also clarifies the timespan vs start/endDatetime precedence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it searches US TV news closed captions for spoken mentions and returns a per-station time series. The verb 'search' and resource 'US television news closed captions' are specific. It differentiates from sibling tools like gdelt_get_tv_clips and gdelt_search_articles by focusing on transcript-level time series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use 'stations' parameter to compare networks, omit for combined national coverage. Warns about data ending in October 2024 and directs to gdelt_list_tv_stations for active date ranges. Also mentions in-query operators for advanced filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!