Playlist and podcast-series performance

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: it explains what each metric means (e.g., viewsPerPlaylistStart as the 'binge metric'), how grouping changes the output, and that the tool automatically sends a sort order when ranking by playlist. This goes well beyond the 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 compact and front-loaded with the core purpose, followed by a list of key metrics and grouping guidance. Every sentence contributes meaning without redundancy or fluff, making it efficient and well-structured.

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 complexity (6 parameters, no output schema), the description covers the purpose, key metrics, grouping modes, and sort behavior sufficiently. It doesn't explicitly describe the response row format, but the schema's group_by descriptions handle that, and the description provides enough context for an agent to select and invoke 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 descriptions cover all parameters (100% coverage), so the baseline is 3. The description adds value by semantically interpreting the metrics (e.g., playlistStarts as 'began the series') and clarifying the effect of group_by values, which enriches understanding beyond the schema's enum 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 reports playlist performance as a series-level view, with specific metrics like playlistStarts and viewsPerPlaylistStart. It distinguishes itself from video-level tools by saying 'not just as bags of videos' and explicitly framing podcasts as playlists, making the resource and action unambiguous.

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 explains the grouping options ('playlist', 'day', 'none') and the sort-order requirement, giving clear context on how to use the tool. However, it does not explicitly name alternative sibling tools or state when not to use it, though the 'not just as bags of videos' contrast hints at when video-level tools are more appropriate.

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