Geotone — Global News Signals

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds that the tool returns an 'analytical summary' with statistics, providing useful context about the output beyond the annotations. No additional behavioral traits (e.g., rate limits) are disclosed, but with strong annotations, this is sufficient.

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 concise sentence that front-loads the tool's purpose and key features. Every word adds value, with 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?

Given the tool has only one parameter, annotations for safety, and an output schema (mentioned in context), the description provides sufficient context about the output contents (coverage surges, tone shifts, notable movers). It is complete for agent decision-making.

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 for the single parameter 'date' is 100%, with a pattern and description. The description repeats the date format (YYYY-MM-DD) but adds no new meaning beyond what the schema provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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 'Geotone's daily global risk briefing' with specific content: 'coverage surges, tone shifts, and notable movers, with the statistics'. The verb 'get' and resource 'briefing' are specific, and the description distinguishes it from siblings like get_country or get_trending by focusing on a daily aggregate.

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 global risk briefing, but does not explicitly state when to use it vs alternatives (e.g., get_country for country-specific data). No exclusions or prerequisites are mentioned. The usage is clear from context but lacks explicit 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 declare readOnlyHint=true, so the agent knows it's a safe read. The description adds that the statistics are 'live' and span 90 days, providing useful context beyond the annotation. No behavioral contradictions or hidden effects are mentioned.

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, compact sentence that conveys the core purpose and data. It is front-loaded with the key information and contains 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 that an output schema exists (and the description thus does not need to detail return values), the description sufficiently covers what the tool does: returns 90-day daily series of coverage volume and tone for a given country. 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?

The input schema already describes the iso2 parameter as an ISO2 code with an example. The description repeats this with additional examples ('ua', 'cn'). Since schema coverage is 100% and the description adds no new semantic meaning, the score is baseline 3.

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 live media-coverage statistics for one country, including coverage volume and tone over a 90-day period. It uses ISO-3166 alpha-2 codes. This distinguishes it well from sibling tools like get_briefing or get_topic which focus on different resources.

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 explains the input (ISO code) and output (daily series of volume and tone). However, it does not explicitly state when to use this tool versus alternatives, though the sibling tools cover different domains, making it implicitly 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 indicate readOnlyHint=true, and the description adds behavioral context by specifying the output includes coverage amount and tone. No contradictions, but it could elaborate on the output structure slightly.

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 concise: one sentence covering functionality, an example, and a note on monitored pairs. No fluff, front-loaded with key 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?

Given the presence of an output schema (not shown) and annotations, the description adequately covers the tool's purpose and constraints. It could be slightly more explicit about the output metrics, but the output schema likely covers that.

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?

Both parameters are fully described in the schema (ISO2 codes), and the description adds real-world context through the example and the limitation to ~50 strategic pairs, which is critical for correct invocation.

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 returns a bilateral co-coverage signal for a country pair, specifying what it measures (mentions and tone) and giving an example. It distinguishes itself from sibling tools focused on single countries, topics, etc.

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 implicitly differentiates from siblings by focusing on bilateral coverage, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The mention of ~50 monitored pairs provides a constraint.

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, but description adds behavioral details: ordering (oldest first), content format (headline + link + outlet count + tone), and that it covers one event chain. 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 sentences, front-loaded with key purpose and ordering, followed by source and content details. Every word adds value with 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 the simple single-parameter input, 100% schema coverage, read-only annotation, and presence of an output schema (so no need to describe return values), the description fully covers what an agent needs to know about the tool's function and context.

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%, with chain_id described as 'Chain id from get_wire'. The description merely reiterates this link without adding new semantic meaning beyond the schema. Baseline 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 it provides a story timeline for a multi-day event chain, ordered oldest first, with examples like 'attack → casualties confirmed → international reaction'. It distinguishes itself from siblings like get_wire (which returns chain_id values) and other tools.

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 specifies that it uses chain_id values from get_wire, giving clear when-to-use context. It doesn't explicitly state when not to use, but the purpose is well-defined enough for an agent to infer.

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 indicate read-only and not open world. The description reinforces this by detailing statistical metrics without mentioning side effects. It adds specific behavioral context (90-day range, tone, z-score) beyond what annotations alone provide.

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 two sentences with no wasted words. The first sentence delivers the core purpose and data provided; the second gives a practical usage hint. 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 single parameter, high schema coverage, and existence of an output schema, the description covers all essential aspects: what data to expect, how to find the required slug, and that it's for a single topic. 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?

