get_top_trends

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is known. The description adds substantial behavioral context beyond these hints: the board is live, exactly one feed type per call, default sort is current rank, rank_change compares against a prior snapshot with specific windows, and certain store feeds are live boards rather than keyword lookups. The rate-limit/quota handling instruction is also a clear behavioral disclosure. There is 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: core purpose, category requirement, sort/window semantics, differentiation from store keyword lookups, alternative tools, and rate-limit handling. It is front-loaded with the essential purpose and does not contain 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?

Given the tool's moderate complexity, the rich schema descriptions, the presence of an output schema, and the read-only/idempotent annotations, the description covers all remaining decision points an agent needs. It explains which feed types require category, how sorting and windows work, how to distinguish this tool from siblings, and how to respond to rate limiting or quota exhaustion. Nothing critical is missing for correct 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?

The input schema already documents every parameter with 100% coverage, so the baseline is 3. The description adds meaningful cross-parameter semantics that the schema does not fully convey: which specific feed types require 'category', that 'sort' defaults to current rank and 'rank_change' enables climber comparisons using a 'window', and that the tool is exclusively for live boards rather than keyword or history data. This raises the value above baseline, but because the schema already carries strong per-parameter descriptions, it does not reach 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?

The description opens with a specific, concrete definition: 'Live top-trending board for exactly one feed type. No keyword.' This immediately conveys the resource and its core behavior, and it distinguishes the tool from keyword-based or history-based lookups. It also names the sibling alternatives (get_growth, get_time_series) and explains when they are the correct choice, making the scope unmistakable.

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 gives explicit when-to-use and when-not-to-use guidance. It states which feed types require the category parameter, that sort='rank_change' is for climbers with a prior snapshot, and that App Store/Google Play boards are live and not keyword searches. It directly addresses alternatives: 'For an app's history use get_growth or get_time_series... Do not use get_time_series for live boards.' It even instructs how to handle rate limits and quota exhaustion.

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