Play music

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

With no annotations at all, the description carries the full burden of disclosing side effects. It clearly explains that 'load' replaces the queue and plays, 'add' appends, and 'insert' plays next, which are key behavioral traits. It stops short of describing return values or error handling, but the core state-changing behavior is 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?

The description is two tight sentences with no filler. The main action and two input types are front-loaded, and the second sentence efficiently maps all three enum values to their concrete behaviors. Every sentence 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 tool has 8 optional parameters, no output schema, and no annotations, yet the description avoids explaining the id fields, player selection, or mutual-exclusion rules. It explains the core playback modes but leaves an agent guessing about how to construct a valid request, especially because 'library id' could map to albumId, artistId, trackId, genreId, or playlistId.

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 only 13%, so the description must compensate. It adds meaning to the 'mode' enum and clarifies that the various id fields are library ids. However, it does not explain which parameter combinations are valid (e.g., whether ids are mutually exclusive, whether 'url' can be combined with ids, or the role of 'player'), leaving significant ambiguity for several of the 8 parameters.

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 clearly states the tool loads or queues music, identifies two input sources (library id from search_library and direct URL), and explains playback behavior for each mode. This makes its purpose specific and distinguishes it from search-focused siblings like search_library and queue-edit operations.

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 when to use the tool: after searching the library or when you have a direct URL. It also explains what each mode does, which helps select the correct mode. However, it does not explicitly compare against alternative siblings like queue_edit or playback_control, so exclusion guidance is weak.

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