gdelt-mcp-server

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

The description discloses key behaviors: returns up to 10 series, aggregates remaining into 'Other' bucket. It does not contradict the readOnlyHint and openWorldHint annotations; adds value by explaining aggregation.

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 efficiently convey purpose, utility, and usage examples without redundancy. 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?

The description adequately covers purpose, usage, and behavioral details. It references GDELT syntax and output schema, so the tool's operation is clear. Minor gap: does not explicitly mention that output schema exists.

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. The description adds context for breakdownBy use cases but doesn't significantly enhance parameter meaning beyond what the schema already 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?

The description clearly states the tool breaks down news coverage volume over time by source language or country, returning a multi-series time series. It distinguishes from siblings by providing specific use cases for 'country' vs 'language' 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?

The description gives explicit usage guidance: use 'country' with signal-detection chain for geographic attention, and 'language' for non-English surges. It implies alternatives for overall timeline but doesn't name sibling tools explicitly.

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 annotations (readOnly, openWorld), the description discloses automatic resolution, 3-month limit, tone interpretation, and that volume_with_articles returns top articles. 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.

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

The description is concise (5 sentences), well-structured with purpose first, then mode explanations, then a note. 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 complexity (6 params, output schema exists), the description covers modes, constraints, and relationship to sibling. It could elaborate on smoothing or query syntax, but schema fills those gaps. Output schema reduces need for return value explanation.

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 all parameters (100% coverage). The description adds context: automatic date resolution, interpretation of tone, and explicit note that volume_with_articles returns top articles. This goes beyond schema but does not add entirely new parameter 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 it retrieves a time series of news coverage or tone, and distinguishes three modes including a primary signal-detection mode. It differentiates from sibling tools by noting that volume_with_articles avoids a follow-up gdelt_search_articles 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 gives explicit guidance for each mode, including when to use volume_with_articles as primary detection. It mentions automatic date resolution and a 3-month limitation. It lacks explicit 'when not to use' but provides sufficient context for typical scenarios.

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, which the description does not contradict. The description adds useful behavioral context: histogram bins, representative URLs, and the approximate range. It does not fully disclose pagination or limits but these are not critical.

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 tight paragraphs front-loaded with action and key differentiator. A minor redundancy exists between the 'Distinct from...' sentence and the following 'Use...' sentence, but overall it is efficient and well-structured.

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 an output schema (context flag true), the description adds relevant return behavior (bins, URLs) and clearly distinguishes from a sibling tool. It covers the tool's purpose and usage context well, though could mention the time window constraints more explicitly.

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 parameters thoroughly. The description does not add additional parameter-level guidance beyond mentioning the histogram and query context. 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?

Clearly states the tool returns a tonal distribution histogram with bins approximately -30 to +30. Distinguishes from sibling gdelt_get_coverage_timeline by emphasizing this is a snapshot, not a time series, and references specific features like bimodal detection and representative URLs.

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 says when to use this tool (to understand tone distribution shape) and when not to (for sentiment over time), directing to the alternative gdelt_get_coverage_timeline with mode 'tone'. This is perfect usage guidance.

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. Description adds return details (show, station, timestamp, excerpt, link) and coverage limits, enhancing transparency 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?

Two sentences, each serving a purpose: first states action and return format, second gives usage guidance and coverage limit. No waste.

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 output schema exists, description covers return format, usage constraints, and coverage span. Sufficient for invoking 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 description coverage is 100%, so baseline is 3. Description does not add significant meaning beyond what the schema already provides for parameters.

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 verb 'retrieve' and resource 'top matching TV news clips' with scope (up to 3,000). It distinguishes from sibling gdelt_search_tv by positioning this tool as the follow-up to read actual transcript content.

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 'Use after gdelt_search_tv' and mentions archive coverage span as a constraint. Lacks explicit when-not-to-use or alternatives, but the usage context is clear.

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, so the description does not need to reiterate safety. It adds valuable behavioral details: returns 'relative frequency scores (0–100, where 100 = the query term itself)' and 'TV data spans 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.

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

