taste_forgotten_bangers

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

With no annotations to carry the safety profile, the description explicitly declares read-only and no-auth behavior, and explains the algorithm (lifetime tops missing from recent sample, revival pick). It does not fully describe return formatting, but the main side-effect and auth traits are disclosed.

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 tightly packed sentences present the purpose, algorithm, and safety model with no filler. The critical read-only/no-auth information is clearly separated and easy to scan.

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 schema fully documents parameters, but because there is no output schema and no annotations, the description should say more about what the returned 'playlist spec' looks like and how it compares with similar taste tools. The read-only/no-auth statement and domain recipe make it minimally viable but not fully complete.

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%, with defaults and meanings for all five parameters, so the description does not need to restate them. The description adds only loose domain context (lifetime tops, recent sample) rather than mapping parameters to behavior, keeping this at the schema-driven baseline.

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 identifies a concrete output ('forgotten-bangers playlist spec') and gives a distinct data recipe: lifetime top tracks missing from the recent sample, ranked with a revival pick. It is clear enough to distinguish from generic taste tools, though it stops short of naming sibling alternatives or using an explicit verb like 'generate'.

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 'Read-only, no auth' phrase gives useful selection context and implies it is safe to call without credentials, but there is no explicit when/when-not statement or pointer to comparable siblings such as taste_revival_queue or forgotten_favorites. Usage is only implied by the tool's domain name.

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