Top artists over a date range

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: inclusive local dates, a default 30-day window, a 3,660-day max span, and the policy of crediting every artist on a track. It stops short of describing return structure or error behavior.

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?

Four tight, front-loaded fragments communicate purpose, ordering, counting semantics, defaults, and range limits. Every sentence earns its place with no filler or redundancy.

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?

With no output schema, the description is expected to carry more return-value context. It conveys output ordering and a key counting rule but does not specify the returned fields (e.g., artist name, id, count) or pagination behavior. Those are minor gaps for a straightforward list tool.

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. The description adds value beyond the schema by clarifying that dates are local and inclusive, and by specifying a maximum range of 3,660 days that is not expressed in the schema. It does not add meaning for the limit parameter beyond the schema's stated default.

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 resource (play counts per artist), scope (between two local dates, inclusive), ordering (most played first), and notable counting semantics (credits every artist on a track). It clearly distinguishes the output from a simple per-track count, but does not explicitly differentiate this tool from siblings like top_tracks or artist_history.

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?

Usage is implied: retrieve top artists over a date range, with defaults and a maximum span given. However, there is no explicit when-to-use guidance or comparison to alternatives such as top_tracks, artist_history, or search. It leaves the agent to infer the selection context.

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