Trends API

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

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these: it specifies the 0-100 scale, availability of absolute volume, and the plan-limit message on rate limiting/quota exhaustion. It also clarifies the keyword format constraints for special sources, which is behavioral context 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?

The description is efficient, with every sentence serving a purpose: it defines the tool, explains the value scale, differentiates from siblings, clarifies special source keyword rules, and discloses rate-limit behavior. It is well-structured, front-loading the core purpose and then addressing edge cases. No filler or redundant 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?

Given the tool's moderate complexity (3 params, all documented), no output schema, and rich annotations, the description is complete. It covers the return scale, absolute volume, plan-limit errors, source-specific keyword requirements, and the exact preset window list (implicitly via schema but reinforced). 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?

Schema coverage is 100% with detailed descriptions, so baseline is 3. The tool description adds substantial meaning: it explains the source-specific keyword formats (npm exact package names, PyPI exact names, Steam display names, Android bundle IDs), provides concrete examples and wrong usages, and clarifies the rule when mixing app sources with others. This goes well beyond the schema's generic 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 computes point-to-point growth for a keyword on one or more sources, with specific details on value scale (0-100) and absolute volume. It explicitly distinguishes from siblings: get_time_series for charting/custom math and get_top_trends for live boards, so an agent can immediately identify the right 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?

It gives explicit when-to-use guidance: 'Designed for growth questions' and directs to get_time_series for charting or custom math. It also clarifies that app downloads/rankings are not the live boards on get_top_trends, preventing confusion. Rate-limit and quota behavior is disclosed, which is operational 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 establish read-only, idempotent, non-destructive behavior. The description adds useful non-annotation behavior: the 0-100 value range, optional volume data, and the plan-limit message on rate limiting or quota exhaustion.

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 sentences, each earning its place: purpose, use case, sibling alternatives, and error behavior. The most important information is front-loaded.

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 2-parameter read-only tool with a fully documented schema, the description covers the main return characteristics, error/limit behavior, and alternatives. It does not describe the exact output structure, but no output schema exists and the description gives enough shape (0-100 values plus optional volume).

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 source and keyword properties are already richly documented. The description mentions 'one keyword and one source' but adds no 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 verb-resource relationship: it returns the full historical series for one keyword and one source. It also distinguishes itself from siblings by explicitly routing live boards to get_top_trends and growth questions to get_growth.

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 concrete usage context ('Suited for charting or custom math'), names an alternative for live data, and points to get_growth for most growth questions. This is explicit enough for an agent to choose between tools without opening schemas.

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 the tool as read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context beyond that: data is fetched live on every call, nothing is stored, and a plan-limit message is returned on rate limiting or quota exhaustion. No contradiction 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?

Four short sentences, each earning its place: the core purpose, live-fetch behavior, usage context, the sibling differentiator, and the rate-limit behavior. Information is front-loaded and no words are wasted.

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 three-parameter read-only tool with no output schema, this description is complete enough for an agent to select and invoke it correctly. It covers when to use it, what it returns conceptually ('top posts'), live behavior, storage, and error signaling. The missing structured return details are not necessary for 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 description coverage is 100%, with clear parameter documentation for keyword normalization, valid sources, and the limit bounds/default. The description adds broader context about one hashtag and one source but does not meaningfully enrich individual parameter semantics 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 opens with a specific verb-resource pair: 'Live top posts for one hashtag on one social source.' It clearly distinguishes itself from the sibling by stating 'get_top_trends ranks the hashtags themselves,' so an agent can tell the two tools apart.

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: 'when the user already has a hashtag and wants the posts winning on it.' It also names the closest alternative and what that tool does instead, giving clear selection 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 readOnly/idempotent annotations, the description discloses meaningful behavior: boards not yet in the database are fetched live, App Store and Google Play boards are live store boards rather than keyword lookups, and rate-limited or quota-exceeded requests return a plan-limit message. No contradiction 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 dense but every sentence earns its place: purpose is front-loaded, then category behavior, sort/window semantics, live-fetch behavior, sibling alternatives, and a rate-limit note. No filler or repetition of the schema's enums.

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 complex tool with seven parameters and no output schema, the description covers the key operational details an agent needs: feed type restrictions, category requirements, sort and window behavior, live fetching, alternative tools for history, and rate-limit response behavior. Nothing critical is 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?

The input schema already documents all seven parameters thoroughly, so the bar is high. The description adds useful parameter-adjacent context about `sort`/`window` semantics, the role of `category` in selecting boards, and the fact that some types are live store boards rather than keyword lookups, though much of it echoes 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 states a specific operation: return the live top-trending board for exactly one feed type, with no keyword. It also clarifies which feed types require a category and distinguishes this tool from history-style siblings by noting live boards are only available here, not via get_time_series.

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 provides explicit when-to-use guidance: use category for specific board types, use sort='rank_change' for climbers over a window, and use get_growth or get_time_series for app history. It also states a clear when-not: live boards are not available via get_time_series.

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, so the safety profile is covered; the description adds a genuinely non-obvious trait: 'Free: does not use a request,' which tells the agent this call is quota-neutral and safe to repeat. It also points to an upgrade URL for the 'need more' case. It stops short of describing the exact response shape, but that is a modest gap.

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 primary outcome, then the quota-cost note, then the trigger condition, then the upgrade link – every sentence is short and earns its place. The trailing marketing URL is slightly tangential but contextually relevant after a limit error.

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 input parameters and no output schema, the description bears the burden of explaining the return payload, and it does so by enumerating all four returned values. An agent has everything needed to call it and to interpret the result.

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 there is nothing for the description to disambiguate; baseline 4 applies. The absence of any parameter discussion is correct rather than an omission.

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 ('Shows') and enumerates exactly what is returned: plan, requests used this month, requests left, and reset time. This clearly distinguishes it from the sibling data-retrieval tools (top posts, trends, time series), which return analytics rather than account state.

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 two concrete invocation triggers: the user asking about their limit, or a limit error having occurred. That is actionable guidance beyond mere implied usage. It does not state when not to call it or name an alternative, but no sibling covers this ground, so the omission is minor.

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