Amazon Trends API

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely non-structured behavior: cost of 1 request per source, and that a plan-limit message is returned when rate limited or the monthly quota is exhausted — useful operational context an agent cannot get elsewhere.

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?

Front-loaded with what it returns, then the distinguishing use case, then cost and error behavior. Every sentence carries distinct information; no restatement of the tool name 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?

No output schema exists, so the description must describe return values — and it does, enumerating item types, engagement metrics and top comments. Combined with cost and quota-message disclosure, an agent has everything needed to call this correctly and interpret limits.

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 baseline is 3. The description still adds meaning by tying results to sources ('per source') and clarifying that comments and engagement are per-item, which explains how the source, limit and comments parameters interact.

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-plus-resource: retrieves what people are posting, reading and betting about a keyword right now, returning posts, videos, news, discussions and prediction markets. It also explicitly distinguishes itself from the measurement siblings ('get_time_series and get_growth measure how much'), so an agent can pick correctly without opening another 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?

Gives an explicit use case ('use it to explain why something is trending or what the conversation says') and names the alternative tools with the condition that selects them (measurement vs. explanation). Nothing about when to reach for it is left 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds value beyond them: output values are on a 0-100 scale with absolute volume when available, and rate-limited or quota-exhausted requests return a plan-limit message rather than data. It stops short of describing response structure per window, but the scale and failure mode are disclosed.

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 is front-loaded in the first sentence, and alternatives follow immediately. The final two sentences on app-source caveats and plan limits are somewhat dense and partially duplicate schema text, but each carries actionable 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 carries the burden of explaining returns, and it does so at a high level (0-100 scale plus absolute volume). Rate-limit behavior is covered. What's missing is the shape of the per-window result, but the essentials for calling correctly are present.

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 per-parameter meaning is already fully documented in the schema. The description mostly restates it ('each window is a preset string') and adds no new syntax or constraints for country, language, or resolution. Baseline 3 applies when 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?

States a specific verb and resource ('Point-to-point growth for a keyword on one or more sources') with explicit scope. It distinguishes itself from siblings by naming get_time_series for full series and get_top_trends for live app boards, so an agent can choose without opening another 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?

'Designed for growth questions; for charting or custom math, get_time_series provides the full series' gives an explicit use case and a named alternative with the condition that selects it. The clarification that App Downloads/App Rankings are keyword sources rather than the live boards on get_top_trends prevents a realistic misselection.

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, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond them: the 0-100 normalized value range, optional volume, and the fact that a plan-limit message is returned on rate limiting or monthly quota exhaustion. It stops short of describing series length, gaps, or response envelope details.

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 compact sentences, front-loaded with the core capability and followed by alternatives and the quota caveat. Slightly clipped phrasing ('get_growth answers most growth questions with less data') reads as telegraphic but wastes no space.

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 5 parameters, 100% schema coverage, no output schema, and full annotations, the description covers purpose, routing, output scale, and quota failure mode. Return structure is only sketched (values plus volume) but the missing detail is minor given the schema's thoroughness.

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%, and the source parameter already documents per-source keyword formats, country, language, and resolution constraints in detail. The description only reinforces the single-source-per-request rule, adding little beyond what the schema carries. Baseline 3 is correct when 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?

States a specific verb and resource ('Full historical series for one keyword and one source') and immediately qualifies the output shape (0-100 values, plus volume when available). It explicitly names two siblings it is not (get_top_trends, get_growth), so an agent can route without opening any 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?

Gives positive usage ('Suited for charting or custom math') and explicit alternatives with conditions: get_top_trends for live trending boards, get_growth for most growth questions with less data. This is the when/when-not/alternative pattern done properly.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing that data is fetched live every call with no storage, and that a plan-limit message is returned on rate limiting or monthly quota exhaustion — operationally important for an agent's retry logic. It stops short of describing the actual post payload or ordering, so it is very good rather than complete.

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 short sentences, each carrying distinct information: what it returns, freshness semantics, when to pick it, the sibling alternative, and the failure mode. The core scope is stated first with no preamble.

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 conveys the shape at a high level ('top posts' per hashtag/source) and covers the quota failure mode. Slight gap: it does not describe ordering or how results are ranked, nor whether an empty result is possible for an unknown hashtag.

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 schema documents all three parameters including the valid source values and the limit default/min/max, so the description correctly defers. It adds nothing extra about parameter behavior, which is the expected baseline here.

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 and resource ('Live top posts') bounded to exactly one hashtag and one source, and explicitly contrasts with the sibling that ranks hashtags instead. An agent can distinguish it from get_top_trends without opening either 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?

'For when the user already has a hashtag and wants the posts winning on it' gives the selecting condition, and 'get_top_trends ranks the hashtags themselves' names the alternative and its own condition. Both sides of the routing decision are explicit.

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 establish readOnly/idempotent/openWorld, yet the description adds real behavior: a live fetch occurs when the requested board isn't in the database, short windows on weekly/monthly feeds return a note pointing to a longer window, and rate-limited or quota-exhausted requests return a plan-limit message. These are operational traits an agent cannot infer from annotations or 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?

Front-loaded with the core purpose and the key constraint ('No keyword'), then layered with exceptions. Some redundancy with the schema – the six category-dependent board names are repeated verbatim from the type description – but every sentence carries operational 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 7-parameter, no-output-schema tool with sibling alternatives, the description covers usage, fallback behavior, quotas, and partial return semantics (plan-limit messages, mover row fields). It stops short of 5 because the general row shape for non-mover results is left entirely unstated with no output schema to fill the gap.

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; the description earns a bump by explaining cross-parameter relationships the schema lists only per-property – that window is meaningful only under sort='rank_change' and that category 'selects the board' rather than filtering results. It largely restates the parameter list, so it stops short of 5.

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?

Opens with a specific verb and resource ('Live top-trending board for exactly one feed type') and enumerates the board families it covers. It explicitly contrasts itself with siblings by stating 'Live boards are only available here, not via get_time_series,' so an agent can separate it from get_time_series and get_growth without opening a 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?

Gives concrete when-to-use rules: sort='rank_change' for climbers with a named window set, category required for six specific boards, and category omitted only on a first pull to learn official names. It also names the correct alternative for App Store history (get_growth or get_time_series with source App Downloads/App Rankings).

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context not in the annotations: 'Free: does not use a request,' which matters for quota-awareness. It stops short of describing return format/pagination but no output schema exists.

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, zero waste, with the return contents front-loaded ahead of the invocation guidance. Nothing extraneous.

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 zero params and no output schema, the description fully covers what the tool does and what it returns (plan, used, left, reset time) plus the cost note. An agent has everything needed to call it 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?

The tool takes zero parameters, so the baseline is 4. The schema is empty and there is nothing for the description to compensate for; no confusion is possible.

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?

Names a specific verb ('Shows') and enumerates the exact resource fields returned: plan, requests used, remaining, and reset time. An agent can clearly distinguish this diagnostic tool from the analytics siblings (get_growth, get_time_series, get_top_posts, get_top_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?

Gives explicit trigger conditions: 'when the user asks about their limit' and 'after a limit error.' Clear invocation context. It doesn't name when-not-to-use or an alternative, but the siblings are unrelated analytics tools so an exclusion is less necessary.

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