sonos_list_music_services

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

With no annotations provided, the description successfully conveys the key behavior: most services require authentication (authType: DeviceLink or AppLink) and will not work unless linked in the Sonos app. It also clarifies that 'Anonymous' services do not require authentication. It does not mention side effects or permissions, but the core behavioral nuance is well-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 sentences plus a bolded IMPORTANT note. It is front-loaded with the main purpose, and every sentence adds significant value. There is no redundant or extraneous information.

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?

Although there is no output schema, the description briefly states what the return value includes (name, ID, authentication type). The tool is simple with one required parameter, so the description is largely complete. However, it could be more detailed about the structure of the response or edge cases like missing services.

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 already provides 100% description coverage for the single `deviceId` parameter, describing it as 'Device ID to query for available services'. The description does not add additional meaning or context about how to obtain the device ID or any constraints, so the baseline score of 3 is appropriate.

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 it lists available music services registered with the Sonos system, providing examples (Sonos Radio, TuneIn, Spotify) and specifying the returned details (name, ID, authentication type). This distinguishes it from sibling tools that focus on playback, control, or browsing other content.

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 provides crucial context about authentication requirements for most services, helping an agent decide when this tool is needed. However, it does not explicitly state when not to use it or offer alternatives like `sonos_search_music_service` or `sonos_browse_music_service`.

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