Get my top tracks or artists

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

With no annotations, the description must carry the transparency burden. It implies a read-only operation ('read this', 'listening history') and usefully discloses that recommendation/audio-feature endpoints are no longer available. However, it does not explicitly state the return shape, ranking/count behavior, or any auth/error considerations, leaving part of the behavioral contract implicit.

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 core purpose and workflow are front-loaded, and each sentence adds context: what the data is, when to read it, and how to use it with search_tracks. The final sentence partly repeats the earlier 'ground picks' instruction, making the description slightly longer than necessary, but it remains tight and readable.

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 top-items getter with no output schema and no annotations, the description nicely covers when and how to use the tool in the playlist-building workflow. The main gap is that it never describes what the returned objects look like or whether they include URIs, which an agent would need to know for downstream steps.

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?

Only time_range is described in the schema (33% coverage). The description adds context around 'top tracks or artists' and the notion of listening history, which gives meaning to the type parameter, but it does not add detail about limit or how the ranking is determined. The schema's enums/defaults and time_range description do some of the work, so the description provides partial but not complete compensation.

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 names the resource ('the user's actual listening history') and the action (top tracks or artists), and differentiates it from sibling tools by positioning it as the personal-taste grounding source rather than catalog search or playlist management. The title reinforces the tracks-or-artists output, so an agent can distinguish it from search_tracks at a glance.

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?

It gives explicit when-to-use guidance: read this before building an own-taste playlist, then choose similar music, then resolve picks via search_tracks. It also explains an alternative that no longer exists (recommendation/audio-feature endpoints), preventing the agent from attempting unavailable calls.

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