gdelt-mcp-server

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

The description goes far beyond the readOnlyHint annotation by disclosing key behaviors: values are normalized ('each point is the topic's share of media output, not an absolute article count'), the ranking implication ('Small media markets with concentrated coverage therefore rank above large markets'), and the 'Other' bucket aggregation with verbose labels. It also explains error handling for bad series labels in the schema, but the main description adds significant interpretive context. 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 dense but every sentence earns its place: core function, use cases, bucket behavior, normalization caveat, and mode-specific guidance. It is front-loaded with the primary purpose in the first sentence, and no redundant or filler content is present. The length is justified by the tool's complexity.

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, an output schema exists, and annotations declare read-only/open-world hints, the description still adds essential context: the normalization semantics, the 'Other' bucket behavior, and the practical interpretations for 'country' vs. 'language'. This fully equips an agent to select and invoke the tool correctly without needing to infer hidden behaviors.

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?

With 100% schema coverage, the baseline is 3. The description adds meaning beyond the schema by explaining how to use the series parameter ('pass any of those labels back as the series input to get that series complete, ranked or not') and how breakdownBy choice affects interpretation (geographic vs. language surge). This supplemental guidance elevates it above the baseline.

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 opens with a specific action and resource: 'Break down news coverage volume over time by source language or source country, returning a multi-series time series.' This clearly distinguishes it from siblings like gdelt_get_coverage_timeline (which likely shows an overall timeline) and gdelt_get_tone_distribution (tone analysis). The verb 'break down' and the breakdownBy dimension make the tool's purpose unmistakable.

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 concrete usage guidance: 'Use breakdownBy "country" with the signal-detection chain to map geographic attention, or "language" to detect non-English media surges.' It also explains how to drill down into 'Other' series by passing labels back via the series parameter. However, it does not explicitly state when not to use this tool or name alternatives, so it stops short of the full 5.

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

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

The description adds substantial behavioral context beyond the readOnly/openWorld annotations: automatic date-resolution selection, rendering behavior of article links (first 3 vs full list via points), handling of unknown timesteps, and the 3-month DOC API coverage limit. These details meaningfully inform invocation and interpretation without contradicting 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 a dense paragraph but front-loaded with the core purpose and mode guidance. Every sentence carries useful information, though the prose could be broken into bullets for readability. No wasted words, but slightly long given the redundant mode explanations already present in the schema descriptions.

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 output schema exists, the description does not need to explain return values, and it covers key constraints (3-month limit, automatic date resolution, text-surface behavior, unknown_point errors). It provides enough operational context for correct use alongside seven parameters and rich annotations, making the tool complete to invoke blindly.

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, but the description enriches the mode semantics (especially volume_with_articles as 'primary signal-detection mode') and explains the points parameter's rendering effects. It does not deeply explain smoothing or datetime pairing, as the schema already covers those, so it earns a 4 rather than 5.

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 opens with a specific verb+resource ('Retrieve a time series') and clarifies the tool's scope via three distinct modes (volume, volume_with_articles, tone). It distinguishes itself from siblings by emphasizing time-series output and explicitly references gdelt_search_articles as an alternative that this tool can make unnecessary.

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 when-to-use guidance for each mode ('Use mode "volume" for...', 'Use mode "volume_with_articles" for...', 'Use mode "tone" for...'). It also names an alternative tool (gdelt_search_articles) and explains when this tool avoids a follow-up call, satisfying the when/when-not/alternatives criterion.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower. The description adds valuable behavioral context: bins are approximately -30 to +30, each bin includes representative article URLs, and the result is a snapshot distribution across all matching articles. This goes beyond the annotations without contradicting them.

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 three sentences, each earning its place: defining the histogram, explaining why it's useful, and differentiating from the timeline tool. It is front-loaded with the core purpose and contains no filler.

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 a full output schema and complete parameter schema coverage, the description covers the remaining context: the nature of the histogram, the semantic difference from a single tone score, and the alternative tool for time-series analysis. It is complete for this 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description references 'query' but does not add new semantic detail beyond the schema, meeting the baseline but not exceeding it.

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's purpose: getting the tonal distribution of articles as a histogram, with a specific bin range (-30 to +30). It explicitly distinguishes itself from gdelt_get_coverage_timeline (mode: tone), making its unique function clear.

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 when-to-use guidance by contrasting with a single average tone score and with gdelt_get_coverage_timeline. It even names the alternative tool and mode ('tone') for time-series sentiment analysis, which is a clear exclusion.

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

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

Despite readOnlyHint and openWorldHint annotations, the description adds critical behavioral context: the hard 3,000-per-call ceiling, the lack of a cursor, and the instruction to split queries using time windows. It also discloses the archive's coverage span (2009–October 2024) and the response's behavior of returning exact windows to use. This goes well beyond the 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 compact yet information-dense. It front-loads the core purpose, then supplies relevant usage context, a key limitation, and a temporal boundary. Each sentence earns its place without redundancy or filler.

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 params, output schema), the description covers the tool's purpose, its role in the workflow (after gdelt_search_tv), the pagination limitation, and the archive's time span. The output schema handles return-value details, so the description remains focused on behavior and constraints, making it complete for an agent to invoke correctly.

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 documentation covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds semantic value by linking the maxRecords ceiling to the startDatetime/endDatetime splitting strategy, which is not explicitly stated in the schema. This helps the agent understand how the parameters interact in practice.

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 states a clear verb ('Retrieve') and resource ('top matching TV news clips'), and specifies what each clip includes. It also distinguishes the tool from siblings like gdelt_get_coverage_breakdown or gdelt_get_tv_trending by focusing on transcript content, making the tool's unique purpose unambiguous.

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 explicitly says 'Use after gdelt_search_tv', providing clear sequencing/context. It also gives practical guidance for handling the 3,000-clip ceiling by splitting into narrower startDatetime/endDatetime windows. However, it doesn't explicitly contrast with alternative sibling tools (e.g., when not to use gdelt_get_tv_context), so it stops short of full alternative differentiation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which covers safety. The description adds valuable behavioral detail beyond annotations: returns non-stopword terms, relative frequency scores 0–100 with 100 meaning the query term itself, and the TV data timespan (2009–October 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?

