GDELT Global Events

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

No annotations exist, so description carries burden. It discloses it returns recent articles and mentions optional filters, but does not explicitly state read-only behavior, pagination, rate limits, or auth needs. 'Returns recent articles' hints at non-destructive nature but is not explicit.

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 purpose. Every sentence adds value: purpose, optional filters, return fields. No redundancy or 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 no output schema, description adequately covers return fields. For a search tool, it could mention sorting/ordering or pagination behavior, but overall covers key aspects for an agent to decide and invoke.

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 4 of 5 params with descriptions. The description adds context: query supports operators (quotes/OR), country is ISO 2-letter, timespan examples ('1d', '7d', '1m'). It also explains return fields. Lacks detail on max_records behavior beyond default and min/max.

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 it searches global news events, with explicit details on what it returns (title, URL, source, etc.) and optional filters. Distinguishes from sibling tools (tone timeseries, trending actors) by its search-and-return focus.

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?

Implies usage for searching events, but provides no explicit when-to-use or when-not-to-use compared to siblings (gdelt_tone_timeseries, gdelt_trending_actors). No exclusion criteria or alternatives mentioned.

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?

No annotations are provided, so the description carries full burden. It discloses the output format (tone scale -10 to +10, volume per time step) but lacks details on edge cases (e.g., empty results), auth requirements, or rate limits. Adequate but not comprehensive.

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 one efficient sentence with parenthetical clarification, no wasted words. It front-loads the key point and is structurally sound, though slightly more detail could be added without losing conciseness.

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 no output schema, 4 parameters with 0% description coverage, and no annotations, the tool description is incomplete. It fails to specify output details beyond tone and volume, parameter meanings, or error handling. More content is needed for the agent to understand the tool fully.

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 0%. The description does not explain individual parameters (query, country, timespan, granularity) despite the schema having defaults and enums. Without parameter details, the agent cannot use the tool correctly based on the description alone.

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 produces a sentiment-tone timeseries for a query, with output rows per time step including average tone and article volume. It distinguishes from sibling tools like gdelt_search_events (event search) and gdelt_trending_actors (trending entities), making its 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 implies use when sentiment over time is needed but provides no explicit guidance on when to use this tool versus siblings, nor any when-not-to-use conditions. Context signals indicate the tool's function, but direct guidance is absent.

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?

With no annotations provided, the description carries the full burden. It discloses the core behavior and return format but lacks details on data freshness, pagination, or limits (e.g., maximum window size). This is adequate but not exhaustive.

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 with no redundant information. Every word adds value, and the key details are front-loaded.

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 simple tool with three parameters and no output schema, the description is mostly complete. It explains the output and main filters. However, the absence of usage guidelines relative to sibling tools and the lack of behavioral detail (e.g., default window) slightly reduce completeness.

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 low (33%: only country described). The description adds meaning for 'country' and 'window' (last N hours) but does not elaborate on 'limit' or the expected format of 'window' beyond the schema defaults. Insufficient compensation for the low coverage.

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 top mentioned named entities (people, organizations, places) from news for a country in the last N hours, and specifies the output format (name + mentions count). This distinctively separates it from sibling tools like gdelt_search_events and gdelt_tone_timeseries.

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 trending entities but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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