Apple's Trending Episodes chart

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar for added value is context beyond safety. The description adds that the chart is 'live' and 'moves far faster,' signaling volatile results across calls, and discloses the entry shape (episode id plus owning show). This enriches the annotations without contradicting them.

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 sentences, each earning its place: the first names the resource, the second explains differentiation and usage value, the third states the return payload. The core purpose is front-loaded before the comparative context. No filler or repetition of schema content.

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 two-parameter read-only tool with rich annotations and fully covered schema, the description is nearly complete. It even compensates for the missing output schema by stating that entries carry episode id and show. The only minor gap is that the temporal window of 'trending' is unspecified, but 'live' largely covers this. An agent has enough to select and call 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 description coverage is 100%, so the baseline of 3 applies; limit and storefront are already fully documented in the schema. The description adds marginal reinforcement by noting the chart is per-storefront, which aligns with the storefront parameter, but adds no new syntax or format details. It does not need to compensate for any coverage gap.

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 and resource: it retrieves Apple's live Trending Episodes chart for one storefront. It actively differentiates from a sibling by contrasting with Top Shows, and clarifies the granularity (episode-level rather than show-level). An agent can tell this apart from get_top_shows, find_chart_position, and list_recent_episodes 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?

The description gives clear context for when to choose this tool: it is the better signal for what a topic or guest is doing right now because a single episode can chart without its show ranking. It names the alternative (Top Shows) and explains why it differs. However, it stops short of an explicit when-not or explicit routing to other siblings such as find_chart_position, so it earns a 4 rather than a 5.

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