The schema covers the slug parameter with a description, and the description adds value by providing an example ('ukraine-war') and clarifying the parameter's role in referencing a geopolitical topic, enhancing semantic understanding beyond the 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?

The description uses a specific verb ('Live media-coverage statistics') and explicitly lists the metrics (90-day daily volume and tone series, z-score, week-over-week change, recent articles). It clearly identifies the resource ('one geopolitical topic') and distinguishes from siblings by focusing on a single topic's statistics.

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 advises to use search_topics to find slugs, providing clear context for tool prerequisite. It implies usage for individual topic statistics, though it does not explicitly state when to avoid this tool versus siblings like get_trending.

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=false. Description adds value by explaining the tool's data source (GDELT), update frequency (every 2 hours), and language coverage (65+), enhancing transparency.

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 fluff, front-loaded with the core purpose. Every sentence adds essential information (what it does, how it's derived, update frequency, coverage).

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 zero parameters and output schema available, the description is complete. It explains the output in detail (statistical criteria, types of results) and provides context on data source and freshness.

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 schema coverage is 100%. Description adds full meaning by explaining what the output contains (z-score topics, movers, surging countries), making the tool's behavior clear without needing parameter details.

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 defines the tool's purpose: show surging topics, week-over-week movers, and surging countries. It distinguishes from siblings like get_topic (specific topic) and get_briefing (summary), providing a unique use case.

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?

Implied usage: for trending global news. Does not explicitly state when not to use or name alternatives, but the context makes it clear this is for surging content, not for specific queries.

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 mark it as read-only (readOnlyHint: true), so no contradiction. The description adds value beyond annotations by detailing the ranking formula, field contents (link, outlet count, tone, countries, chain_id), and the reclustering cadence (every 2 hours). This discloses dynamic behavior not captured 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?

The description is concise, packing key details into two sentences. It front-loads the main purpose and then explains the formula and fields. It could be slightly more structured (e.g., bullet points), but it is effective and not verbose.

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 fields, output schema exists), the description is remarkably complete. It explains the ranking logic, the fields returned, and the relationship with get_story_chain. The presence of an output schema reduces the need to describe return format, so the description covers all necessary contextual information.

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 covers 100% of parameters (only limit), with a clear description of min, max, and default. The description does not add extra semantic detail beyond what the schema provides, so it meets the baseline for high 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 that the tool fetches 'the world's most significant stories right now', ranked by a published formula. It distinguishes itself from siblings by mentioning get_story_chain for multi-day timelines, and the unique ranking approach differentiates it from other get_ tools.

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 guidance by explaining when to use get_story_chain as a follow-up (for stories with a chain_id). It implies that get_wire is for the top stories, but doesn't explicitly compare to other siblings like get_briefing or get_trending. However, the context of 'most significant stories' and the mention of get_story_chain offers clear usage context.

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, so description's contribution is minimal. It adds that the search matches name, slug, and description, but does not disclose behavioral details like result limits, pagination, or fuzzy matching.

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 two sentences with no wasted words, front-loading the action and return 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 has an output schema (not shown but referenced) and one parameter, the description covers the key behaviors: what it searches, what it returns, and the intended follow-up. This is complete for a search 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 coverage is 100% with an example in the parameter description. The description adds context by explaining what fields the keyword matches against, enhancing understanding beyond the 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?

The description clearly states it searches geopolitical topics by keyword, specifying the fields matched (name, slug, description) and the return value (slugs and coverage stats). This distinguishes it from siblings like get_topic which retrieves a single topic by slug.

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 indicates the return slugs are usable with get_topic, implying a workflow. However, it does not explicitly state when to use this tool over alternatives like get_trending or get_wire, nor does it mention any exclusions.

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