user_get_top_artists

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

The readOnlyHint annotation already establishes this is a safe read, so the description's job is to add context. It does contribute one useful behavioral detail — results carry play counts and are bounded by a time window — but it says nothing about ranking order, whether ties or scrobbles are counted, or how pagination behaves past the limit.

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?

A single front-loaded sentence with no filler and no repetition of schema content. It is efficient, though slightly under-specified rather than lean by design.

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 four-parameter, zero-required read tool with full schema coverage and no output schema, the description covers the essentials: what is returned, that counts are included, and that a time window scopes it. Only return-shape details such as ordering and the artist payload fields are left implicit.

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 all four parameters (page, user, limit, period) are already fully documented including defaults, bounds and the enum values. The description's only semantic contribution is corroborating that a time window exists; it adds no format or behavior detail beyond the schema, so baseline 3 applies.

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 pair ('most played artists') plus a scope ('the user's, in a time window, with play counts'), which is enough to separate it from user_get_top_tracks, user_get_top_albums and tag_get_top_artists. It never names those siblings explicitly, so differentiation is inferential rather than stated.

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 only implied: the phrase 'most played artists in a time window' tells an agent the situation it fits, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as user_get_weekly_artist_chart or user_get_recent_tracks for finer-grained listening history.

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