artist_collection_gaps

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

With no annotations provided, the description carries the behavioral burden. It discloses a significant operational trait: this is a paginated walk requiring a saved-albums membership check, which implies quota cost and multiple API calls. The red-circle quota warning is useful beyond what the schema conveys, though it does not mention read-only status or auth requirements.

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 description is two sentences with no filler. The core purpose is front-loaded, and the quota warning is compact but informative. Every element earns its place.

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?

The description covers the tool's purpose and a key operational cost, but it omits usage routing and leaves max_results semantics unexplained. Since there is no output schema and sibling tools overlap significantly, the description could be more complete with a note on when to choose this over related gap/completeness tools.

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?

The schema describes artist_id and response_format but leaves max_results undocumented, and the description adds no parameter-level detail. The phrase 'studio albums' clarifies the output domain but does not help an agent understand max_results behavior, defaults, or how response_format affects the result. With 67% schema coverage, the description should compensate for the missing max_results semantics but does not.

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 a specific verb ('List'), a specific resource ('an artist's studio albums'), and a clear filtering condition ('missing from your saved collection'). It also states the intended outcome ('the exact records to add next'), which distinguishes it from broader catalog or discography tools like get_artist_discography or artist_discography_gaps.

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 description implies a use case — finding what to add next to one's saved albums — but it does not explicitly state when to use this tool versus similar sibling tools such as artist_discography_gaps, artist_album_completeness, or artist_complete_check. There are no alternatives, exclusions, or preconditions mentioned.

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