track_rotation_report

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

With no annotations provided, the description carries the full burden, and it does solid work: 'Quota: GET /me/player/recently-played cursor walk' discloses that the tool consumes API quota and paginates through history — the key behavioral trait an agent needs before invoking a possibly multi-call operation. It also states the default 150-item window. It stops short of explicitly noting the operation is non-mutating, though 'Report' implies read-only.

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?

Two sentences with zero filler: the first front-loads the purpose and bucketing behavior, the second appends the quota/pagination warning that matters for agent decisions. Every word earns its place, and the most distinctive detail (heavy/regular/light buckets) leads the description.

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 report tool with no output schema and no annotations, the description covers the essentials: data source (recently-played history), computation (per-track counts with rotation buckets), the default window, and the quota cost of execution. The main gaps are the lack of alternative-tool routing and no description of the returned shape beyond what response_format's enum values imply, but the schema compensates for the format dimension.

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 is 3 and the schema fully documents max_items, max_results, and response_format. The description merely reinforces the max_items default ('default 150 history items') without adding parameter meaning beyond the schema. The pagination hint 'the API pages 50 per call' already lives in the schema, so no extra credit is warranted.

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: 'Report how many times each track appears in recently-played history and bucket them into heavy/regular/light rotation.' The heavy/regular/light bucketing is a distinctive behavior that separates it from plain history tools like get_recently_played and from weekly_rotation_report. An agent can understand exactly what computation this tool performs.

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 intended usage is implied — if you want rotation categorization of recently-played history, call this tool — but no alternatives are named and no when-not-to-use conditions are given. Siblings like get_recently_played, most_replayed, and weekly_rotation_report overlap in data source, yet nothing tells the agent how to route among them. The default-window and quota notes provide context but not decision criteria.

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