The description is concise and front-loaded: first sentence states purpose, second explains output format, third gives usage scenarios, and fourth adds temporal scope. No wasted sentences; every line 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 tool has an output schema, rich input schema, and annotations, the description covers purpose, output semantics, use cases, and data span. It doesn't need to explain return values or safety (already in schema/annotations). Slight repetition of the data span in the schema is minor, but overall the description is suitably complete.

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 input schema already provides rich parameter details (e.g., query operators, station requirements, datetime format rules). The description adds minimal parameter-specific meaning beyond 'matching a query,' so the 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's function: 'Get the top co-occurring words and phrases from TV news clips matching a query' and explains what it returns. It distinguishes itself from siblings like gdelt_search_tv (search results) and gdelt_get_tv_clips (clips) by focusing on vocabulary/framing.

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 name alternatives or exclusion criteria, but the use-case guidance is clear enough for an agent to decide when to invoke it.

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

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

Goes beyond the readOnly/openWorld annotations by disclosing the 15-minute update frequency and the critical caveat that the GDELT TV archive feed stopped updating around October 2024, so results are stale archived data rather than live. This is essential behavioral context for an AI agent.

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, tightly packed with useful information: the purpose, scope, no-query requirement, update cadence, and the data staleness warning. No filler or repetition; 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?

For a zero-parameter tool with an output schema, the description fully covers what the agent needs: purpose, source, update frequency, and a clear data-freshness caveat. The output schema handles return values, so no extra explanation is needed.

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 tool has zero parameters and schema coverage is 100%, which yields a baseline of 4. The description adds value by stating 'No query required,' explaining why the input schema is empty and reinforcing that no parameter is needed.

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 uses a specific verb ('Retrieve') and clearly identifies the resource (trending topics, keywords, and phrases dominating US television news) and scope (national networks). It stands apart from sibling tools like gdelt_search_tv and gdelt_get_tv_clips by focusing on the top 'memes' of the current news cycle.

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 clear context: 'No query required — returns the top memes of the present news cycle' signals this is for a high-level overview of current trends. However, it does not explicitly name alternatives or say when not to use it, though sibling tool names imply such distinctions.

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

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

