Geotone — Global News Signals

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

Annotations already declare readOnlyHint=true. The description adds valuable context: it is an analytical summary with statistics behind each claim. This goes beyond the annotation by describing the content and type of analysis provided, improving transparency for an 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?

The description is a single, well-structured sentence that immediately conveys the tool's purpose and output. Every word adds value; no 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 tool has an output schema (not shown but noted) and all parameters are covered by the schema and description, the description is complete. It explains what the output contains, and the read-only annotation covers safety. No gaps are apparent.

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% and the description reiterates the date format (YYYY-MM-DD) and its purpose (UTC date for the briefing). This adds practical meaning beyond the raw schema, helping agents understand the parameter's role.

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 explicitly states the tool returns a daily global risk briefing with specific content (coverage surges, tone shifts, notable movers, statistics). It clearly distinguishes from sibling tools that target individual entities (e.g., get_country, get_topic) rather than a curated summary.

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 obtaining a daily risk briefing on a specific date, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context of sibling tools suggests this is for an overview, but guidance is only implicit.

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 read-only and closed world. Description adds valuable behavioral details: time ranges (90-day daily series), specific data sources (UCDP fatalities, UNHCR displacement), and coverage origin split by domestic vs foreign production. This is rich context 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 a single, well-structured sentence that front-loads the main purpose and then lists the specific metrics. It is concise given the amount of information, but could be slightly more readable with bullet points.

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 covers the major data categories (series, fatalities, displacement, origin). With an output schema present, it doesn't need to detail return format. It provides sufficient context for an agent to decide whether 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 schema already describes iso2, but the description adds the standard name 'ISO-3166 alpha-2' and examples 'ua', 'cn', reinforcing correct usage. It also explains the output context, helping the agent understand the parameter's role.

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?

Clear verb and resource: provides live media-coverage statistics for a single country by ISO code. Includes specific data types and time ranges, distinguishing it from sibling tools which focus on topics, relations, or trends.

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 country-specific statistics are needed, but does not provide explicit guidance on when to use this tool vs siblings like get_topic or search_topics. A simple sentence like 'For media coverage data by topic, use get_topic instead' would improve 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?

Annotations already declare readOnlyHint=true. The description adds context about the 'signal' nature (coverage + tone) and the limited set of monitored pairs (~50), providing behavioral insight 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, front-loaded with example and clear purpose. Every sentence adds value; 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 simple parameters, existing output schema, and annotations, the description adequately explains what the tool returns (coverage and tone) and its scope (monitored pairs). No missing critical details.

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 self-explanatory ISO2 parameters. The description adds value by providing an example (a='cn', b='us') and stating the monitored pair scope, going beyond the schema's minimal descriptions.

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 bilateral co-coverage signal, with an example (a='cn', b='us') and explains what it measures (coverage amount and tone). This distinguishes it from siblings like get_country (single country) or get_trending.

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 bilateral country pairs but does not explicitly state when to use this tool vs alternatives like get_country or get_topic. No exclusions or when-not-to-use guidance is provided.

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 signal read-only behavior. Description adds value by revealing chronological ordering (oldest first) and the structure of developments, which are not in 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 concise sentences front-load the core purpose and example, with no wasted words. Every sentence adds necessary information.

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?

Sufficient for a simple read tool with one parameter and an output schema. Could mention limits or pagination, but the given details cover essential 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%, but description adds meaning by explaining the chain_id parameter's origin (from get_wire) and its role in retrieving a specific story chain.

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 provides 'threaded developments of one multi-day event chain' with oldest first ordering and example structure. It includes specific components (headline, link, outlet count, tone) and distinguishes from siblings by referencing get_wire and chain_id.

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 instructs to use chain_id from get_wire, providing clear context for when to invoke. However, lacks comparisons with siblings or when-not-to-use 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?

Beyond the readOnlyHint annotation, the description details the data scope (90-day series, z-score, week-over-week change, article headlines/links) and notes what is not included (full text). This adds meaningful insight into the tool's behavior and limitations.

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, no wasted words. Core purpose is front-loaded in the first sentence; the second provides actionable guidance. Efficient and clear.

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 one-parameter tool with an output schema, the description covers all essential aspects: what it returns (specific metrics), time range, and how to get input. No gaps given the 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 coverage is 100% with a clear description of the 'slug' parameter. The description adds extra value by advising to use search_topics to obtain the slug, which is not in the schema, enhancing 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 it provides live media-coverage statistics for a geopolitical topic, listing specific outputs (volume, tone, z-score, change, article samples). It distinguishes from siblings by focusing on media-coverage stats vs. other get_* tools which likely cover different scopes.

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 mentions using search_topics to find slugs, guiding the agent on a necessary prerequisite. However, it does not explicitly address when to prefer this over sibling tools like get_briefing or get_trending, leaving room for improvement.

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?

Adds behavioral context beyond annotations: derived every 2 hours from GDELT across 65+ languages. No contradiction with readOnlyHint annotation.

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: first defines purpose and metrics, second adds frequency and source. 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?

For a parameterless tool with output schema, description fully explains what is returned and update frequency. No gaps.

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, so baseline 4 applies. Description adds value by explaining output metrics (z-score, movers, surging countries), though not required for this dimension.

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 defines verb ('surging'), resource ('global news topics'), and specific metrics (z-score, week-over-week movers, surging countries). Distinguishes from siblings by focusing on trending/surging 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?

Description implies usage context (trending vs other tools) and states update frequency ('every 2 hours'), but does not explicitly state when not to use or name alternatives.

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 include readOnlyHint=true, indicating safe read. The description adds meaningful behavioral context beyond this, such as the ranking formula (authority-weighted outlet breadth, etc.), 72-hour decay, 2-hour reclustering, and the structure of returned stories (representative link, outlet count, etc.). 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 three sentences long, starting with the core purpose, then explaining the ranking formula, and finally listing output fields. It is well-structured and front-loaded, though the title 'The live wire' is somewhat whimsical and adds little 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 (ranking formula, multiple output fields, periodic updates), the description is comprehensive. It covers how stories are ranked, what fields are returned, the 2-hour reclustering cycle, and references the sibling tool for multi-day stories. An output schema exists, so return values are fully documented.

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 a single parameter 'limit' having min/max and description. The tool description does not add any additional meaning or usage context for the parameter beyond what the schema already provides, so 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 that the tool returns 'the world's most significant stories right now' ranked by a specific formula. It specifies the verb 'get' and resource 'wire', and distinguishes from sibling tool get_story_chain by mentioning its use for multi-day story timelines.

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 provide guidance on when to use get_wire over sibling tools like get_briefing or get_trending. It only mentions get_story_chain as a follow-up for multi-day stories, but lacks explicit when-to-use or when-not-to-use instructions.

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 show readOnlyHint=true; description adds that it returns slugs and coverage stats, enhancing transparency. No contradictions. Could mention result limits or ordering, but sufficient for a search tool.

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, front-loaded with action and resource. Every word adds value, no 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 single parameter, clear annotations, and existence of output schema, description fully covers tool behavior and output. References sibling tool for workflow 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 covers 100% with description and example. Description adds meaning: query matches name, slug, and description. Provides additional context 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?

Clearly states verb 'Search', resource 'geopolitical topics', and matching criteria (keyword on name, slug, description). Distinguishes from sibling 'get_topic' by noting returned slugs can be used with that tool.

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?

Describes when to use: to find topics by keyword. Mentions returned slugs are input to get_topic, providing guidance. Lacks explicit when-not-to-use or alternative tools, but context from siblings is clear.

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