The description is concise (three sentences) and front-loaded: first states the core purpose, then explains the output format, then provides usage guidance. Every sentence adds value 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 tool's complexity (5 parameters, 1 required) and the presence of an output schema, the description is quite complete. It explains the output (top co-occurring words with relative frequency), usage scenarios, and data coverage. The output schema exists, so it doesn't need to detail return values.

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 baseline is 3. The description adds some context about the output format (scores 0–100) and usage, but does not significantly enhance parameter understanding beyond the schema descriptions. It does not add new constraints or examples for parameters.

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 — the vocabulary framing a topic on television.' It specifies the verb ('Get'), the resource ('top co-occurring words and phrases from TV news clips'), and distinguishes from sibling tools like gdelt_search_tv (which returns clips) and gdelt_get_tone_distribution (which returns tone scores).

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 usage contexts: 'Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms.' It also mentions data coverage. While it doesn't explicitly state when not to use or list alternatives, the differentiation from sibling tools is implicit and adequate.

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 indicate readOnlyHint and openWorldHint. The description adds behavioral context: the tool returns US national network data, updated every 15 minutes (historically), and importantly discloses that the feed stopped updating in October 2024, so results are archived. This is valuable beyond annotations and consistent with safe read behavior.

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: action, result content, and a critical caveat about data freshness. Front-loaded and efficient, every sentence adds value 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 tool's simplicity (no params, output schema exists), the description covers what the tool returns, its update nature, and the crucial limitation about archive data. It is fully adequate for an agent to understand and 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?

With zero parameters and 100% schema coverage from the empty schema, the description adds no parameter details, which is expected. The statement 'no query required' is a helpful elaboration, meeting the baseline of 4 for a no-parameter tool.

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 trending topics, keywords, and phrases from US TV news. It differentiates from siblings by noting 'no query required' and focusing on 'top memes of the present news cycle', making its specific purpose distinct.

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 implies usage for a quick overview of current TV news trends without a query. It notes the data is from an archived feed (stopped updating), providing context for when the tool is appropriate, but does not explicitly name alternatives or when not to use.

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?

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.

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

Annotations declare readOnlyHint=true and openWorldHint=true, which are consistent with a search/read tool. The description adds context about the 3-month window, supported fields, and GDELT syntax, enhancing transparency 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 concise with two well-structured paragraphs. Every sentence adds value: first paragraph covers purpose and outputs, second covers query syntax and alternative tool. No unnecessary 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 (6 parameters, output schema exists), the description covers all essential aspects: scope, return fields, query syntax, parameter details, and alternative tools. An agent has sufficient information to select and use 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 description coverage is 100%, but the description adds value by explaining the overall query syntax, default behaviors (e.g., default sort, default timespan), and relationship between parameters (e.g., startDatetime/endDatetime must be used together).

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 verb 'Search' and resource 'GDELT articles', specifies the coverage (last 3 months), and the return fields (URL, title, etc.). It distinguishes itself from sibling tool 'gdelt_search_tv' by noting the temporal scope difference.

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 gives explicit guidance on when to use this tool vs the alternative (gdelt_search_tv for historical TV transcripts). It also explains the query syntax and default behavior, but could be more explicit about when not to use it (e.g., if older than 3 months).

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 indicate readOnlyHint=true and openWorldHint=true. Description adds behavioral context: data cutoff (October 2024), normalization behavior, and operator usage. Does not contradict 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 a well-structured single paragraph, front-loaded with purpose, followed by key usage details. Efficient but could be slightly more concise; no fluff.

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), the description covers purpose, parameters, data limitations, and usage tips. Output schema exists, so return values are handled. Completeness is high.

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?

Input schema has 100% description coverage, so baseline is 3. Description enhances understanding with additional context for query operators, normalization effect, and timespan behavior. Adds value 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 searches US TV news closed captions for spoken mentions and returns normalized per-station time series. Distinguishes from siblings 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.

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

Provides explicit guidance on when to use the stations parameter (compare networks) and when to omit (national coverage). Recommends using gdelt_list_tv_stations for validation of active date ranges, especially for recent events, and warns that data ends October 2024.

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