Keyword Search Volume, CPC, Keyword Ideas and Google Trends API

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

Annotations already cover readOnly/idempotent/openWorld, yet the description still adds non-obvious traits: ~30 s live latency, per-call price of $0.045, the rule that bad input and upstream errors are free but success is charged, and the x402/USDC-on-Base payment path via _meta["x402/payment"]. That is exactly the operational context an agent needs before spending money.

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?

Four tight sentences front-loaded with what the tool returns, then when to use it, then granularity, latency and pricing. No filler, and the cost/payment caveat is placed where an agent will see it before calling.

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 output schema, the description still specifies the return shape (dated 0-100 series), the resolution per timeframe, and the full cost/payment model. There is no material gap an agent would need to close before invoking it.

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 country codes, keyword length limits and the timeframe enum are fully documented in the schema. The description only reinforces the single-keyword constraint and states the daily-vs-weekly granularity split, adding modest value above the baseline.

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 opens with a specific verb+resource ('Google Trends interest over time for one keyword') and defines the returned shape as a dated 0-100 series with country/worldwide scope. The 'one keyword' phrasing distinguishes it in spirit from google_trends_by_region and google_trends_related_queries, though those siblings are never named, so an agent must infer the boundary.

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?

'Use when you need search-interest trends, seasonality or demand direction for a keyword' gives clear positive selection criteria. It stops short of exclusions or explicit alternatives (e.g., 'use google_trends_by_region for a regional breakdown'), leaving that routing to inference.

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 readOnly, idempotent and openWorld, and the description layers on what only it can supply: a live call takes up to ~30 s, bad input is free while upstream errors are not charged, and payment is settled over x402 (USDC on Base) via _meta['x402/payment']. This is exactly the operational context an agent needs before committing to a paid call.

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 dense sentences, front-loaded with what the tool returns and its scale before pricing and payment mechanics. The pricing/payment sentence is long but carries decision-relevant information; no 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?

With no output schema, the description still explains the return shape (0-100 per subregion), and it covers latency, error-charging policy, and payment mechanics that the annotations and schema omit. Nothing an agent needs to call this correctly appears to be missing.

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 the baseline is 3, but the description adds real meaning: it frames the output as '0-100 interest per subregion of a country (or per country worldwide)', which explains the country parameter's effect, and 'past 7 days to 5 years' summarizes the timeframe enum range. It doesn't restate the keyword length or comma restriction, but the schema already covers those.

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 names the specific resource and scope: Google Trends interest by region for one keyword, with the 0-100 index, the subregion-vs-worldwide granularity, and the timeframe span. It doesn't explicitly name sibling tools like google_trends or google_trends_related_queries, so the differentiation is implied by the 'by region' scope rather than stated.

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?

It states a concrete use case ('when you need where a keyword is searched most, for geo-targeting or local market research'), which tells the agent when to reach for it. It stops short of naming alternatives or stating when not to use it, leaving the sibling distinction to inference.

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 readOnly/openWorld/idempotent annotations, the description discloses the things annotations cannot: ~30 s latency for live calls, a $0.03 per-successful-call price, the pricing asymmetry (bad input free, upstream errors not charged), and the x402 USDC payment mechanism in _meta. That is exactly the extra operational context an agent needs before invoking a paid external call.

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?

What it does and returns comes first, then use cases, then cost/latency/payment — a sensible order with no filler. Minor redundancy: the $0.03 price appears twice ("one $0.03 GET" and again in the price sentence), costing a little density.

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 output schema, the description carries the return-shape burden and does so (two lists, score 0-100 and % growth). All three parameters are covered by the schema, and cost, latency, billing behavior and the payment field are all stated, leaving nothing material an agent needs before calling.

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 keyword, country (ISO alpha-2, uk=gb) and the timeframe enum with its default. The description only restates the ranges (country or worldwide, 7 days to 5 years) without adding syntax or edge-case meaning, so the baseline 3 applies.

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?

States the exact verb+resource (related queries for ONE keyword) and enumerates the two return groups with their scales: top related searches scored 0-100 and rising ones with % growth. This differentiates it cleanly from google_trends (time series) and keyword_ideas (expansion lists), so an agent can pick it without opening the schema.

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?

