The Apple Podcasts genre tree

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

Annotations already declare readOnly and idempotent, so the safety profile is covered. The description adds genuinely useful behavioral context beyond those hints: the data is fetched live rather than hardcoded, and the returned categories are Apple's filing categories, not chart categories. This helps an agent avoid stale or wrong assumptions.

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 compact and every sentence earns its place: what the resource is, how it is fetched, how the ids connect to another tool, and a crucial limitation. It is front-loaded with the core purpose and does not waste tokens.

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 read-only list endpoint with two well-documented optional parameters, the description is largely complete: it states what is returned, that it is live, and how the values relate to search. It doesn't describe the exact response envelope or whether subcategories are included by default, but the input schema covers the top_level_only toggle and no output schema is required to infer basic shape.

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 fully documents storefront and top_level_only, including default behavior and country-dependence. The description adds no extra parameter-level meaning; it only relates the returned ids to search_podcasts, which is useful but not about a specific 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 identifies the exact resource ('Apple's podcast categories and their numeric ids') and the action implied by the tool name: listing the genre tree. It also distinguishes the tool from chart-oriented endpoints by explicitly stating these are not charts and no chart can be requested for a genre.

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 this tool matters: the returned ids are exactly what search_podcasts uses as genre_id. It also provides a firm when-not boundary: genres are not charts and cannot be used to request charts. It doesn't name an alternative sibling for chart data, but the exclusion is explicit.

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