followed_artists

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

With no annotations, the description carries the full burden, but it does disclose a genuine behavioral trait: the required user-follow-* scopes. Beyond that it says nothing about pagination, ordering, or result shape for what is presumably a paged list endpoint.

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?

It is short and front-loaded, which is good, but the parenthetical repeats the scope requirement verbatim ('needs follow scope — needs the user-follow-* scopes'), wasting the only sentence of substance.

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 list-style tool with one optional parameter and no output schema, the definition is still too thin: no indication of what the agent gets back, how limit affects results, or how this differs from the sibling follow_artists. Only the auth scope is covered.

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?

There is one parameter (limit) with 0% schema description coverage, so the description must compensate and does not — it never mentions limit, its default, or its accepted range. The parenthetical 'needs follow scope — needs the user-follow-* scopes' restates the same requirement twice instead.

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 names the resource ('artists you follow') and implies a read/list operation, but it is a noun fragment with no verb. It is separable from follow_artists/unfollow_artists only by name inference, not by anything stated in the text.

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?

There is no when-to-use guidance or mention of alternatives such as follow_artists (which adds follows) or artist_catalog (which looks up artist data). The only condition given is an auth prerequisite, not a usage condition.

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