"Use when you need query expansion, content ideas or emerging searches around a keyword" gives concrete selection criteria tied to intent. It stops short of naming alternatives (e.g. keyword_ideas) or stating when not to use it, so it is clear context rather than full routing 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 mark it read-only, idempotent and open-world, and the description adds substantial context beyond that: $0.04 cost, x402 USDC-on-Base payment via _meta["x402/payment"], empty result sets still being charged, bad input being free, and upstream errors not billed. That is exactly the billing/failure behavior an agent cannot get from annotations or schema, and nothing contradicts the hints.

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?

Purpose and the metrics it returns are front-loaded and the pricing/edge-case notes follow in a logical order. There is mild redundancy between 'up to 100 ideas in one $0.04 call' and the later 'Price: $0.04 per successful call', but each sentence otherwise carries 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?

With no output schema, the description takes on the job of describing the response (volume, CPC, competition, difficulty, intent) and also covers cost, payment mechanics and the empty-result/free-400/uncharged-error cases. An agent has enough to decide whether to call and how to pay 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 the parameters (limit, country, locationCode, languageCode, includeMonthly) are already fully documented and the baseline of 3 applies. The description's metric glossary (volume, cpc, competition 0-1, difficulty 0-100) explains return values rather than adding parameter meaning, so it doesn't push this above baseline.

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?

States a specific verb+resource ('Keyword ideas for a seed keyword') and enumerates the returned metrics, plus a count/price bound. It implies differentiation from volume-lookup siblings via 'Use when you need related keywords to target' but never names keyword_overview or keyword_search_volume, so the boundary is inferred rather than stated.

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?

There is one clear usage cue ('Use when you need related keywords to target'), which positions it as an expansion/discovery tool. However, no sibling is named as an alternative and no when-not-to-use condition is given, even though keyword_search_volume and keyword_overview overlap conceptually.

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 annotations, the description discloses important behavior: pricing, x402 payment handling via _meta, exclusion and charging for keywords without data, and the distinction between free bad input and charged upstream errors. These details materially affect whether and how an agent should invoke the 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?

The description is dense but front-loaded: the core capability and use case come first, followed by metric definitions, charging rules, and payment mechanics. Every sentence contributes operationally relevant 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 paid, external-data tool with no output schema, the description covers the essential context: what metrics are returned, bulk limits, missing-data behavior, billing semantics, and the x402 payment mechanism. The schema already handles location, language, and fallback 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 description coverage is 100%, so the parameters are already well documented. The description adds useful semantics for returned metrics, but it adds little input-parameter meaning beyond what the schema already provides, 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 states a specific resource and metric set: search volume, CPC, competition, keyword difficulty and search intent for up to 100 keywords. It also implies a clear use case that separates it from idea-generation siblings, but it does not explicitly name or contrast a sibling such as keyword_search_volume.

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?

It gives a clear usage condition: 'Use when you already have a keyword list to prioritise.' That helps distinguish it from keyword_ideas, but there is no explicit when-not guidance or named alternative tool.

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 read-only and idempotent annotations, the description discloses pricing, which failures are charged, missing-keyword behavior, and the x402 payment mechanism. This is unusually complete behavioral context for a paid data-lookup 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?

The description is dense and front-loads the core purpose, metrics, and scope. Every sentence carries useful information, though the pricing and payment details make it heavier than strictly necessary for selection.

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 output schema, the description supplies the metric meanings and billing/missing-data behavior an agent needs to call the tool correctly. Annotations already cover safety, and the description complements them with cost and failure-mode 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%, so the schema already fully documents keywords, country, lang, and includeMonthly. The description adds metric definitions for returned fields and repeats the 20-keyword limit, but adds little parameter-specific meaning beyond the schema; 'comma-separated keywords' also slightly mismatches the array parameter.

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 names the exact resource and metrics (Google search volume, CPC, competition, keyword difficulty and intent) and the concrete scope (up to 20 keywords in one GET). It also explicitly distinguishes itself from keyword_overview, which handles up to 100 keywords via POST.

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?

It states when to use it: 'when you need monthly search volume for a few keywords in a country.' It also names the alternative for larger batches and the condition that selects it, leaving little ambiguity.

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