Read a playlist

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

Annotations already cover the read-only and open-world profile, so the bar is lower, and the description still adds real behavioral context: a 12-hour cache with a refresh escape hatch, and the hard limitation that Spotify-made playlists (Discover Weekly, Blend, Top Hits) cannot be read by new apps. That access restriction is exactly the kind of non-obvious constraint an agent needs.

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 dense sentences, front-loaded with the action and inputs before moving to views and caching caveats. No filler and every clause carries operational information.

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?

There is no output schema, so the description carries return-value burden, and it partly does so by naming the fields each view returns (artists/decades/counts; year, ISRC, URI; artist counts). Pagination mechanics for the tracks view are the main unaddressed gap.

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 40%, so the description must compensate. It does clarify the 'playlist' input forms and the 'view' options, but 'limit' and 'offset' (paging) are never explained beyond the schema's bare 'default 50' and the description's single word 'paged'. Partial compensation only.

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?

Opens with a specific verb+resource ('Read any playlist into a structured list') and enumerates the full range of accepted inputs (Spotify/Deezer link, library name, draft id, "library"). It does not explicitly contrast itself with siblings like analyze_playlist or expand_playlist, which is the only thing keeping it off a 5.

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 three views, the 12-hour cache, and the refresh flag give clear context for how to call the tool, but there is no guidance on when to choose read_playlist over analyze_playlist, expand_playlist, or compare_playlists. Usage is implied rather than stated.

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