Annotations declare readOnlyHint=true, and the description aligns with that. It adds valuable behavior beyond annotations: the flagging logic for active/discontinued stations based on 24-hour thresholds, and the critical context that monitoring ended October 2024. This transparency helps 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.

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

The description is four sentences, each delivering critical information: purpose, active/discontinued interpretation, usage context, and monitoring end date. It is front-loaded with the main purpose and contains no fluff or repetition.

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?

For a parameterless listing tool with an output schema, the description fully covers what the tool does, how to interpret its results, when to use it, and an important external constraint (Internet Archive TV feed ending). The output schema handles return format specifics, so no additional return-value explanation is needed.

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 tool has zero parameters, so parameter semantics are a non-issue. The baseline for no parameters is 4, and the description appropriately focuses on the output semantics (what station metadata is returned and how to interpret the dates).

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 begins with a clear verb and resource: 'List all television stations available for TV search' and specifies the returned fields (market, network, monitoring dates). It is distinct from sibling tools like search_tv or get_tv_clips, as it focuses on station metadata, not content or analysis.

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 explicitly states 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.' It does not explicitly mention when not to use it or name alternatives, but the guidance is specific and actionable within the context of sibling TV tools.

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

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

Even with readOnlyHint and openWorldHint annotations, the description adds crucial behavioral context: the hard 250 per-call ceiling, absence of cursor pagination, the need to split runs into narrower windows, and that the response returns the exact windows to use. This goes well beyond annotations and no contradiction exists.

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 longer than typical but every sentence carries meaningful information: scope, fields, query syntax, ceiling behavior, and sibling alternative. It is well front-loaded with the core purpose, and the density of actionable content justifies the length.

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?

The description fully accounts for the tool's complexity: it explains the return fields, query operators, pagination limitations, date window handling, and relationship to sibling tools. With the output schema also present, an agent has everything needed to invoke the tool correctly.

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 the baseline is 3. The description adds value by explaining the 250 limit in relation to maxRecords, mandating startDatetime/endDatetime pairing, and providing rich query syntax examples that the schema only lists without contextual detail.

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 a specific verb and resource ('Search the last 3 months of global news coverage using the GDELT DOC API') and differentiates from siblings by naming the TV search alternative. It lists return fields, making the tool's purpose unmistakable.

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 provides both when to use this tool (for recent 3 months of news) and when to use an alternative ('use gdelt_search_tv for historical TV transcripts back to 2009'). Also gives operational guidance on splitting queries when hitting the 250-article ceiling.

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

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

Beyond the annotations (readOnly, openWorld), the description discloses a major limitation (station monitoring ended October 2024), a hard requirement (must provide at least one station, omitting both is rejected), and a pairing constraint for startDatetime/endDatetime. It also clarifies normalization vs. raw values. These are non-obvious behaviors an agent needs to know.

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 compact yet information-dense. It front-loads the core purpose, then explains return value, gives concrete operator examples, and closes with a critical caveat. No wasted words; 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?

For a tool with a rich output schema, the description still covers essential context: coverage timeframe, 150+ stations, station requirement, operator syntax, normalization behavior, and the October 2024 shutdown. It also links to a sibling tool for coverage validation, making it self-sufficient for correct invocation.

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 schema already covers all 7 parameters with detailed descriptions (100% coverage), so the description adds little semantic value beyond the schema. The main description reinforces the station: operator and station requirement, but these are already documented in the schema. Baseline 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 opens with a specific verb and resource: 'Search US television news closed captions... for spoken mentions of a query.' It clearly differentiates from siblings like gdelt_search_articles (TV vs. articles) and gdelt_list_tv_stations (search vs. list). The return type (normalized per-station time series) further pins down the function.

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?

It explicitly states when to use the tool (for TV closed captions), gives operational prerequisites (station required, either via parameter or query selector), and recommends the alternative gdelt_list_tv_stations to verify coverage date ranges. This is concrete, actionable usage guidance beyond mere purpose.

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