TrendFlow

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds value by explaining that values are normalized relative interest (0-100 within the result set). It does not disclose output structure or edge cases, but the added value is sufficient given 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?

Two concise, front-loaded sentences deliver purpose, usage, and value normalization with zero 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?

For a simple tool with annotations and no output schema, the description covers purpose, when-to-use, and value semantics. It sufficiently supports an agent's decision to invoke the tool, though a brief note on output shape could be added.

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 a key constraint that the keyword is a single term and reinforces granularity through 'regional or city-level comparison,' providing meaning beyond the schema's field 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?

Description clearly states the tool breaks down search interest by geography for a single term, distinguishing it from time-based or related-query siblings. The verb 'break down' is specific and the scope (one term, geographic breakdown) is explicit.

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 trigger conditions ('when the user asks where something is popular') and mentions regional/city-level comparison, but does not explicitly name alternatives or state when not to use it. This gives clear context but no exclusions.

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 annotation already indicates readOnlyHint and openWorldHint, so the description doesn't need to cover safety. The description adds valuable context about the output being 'normalized relative interest (0-100 within the result set), not absolute search volume,' which is not obvious from the schema or annotations. However, it doesn't describe the exact structure of the returned time series, which would be helpful given no output schema.

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 exactly two sentences, front-loaded with the core action, then adding usage guidance and a normalization caveat. There is no redundant or filler information; every clause earns its place. It is appropriately concise for 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 moderate complexity, the description covers the essential points: what it does, when to use it, how multiple keywords behave, and the relative scale. It does not repeat schema details. The only minor omission is a lack of detail on the returned data format (e.g., time series granularity), but the absence of an output schema makes that less critical here. Overall, it is complete enough for selection and 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?

Schema describes all three parameters with definitions for region, keywords, and timeframe, achieving 100% coverage. The description enhances this by explaining that passing multiple keywords 'compares them on one scale,' which gives deeper semantic meaning beyond the schema's literal field descriptions. This is a clear added value.

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 relative search interest for one or more terms over a historical period.' It uses a specific verb and resource, and distinguishes from siblings by emphasizing historical time-series comparison versus regional, trending, or related queries. This makes the purpose unambiguous and easily differentiable.

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 this when the user asks how popular something is, whether it is rising or falling, or how several things compare.' This gives direct usage guidance and implies when not to use it (e.g., for real-time trending or regional breakdowns). It also clarifies the behavior with multiple keywords, which is a key differentiator.

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 safe-read nature is known. The description adds meaningful behavioral context by explaining the distinction between 'top' (ranked by volume) and 'rising' (ranked by growth), and defining 'Breakout' as growth too large to measure.

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, front-loaded with the primary action and directly followed by use cases. Every sentence earns its place, with no wasted words or redundant 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?

For a single-parameter, read-only tool with no output schema, the description covers purpose, use cases, and key output semantics (top vs rising, breakout). It lacks an explicit statement of the return format, but the provided context is sufficient for an agent to select 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?

Schema coverage is 100%, with the only parameter 'keyword' fully described. The description does not add new parameter-level details beyond the schema, but it does add context about how the keyword is used (related search discovery). This matches the baseline for high schema 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 uses a specific verb ('Find') and clearly identifies the resource: 'top and rising searches related to a term'. It distinguishes the tool from siblings like get_interest_over_time or get_trending_now by focusing on related queries for keyword discovery.

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 this for keyword discovery, SEO and content research, and spotting breakout queries.' This provides clear context but does not mention when not to use it or name alternative tools, so it falls short of a 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?

Annotations already mark readOnlyHint and openWorldHint, so the description doesn't need to restate safety. It adds meaningful behavior beyond annotations: the `backend` parameter differences (rpc vs rss vs auto fallback), return sizes, growth percentages, relative volume index, and news articles. This is substantial and transparent.

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: first sentence states purpose and use case; second details backend options. No redundant filler, information is front-loaded and directly useful.

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?

Despite no output schema, the description explains what results to expect for each backend (entry counts, growth percentages, news articles), making the tool's behavior understandable. Combined with the parameters and annotations, this is 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 coverage is 100%, so baseline is 3. The description goes beyond schema by explaining the practical differences between backend values ('rpc' returns ~50 with growth percentages; 'rss' returns 10 with news articles; 'auto' fallback). This adds value for correctly selecting the backend enum.

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 specific action ('Lists the searches surging right now in a country') and clarifies the use case ('for questions about what is spiking without a term being named'). It clearly distinguishes from sibling tools like get_interest_over_time and get_related_queries, which focus on historical or term-specific 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?

Signals appropriate contexts: 'for questions about what is spiking without a term being named, and for news and real-time context.' It does not explicitly name alternatives or state when not to use it, but the intended use is clear and the sibling tools are distinct enough that the context suffices.

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 the read-only behavior is known. The description adds valuable behavioral detail: sections are fetched independently and failures yield errors per-section while other data still returns. This goes beyond the annotations and helps set expectations for partial results.

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 paragraphs with no filler. The first sentence immediately states the tool's purpose and contents, and the second paragraph efficiently communicates the partial-result behavior. Every sentence 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 no output schema, the description covers what is returned (three sections) and the failure behavior. It lacks precise detail about the response format for each section, but the sibling tools likely cover those specifics, and the open-ended research use case is well contextualized.

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% of parameters with clear descriptions (keyword, region, and their formats). The description itself adds little to parameter semantics beyond referring to 'one term,' so the 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 the tool returns a comprehensive view of one term (interest over time, top regions, related queries) and explicitly distinguishes it from single-facet alternatives by noting it's for open-ended research rather than narrow questions. This separates it from siblings like get_interest_over_time and get_related_queries.

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 usage context: 'Suited to open-ended research on a topic rather than one narrow question,' implying when to choose this tool over more specific ones. Also explains that partial results are normal due to independent section fetching. Does not explicitly name alternative tools, but the sibling list makes the contrast 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?

Beyond the readOnlyHint/openWorldHint annotations, the description explains that a topic aggregates spellings and translations, and quantifies the difference (AI topic scores 62 vs literal string's 1). This provides significant behavioral context for search volume semantics.

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 total. The first sentence states purpose and output, the second provides an illustrative example and integration context. Every sentence earns its place; there is no redundant or filler text.

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 one parameter and no output schema, the description fully explains what the tool returns (mid and type), why it matters (aggregated volume), and how it fits into the tool ecosystem. It is complete for a simple lookup 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 covers the single parameter (query can be a search term or an existing topic id) with 100% coverage. The description adds examples of entity types (company, product, person, etc.) but does not materially change understanding of the parameter's meaning or format 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 ('resolves') and names the resource ('Google Trends topic id') and output ('mid'), with an added 'type' field. It clearly distinguishes itself from sibling tools by focusing on entity resolution rather than trend measurement.

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 states that 'other TrendFlow tools accept a topic id anywhere they accept a keyword', implying this tool should be used to obtain topic ids for those tools. It gives a useful disambiguation example (Nike company vs goddess) but does not explicitly enumerate when not to use it or name alternative tools.

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