ZoneFoundry for Sonos

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the relative adjustment context and that current level isn't needed, but doesn't disclose additional behavioral traits like failure modes or side effects. Since annotations cover the safety profile, a 3 is appropriate.

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?

One sentence that front-loads the core action and constraint. No fluff, every word 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?

For a simple two-parameter tool with annotations, the description is adequate. It explains the relative nature and delta range, but doesn't explicitly differentiate from set_volume. That gap is minor, so a 4 is warranted.

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 coverage is 50%, with delta lacking a description. The description compensates by explaining delta as a relative amount (-30 to 30) and that current level isn't needed, but doesn't specify units or semantics beyond that. This adds some value over the schema.

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?

States a specific verb (raises/lowers) and resource (room's volume), with the relative nature distinguishing it from set_volume. It's not a tautology and clearly communicates the tool's function.

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?

Mentions that it's a relative adjustment and that current level isn't needed, implying it's for when a relative change is desired. However, it doesn't explicitly name the alternative (set_volume) or state when not to use it, so it's clear but not fully explicit.

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

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

Beyond the minimal annotations, the description discloses the important side effect that music pauses and resumes, and it adds the rate limit ('at least 8 seconds apart') and language default behavior. This is valuable behavioral context for an agent.

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?

Three compact sentences deliver the core action, constraints, and language behavior with no filler. The most important information is front-loaded.

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?

Together with a well-described schema, the description covers the target, the behavior, the limits, and optional language handling. Nothing essential is missing for correct invocation.

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 documents room, text, and volume well. The description adds meaning for the otherwise undocumented language parameter by listing allowed values and explaining the fallback to the home's preference, plus the multi-item text behavior.

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 a specific verb ('Speaks') and resource ('a room's Sonos speaker using text-to-speech'), making the tool's function unmistakable and distinct from sibling playback and volume tools.

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 gives concrete usage constraints: up to 300 characters, at least 8 seconds apart, support for multiple items, and language fallback. It does not explicitly name alternatives or exclusions, but the TTS use case is unambiguous.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses significant behavior: the reply-based interaction model, the needs_user_answer question flow for ambiguous time/day/room, and the fallback where without the bridge tracks play directly on the speaker and are queued until the app is reopened. This is meaningful side-effect disclosure the annotations alone do not convey.

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 purpose and interaction model are front-loaded in the first sentence, followed by capability scope, fallback behavior, and examples. It is a dense single paragraph and somewhat run-on, but each sentence carries distinct information and nothing is redundant.

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 complex, open-world natural-language tool with no output schema, the description covers what it does, what it returns (a reply or a clarifying question), supported domains, languages, services, aliases, and the no-bridge fallback. An agent has everything needed to call it and interpret the result.

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%, so the schema already documents both parameters and their formats, giving a baseline of 3. The description adds value by illustrating the instruction parameter with concrete examples in English and Chinese and by explaining the needs_user_answer behavior when a time, day or room is unclear, which clarifies how to phrase the instruction.

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 states a specific verb and resource: it sends a natural-language request to the ZoneFoundry assistant, which executes it on the user's Sonos system and returns a reply. It further scopes the tool by listing what it handles (songs, news, announcements, scenes, multi-step requests) and the supported services and languages, which sets it apart from the single-purpose siblings like play_music or adjust_volume.

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?

It gives clear context for when this tool applies, including example utterances ('play some jazz in the kitchen') and the fact that it accepts free-form, multi-step requests that the granular sibling tools do not. However, it never explicitly routes the agent away from alternatives (e.g. 'prefer play_music for a single known track'), so there is no stated when-not guidance.

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

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

Annotations already mark this as destructive (destructiveHint: true), and the description's 'cancels' is consistent with that. The 'pending' qualifier adds a useful constraint, but the description provides little beyond what the annotations already disclose.

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 a single, focused sentence that front-loads the action and object. Every word is necessary and there is no redundant detail.

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 one-parameter tool with no output schema, the description is mostly complete: it states the action, the target, and the parameter. It could add a note that the reminderId can be obtained via list_reminders or that cancellation is permanent, but these are minor gaps.

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 0%, so the description must clarify the parameter. It mentions 'by its reminderId,' which loosely maps reminder_id, but it does not explain the ID's format, where it comes from, or any constraints. This is minimal compensation for a completely undocumented schema.

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 uses a specific verb ('cancels') with a specific resource ('pending reminder') and identifies the required identifier (reminderId). It clearly differentiates this tool from siblings like set_reminder and list_reminders.

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—canceling a pending reminder—but does not explicitly state when not to use it or mention alternatives such as list_reminders to find a reminderId. Usage context is inferred rather than explicit.

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

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

Annotations only signal readOnly=false and destructive=false. The description adds valuable behavioral detail: `room` remains the playback source while the others join it. This goes beyond what annotations provide and helps predict the operation's effect.

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 written sentences with no filler. The main operation is front-loaded, and the second sentence explains the key behavioral nuance efficiently.

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 low-complexity mutation with 100% parameter coverage and useful annotations, the description is largely sufficient. The only notable gap is the unresolved default-room ambiguity in the schema, which the description does not clarify.

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 coverage is 100%, so the baseline is 3. The description clarifies that `room` is the anchor and `rooms` are followers, but it does not resolve the schema's internal contradiction where `room` is required yet the property description says 'Omit for the default room.'

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 uses a specific verb ('Group') with a clear resource and outcome: one or more rooms join `room` so they all play the same thing. It also clarifies the directional behavior, distinguishing it from ungroup_room and other sibling tools.

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 clearly conveys when to use the tool: when multiple rooms should play synchronized audio with one anchor room. It does not explicitly name alternatives or exclusions, but the use case is evident.

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

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

Annotations already establish it as a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description adds real value: results are in Sonos' stored order, no bridge is required, and favorites are capped near 70 with `total` reflecting the true count. That ~70-vs-total quirk is exactly the kind of behavioral detail an agent cannot infer elsewhere.

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?

Three tight sentences, front-loaded with what is returned, then two short caveats. No filler; each sentence carries distinct operational 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?

With no output schema, the description helpfully discloses the returned fields and the approximate 70-item cap plus `total` semantics. It is nearly complete, lacking only pagination/limit interaction detail.

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 a single `limit` parameter whose schema description is fully covered (100%), so the baseline is 3. The description mentions `total` but does not clarify limit behavior or interaction with the cap, adding nothing beyond the schema.

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?

States a specific verb and resource ('Lists the home's Sonos favorites') and even enumerates the returned fields, which clearly separates it from siblings like list_playlists or search_music. It does not name an alternative explicitly, so it stops short of a 5.

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?

'Works without the ZoneFoundry bridge' is useful context about when this tool is viable, but there is no explicit guidance on when to prefer it over list_playlists or search_music. Usage is implied rather than scoped.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: no ZoneFoundry bridge dependency, and crucially that an error response means the list could not be read rather than being empty — a real ambiguity resolution.

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?

Three short sentences, front-loaded with the core purpose, then a capability note, then the error-semantics caveat. Every sentence earns its place with no filler.

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 zero-param read tool with no output schema, the description covers purpose, fields returned, dependency behavior, and the empty-vs-error ambiguity. Annotations handle the safety profile, leaving little else an agent would need.

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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly lists the output fields a caller will receive 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?

States a specific verb and resource ('Lists the home's Sonos playlists') and even enumerates the returned fields (id, title, track count). This is clearly distinguishable from siblings like list_favorites or list_rooms without opening any schema.

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 note 'Works without the ZoneFoundry bridge' implies when this tool is usable and useful, but there is no explicit when-to-use guidance or named alternative. Usage is only indirectly implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuine scoping constraint (only pending reminders from this connection), but says nothing about ordering, limits, or what an empty result means.

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?

A single tight sentence with the scope qualifiers front-loaded and no filler. Every word carries 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?

For a trivial parameterless read with a full annotation set and no output schema, this is nearly sufficient. Only minor gaps remain (return shape, ordering) that the agent could not infer from the description alone.

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 tool takes zero parameters, so there is no parameter surface for the description to document. Baseline 4 applies; nothing is missing here.

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?

States a specific verb+resource (list reminders) with two meaningful qualifiers: 'pending' and 'created via this MCP connection'. That scope distinguishes it from set_reminder/cancel_reminder siblings, though it doesn't name any sibling explicitly to route the agent.

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?

Usage is implied (call this to see outstanding reminders) but there is no explicit when-to-use/when-not or any named alternative. The agent can infer intent, but nothing routes it between this and the reminder-creation/cancellation siblings.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so safety is covered. The description adds the 'cloud topology' qualifier, hinting the data source is cloud state rather than local devices, which is modest but real context beyond the annotations. It does not describe staleness or refresh behavior.

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?

A single front-loaded sentence with no waste; every phrase (user scope, rooms, groups, cloud topology) carries meaning.

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 no-param list tool with no output schema, the description should ideally sketch the return shape (room identifiers, group membership structure). It names what is returned ('rooms and current groups') but not the fields or format, leaving a gap since no output schema exists to compensate.

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 tool takes zero parameters, so there is no parameter semantics to document. Baseline 4 applies.

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?

States a specific verb (list) and resource (this user's Sonos rooms and current groups), plus scope via 'cloud topology'. It is distinguishable from mutation siblings like group_rooms/ungroup_room by its read nature, though it never names those alternatives explicitly.

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?

No when-to-use or when-not context, and no alternatives are named. The agent must infer from the verb that this is the read path versus group_rooms/ungroup_room, with no explicit routing guidance.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral detail: music continues in to_room, stops in from_room, and grouped rooms keep playing. This is valuable context that goes beyond the annotations and helps predict side effects.

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 entire description is one efficiently structured sentence. It leads with the action, then specifies the effects on both rooms and includes the important grouped-room exception without any wasted words.

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 two-parameter tool with no output schema and simple semantics, the description covers the core behavior and an edge case (grouped rooms). It does not describe return values or error handling, but these are typically not essential for such a direct command, so the definition is near-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 coverage is 100%, so the baseline is 3. The description adds value by linking the parameters to their operational roles ('music continues in to_room' and 'stops in from_room') and clarifies the grouped-room caveat for from_room. This is more than the schema alone provides.

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 uses a specific verb ('Moves') and resource ('what's playing') and clearly distinguishes the behavior from siblings like play_music or switch_source. It states the outcome for both rooms and even handles the grouped-room nuance, making the tool's purpose unmistakable.

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 clearly implies when to use the tool: when the user wants to transfer currently playing audio from one room to another. It provides the behavioral context (music continues in to_room, stops in from_room) but does not explicitly mention alternatives or when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutating and non-destructive nature is known. The description adds the 'room's group' context but does not disclose any additional side effects (e.g., whether playback stops, if it affects the whole group). It provides minimal extra behavioral value beyond the annotations.

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 a single sentence with no redundant words. The action is front-loaded ('Skip to next track') and the context is appended efficiently. Every word 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?

For a simple tool with one optional parameter and no output schema, the description covers the basic action. However, it does not explain the concept of a 'room's group' or clarify interactions with playback state. Given the many siblings, more explicit guidance on when to use this tool would improve completeness.

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 input schema fully documents the 'room' parameter, including aliases and default behavior, with 100% coverage. The description adds no parameter-specific information, so it does not enhance what the schema already provides. Baseline 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 states a specific verb ('skip'), a resource ('track'), and a context ('in a room's group'). It clearly distinguishes from the sibling 'previous_track' by specifying 'next'. No ambiguity about the tool's core function.

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 usage for advancing to the next track but does not explicitly contrast with alternatives like 'previous_track' or 'toggle_play_pause'. There is no when-to-use or when-not-to-use guidance, though the context of 'room's group' hints at a scoped action.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. With no output schema, the description's enumeration of return fields (track/artist/state/volume) does add useful context, but it stays shallow and says nothing about pagination, freshness, or behavior for idle rooms.

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?

A single front-loaded sentence that packs purpose, scope, and return fields with zero filler. It is efficient, though its extreme terseness leaves some behavior unstated.

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 single-parameter, read-only query tool with full schema coverage, the definition is largely sufficient, and the field list compensates for the absent output schema. Minor gaps remain around what is returned when nothing is playing and whether volume reflects the room or the group.

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% and the single room parameter is fully documented, including alias handling and the default-room behavior. The description only echoes the room scoping ("for a room") and adds no syntax or semantic detail beyond the schema, so baseline 3 applies.

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 resource (current playback state) and enumerates the returned fields (track/artist/state/volume), scoped to a room. It is clearly distinguishable from siblings like play_history or toggle_play_pause, though it does not explicitly name a counterpart tool.

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 word "Current" implies this is the tool for checking what is playing right now rather than past playback, but no when-to-use or when-not-to-use guidance is given and no alternative is named. Usage is inferable but not stated.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing what the data actually represents, which sources feed it, which do not, and critically that entries hold request text only with no structured track/artist fields. That last point materially changes how an agent must parse results.

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 dense sentences, front-loaded with the core action and ordering before the scope caveats. Slightly long, but every clause (channel coverage, exclusions, entry shape) carries useful information rather than padding.

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?

With no output schema, the description compensates by describing what entries contain and the absence of structured fields. Combined with the exhaustive channel coverage/exclusion list, an agent has everything needed to call and interpret this tool.

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%, and the schema fully documents days, limit, and include_failed with defaults and maxima. The description adds no additional parameter semantics, so the baseline 3 applies.

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?

States a specific verb+resource (list recent requests made to ZoneFoundry) with ordering ('newest first') and scope. It is clearly distinguishable from siblings like now_playing (current state) and search_music (catalog lookup).

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?

Gives substantial when-to-use context by enumerating the channels that DO produce entries (assistant, app voice/command, messaging bots, this connection) and explicitly excluding browsing-started playback. It does not name a sibling alternative for adjacent needs (e.g. now_playing), so it stops short of a 5.

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

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

Annotations only declare it is a non-read-only, non-destructive, open-world call; the description adds real substance beyond that: playback runs through the Sonos cloud, and without the ZoneFoundry bridge tracks play directly and are queued later. It does not state auth/prerequisite details or what happens on a failed match, so it stops short of a 5.

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?

Three sentences, front-loaded with the core action before the query-shape rules and the bridge caveat. Dense but every sentence carries information; minor cost is that the queue/bridge detail trails into the final sentence.

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?

With no output schema, the description should cover behavior and outcomes, and it does: playback target, batch vs single behavior, deduplication, and the no-bridge fallback path. Missing only failure modes (e.g. no matching track) and any permissions requirement, which keeps it at 4 rather than 5.

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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains that a lone artist name yields a batch with duplicate titles removed, and that track counts derive from query shape. This clarifies the interaction between query and count beyond the schema's per-field text.

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?

States a specific verb and resource ('Searches for a song or artist and starts playback in a room through the Sonos cloud'), which is more specific than the title alone. It implicitly separates itself from the sibling search_music by adding 'starts playback', though it never names that sibling to make the distinction explicit.

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 explains query shapes ('title artist' plays one song; artist name alone plays a batch), which implies how the tool is meant to be driven. However, it gives no explicit when-to-use guidance against siblings like search_music, list_favorites, or list_playlists, leaving routing to inference.

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

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

Annotations already indicate this is a non-read-only, non-destructive action, and the description adds the group-level scope. It does not disclose edge behavior such as what happens at the start of a queue or whether all rooms in the group are affected, so additional transparency is limited.

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 a single, direct sentence with no filler: action, target, and scope are all present. Every word contributes to understanding the tool.

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 one-optional-parameter playback command with no output schema, the description gives the core action and scope, and the schema covers the parameter. It is only mildly incomplete regarding boundary behavior and explicit default-room effects, which are minor for this tool.

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%, and the input schema already explains the room parameter, including aliases and default behavior. The tool description adds no parameter-specific meaning beyond what the schema provides, so it meets but does not exceed the 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 uses a specific action verb ('Skip') with a clear target ('previous track') and scope ('in a room's group'), making the tool's function immediately recognizable. It also distinguishes itself naturally from the sibling next_track by specifying 'previous.'

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 intended use is implied by the action and target: call this when a user wants to go to the previous track. However, it names no alternatives or exclusions, such as next_track or seek, so the agent must infer routing rather than being told.

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

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

Annotations already cover read-only, open-world, and non-destructive status, but the description adds a distinct behavioral guarantee: no playback side effect. It also discloses the shape of returned candidates, which is useful because there is no output schema. It stops short of explaining service-specific behavior or rate limits.

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?

A single sentence front-loads the action and result, using parentheses efficiently to summarize return fields. No filler or redundancy.

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 three-parameter search tool with no output schema, the description adequately covers purpose and return fields, and the schema supplies enum and min/max constraints. However, it leaves parameter semantics unexplained, particularly the service selector and limit, so it is only minimally 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?

With 0% schema description coverage and three parameters, the description should compensate but does not. 'Searches for songs' weakly implies the required query string, but the limit and service parameters are never mentioned, and no formats or constraints are explained.

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?

States a specific verb ('Searches') and resource ('songs'), and explicitly scopes the behavior as 'without playing them,' which distinguishes it from playback siblings like play_music. It also names the candidate track fields returned, making the operation unambiguous.

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 phrase 'without playing them' implies this is a search-only tool and suggests it should be used when playback is not desired, but it does not explicitly name play_music as the alternative or state when not to use it. Usage is therefore inferable but not fully guided.

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

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

The description adds the important behavioral constraint that seeking only works during playback, which is not captured by annotations. It implies a state change (position change) consistent with readOnlyHint=false. No contradictions with annotations.

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 sentences with zero waste. The core action and units are front-loaded, and the constraint is stated second. Efficient and easy to parse.

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 is simple, but the room optionality conflict between schema (required) and schema description (omit) is not resolved. The description could have clarified the default-room behavior or that room is optional, but it doesn't. The playing condition is covered, so the main gap is this ambiguity.

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 description clarifies position_seconds with 'seconds from the start' and an example, adding value beyond the schema's bare type/minimum. However, it does not address the room parameter, and the schema itself is inconsistent (room marked required yet its description says 'Omit for the default room'), leaving ambiguity unresolved.

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 action ('Jump to a position in the current track'), the resource, and the unit with a concrete example. It distinguishes from siblings like next_track/previous_track because it's about precise positioning within a track, not skipping tracks.

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?

It provides a clear condition ('Only works while something is playing') but does not explicitly state when to use this tool versus alternatives, nor when not to use it. No mention of next/previous as the preferred way to skip tracks.

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

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

The description adds meaningful behavioral details beyond the annotations: partial updates ('Only the settings that are passed are changed') and the home-soundbar fallback. These are consistent with readOnlyHint=false and destructiveHint=false, since the tool modifies settings but is not destructive.

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?

Three concise sentences with no filler. The first sentence states what the tool does, the second covers scope and fallback, and the third explains the partial-update behavior. Every sentence adds value.

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 effect, target hardware, fallback, and partial-update behavior, which is adequate for a simple settings tool. The main gap is the unresolved room optionality conflict between the schema's required list and its 'Omit for the default room' note, which could confuse an agent deciding whether to pass room.

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 description gives plain-language meaning for night_mode and speech_enhancement, both of which lack schema descriptions, and clarifies that only provided settings are changed. However, the schema marks room as required while its own property description says 'Omit for the default room,' creating a minor unresolved inconsistency.

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 opens with a clear verb and resource: 'Changes soundbar settings' and then names the exact settings (night mode, speech enhancement) with brief explanations. This distinguishes it from sibling tools like set_volume or set_mute, which target different audio parameters.

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 states it applies to Sonos soundbars, defines fallback behavior when the named room has no soundbar, and clarifies that only passed settings are changed. It does not explicitly contrast with sibling tools or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false) and non-destructive. The description adds a useful nuance ('Muting keeps playback running') that clarifies the effect beyond the schema. It does not disclose other potential behaviors like error handling or effects on grouped rooms, but given annotations cover the safety profile, this is sufficient.

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 short sentences with zero filler. The primary action is front-loaded, and the behavioral detail is the only extra, earning 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?

For a simple tool with two parameters and no output schema, the description plus schema covers the essential information: what it does, how it behaves, and the room parameter is described. The 'muted' parameter is implied, and the default-room nuance is in the schema. It is complete enough for an agent to invoke correctly without additional context.

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 50%: the 'room' parameter is described, but 'muted' has no schema description. The tool description does not compensate by explaining the boolean semantics, though the action phrase 'Mutes or unmutes' implicitly maps true/false. With only partial coverage and no additional parameter context, the description leaves the 'muted' parameter underspecified.

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 states a specific verb (mute/unmute), the resource (a single room), and adds a key behavioral detail (muting keeps playback running). This clearly distinguishes it from siblings like adjust_volume or toggle_play_pause.

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 purpose is clear enough to imply when to use it, but the description offers no explicit guidance on when not to use it or comparisons to alternatives. For instance, it doesn't mention that volume control is separate, though the 'keeps playback running' note hints at a distinction.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds value beyond that by explicitly stating the partial-update behavior and defining what each repeat enum value does, so an agent knows it won't unintentionally reset other playback settings.

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 sentences with no filler. The action is front-loaded, the repeat enum is compactly defined, and the partial-update caveat is placed at the end where it reinforces behavior without distracting from the main purpose.

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 three-parameter setter with no output schema, the description plus schema covers everything needed to call it correctly: target room, allowed repeat values, shuffle boolean semantics, and the fact that only passed settings are changed. No return-value documentation is necessary for this operation.

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 coverage is only 33%, but the description compensates by explaining the repeat enum values in detail and confirming that shuffle/repeat are toggles via 'on or off.' The room parameter is already documented in the schema. Shuffle could use a bit more explicit spelling, but the meaning is clear enough from context.

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 states a specific verb and resource: 'Turns shuffle and/or repeat on or off for a room's group.' It also disambiguates the repeat modes ('repeat the queue' vs 'repeat the current track'), making the tool's function unmistakable and distinct from the listed music-control siblings.

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 makes clear when this tool is appropriate: to change shuffle and/or repeat for a group. It also adds the key usage nuance that 'only the settings that are passed are changed.' No explicit alternative is named, but none of the sibling tools overlaps with this functionality, so no exclusion is required.

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

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

Annotations already mark it as a mutating but non-destructive operation. The description adds behavior beyond that: the reminder fires once, the speaker reads the text aloud, and scheduling is ZoneFoundry-specific. No hidden destructive effects are indicated, and the description does not contradict the annotations.

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?

Three short sentences plus two concrete JSON examples carry the whole message without repeating the title or schema. The most important purpose statement comes first, and the final distinguishing note is short.

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 5-parameter scheduling tool with no output schema, the description is near-sufficient: purpose, time formats, examples, and differentiation are covered. It does not mention return/confirmation behavior or explicitly require one of `at`/`in_minutes`, but the schema and examples make successful invocation likely.

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 coverage is high (80%), so the baseline is 3; the description's examples and the `at` vs `in_minutes` relationship add modest clarity. It does not improve on the schema's explanations for `text`, `room`, or `language`, and it leaves the 'at least one time parameter' requirement slightly ambiguous.

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 definition states a specific action ('Schedules a one-time spoken reminder') with a clear resource (the room's Sonos speaker reading text aloud). It also disambiguates from native Sonos alarms by noting this is ZoneFoundry's own scheduler, so it stands apart from generic reminder tools.

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 context for use is clear: future one-time spoken reminders, with either an absolute time or a relative delay. It separates itself from native Sonos alarms but does not explicitly point to sibling tools like cancel_reminder/list_reminders or announce for alternative cases, so it stops short of full when/when-not guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write nature is already known. The description adds the clamping behavior ('values above 70 are clamped for safety'), which is useful and not present in annotations. However, it does not disclose other behavioral traits like error handling or whether the room must exist, so it only partially exceeds the structured info.

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 a single efficient sentence with the core action and range front-loaded. The clamping note is concise and valuable. It loses a point because it omits the alternative tool mention and contains an inconsistency regarding room optionality, but it is otherwise tightly written.

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 two-parameter write tool with annotations, the description provides enough to set volume correctly (range and clamping). However, the contradiction between the schema requiring 'room' and the description saying 'Omit for the default room' creates confusion. It also fails to mention the sibling adjust_volume, leaving the agent to guess which to pick. This is adequate 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 50% (only room has a description). The tool description adds semantics for volume by stating the range and clamping, which compensates partially for the missing volume description. It adds nothing for room beyond the schema, which already explains aliases and the optionality that conflicts with the required flag. Overall, it adds modest value.

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 states a specific action ('Set a room's volume') with a resource (room) and the value range (0-70). It clearly distinguishes the operation from siblings like set_mute or toggle_play_pause, though it does not explicitly contrast with adjust_volume. The clamping detail adds precision.

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 gives no guidance on when to use this tool versus alternatives. There is no mention of adjust_volume or any conditions that would favor one over the other. An agent must infer that this is for absolute volume setting, but the lack of explicit exclusions or prerequisites leaves a gap.

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

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

Beyond annotations (readOnly=false, openWorld=true, destructive=false), the description adds useful behavior: cloud routing, no need for the app to be open, automatic device selection for TV and line-in, and a fallback path for TV. This is meaningful added transparency for a state-changing action.

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?

Three sentences, front-loaded with the core function, with cloud behavior and fallback in supporting sentences. Each sentence adds operational information, though the middle sentence packs multiple details.

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 two-parameter action with no output schema, the description covers what the tool does, what source choices mean, cloud dependency, and a fallback. It doesn't describe return values or failure behavior for music/line-in, but these are minor for invocation.

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 only documents room; source has an enum but no description. The description compensates by explaining the source values ('TV audio (soundbar HDMI/optical)', 'line-in') and their device-selection behavior. It does not explicitly map them to parameter names, but the meaning is clear.

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?

Description says 'Switch a room between music, TV audio (soundbar HDMI/optical) and line-in,' naming the exact action and the three source values. This makes it easy to distinguish from volume, playback, and reminder siblings.

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?

Provides clear context: switching goes through Sonos cloud so the user needn't be home or have the app open, and TV has an explicit fallback to the ZoneFoundry app on home Wi-Fi. It doesn't explicitly say when not to use it or name an alternative, but the context is sufficient.

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

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

Annotations cover the safety profile (read-only, non-destructive, open-world), and the description adds meaningful behavior beyond them: the profile is regenerated daily, can be empty for new users, and statistics are computed live in contrast to the static profile. Missing any note on latency or auth, but the freshness semantics are genuinely useful.

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?

Three tight sentences that front-load the return content, then freshness, then the empty-state caveat. No filler. The middle clause 'Same coverage as the play history' is the only vaguely worded part.

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?

No output schema exists, so the description carries the burden of describing returns, and it does so by enumerating the profile fields and statistic categories. Combined with the daily-regeneration caveat, an agent has enough to call and interpret it, though the exact return shape and the empty-profile representation are unspecified.

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?

Only one optional parameter and schema coverage is 100%, with the schema itself documenting the default (90) and max (365). The description says nothing about the days window, so it adds no meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource: it returns the home's learned listening profile (artists, genres, rooms, times, language) plus request statistics. The clause 'Same coverage as the play history' helps relate it to a sibling, but it is oblique rather than a crisp differentiation. An agent can tell roughly what it gets, though the relationship to play_history is fuzzy.

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 never says when to call this versus alternatives, nor any exclusion condition. The note that the profile 'may be empty for a new user' is a caveat, not usage guidance. The agent must infer that this complements play_history from a single ambiguous clause.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description only needs to add context. It adds the state-dependent 'toggle' semantics and the group scope, but does not describe side effects or result. No contradiction with annotations.

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?

One short sentence with no filler. The verb and scope are front-loaded, and every word contributes meaningful 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?

For a simple one-parameter toggle with no output schema, the description plus schema fully covers the target, effect, and default behavior. Nothing an agent needs to invoke it correctly is missing.

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 single room parameter is fully documented in the schema (English names, Chinese aliases, omit for default). The description adds no parameter-level meaning beyond what the schema already provides, so the 100% schema coverage carries this dimension.

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?

States a specific verb 'toggle' and resource 'play/pause' scoped to 'a room's group.' This clearly distinguishes it from sibling transport controls such as next_track, previous_track, play_music, and adjust_volume without needing to name an alternative.

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 gives the operational context (toggle playback for a room's group) and the schema clarifies room selection, but it does not explicitly say when to choose this tool over alternatives like play_music or seek, nor does it state any exclusions.

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

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

Beyond the annotations, the description discloses key behavioral nuances: the 10-minute time limit, that each change can be undone only once, that repeated calls step backward through older changes, and that only volume/grouping states are touched while other settings remain unaffected. This is substantial added context and does not contradict any annotation.

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?

Three tight sentences, each earning its place: the first states the core action and scope, the second explains repeated-call behavior, and the third clarifies exclusions. The most decision-relevant information is front-loaded in the opening sentence.

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 zero-parameter, no-output-schema tool, the description supplies all necessary operational context: what counts as an undoable change, the time window, repeat behavior, and what is unaffected. Combined with the annotations, an agent has enough to invoke and reason about the tool correctly.

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 input schema is empty, so the 0-parameter baseline applies. The description adds meaning by reinforcing that no selection is needed: the tool automatically targets the most recent relevant change in the home. There are no parameter details to document, so this dimension is well-served.

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 uses a specific verb ('Reverts') and names the exact resource ('most recent volume or grouping change'), with the scope ('in this home within the last 10 minutes') and what is restored ('every room's prior volume and group layout'). This clearly distinguishes it from sibling tools like set_volume or group_rooms, which create or apply changes rather than undo them.

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 a volume or grouping change, and within a 10-minute window. It also clarifies what it does NOT affect (playback, favorites, alarms), which gives the agent useful exclusionary context. It stops short of explicitly naming alternatives or saying 'use this when...', so it misses the top bar for explicit routing.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context: the operation removes the room from whatever group it belongs to and restores independent playback. It does not mention no-op behavior for already-ungrouped rooms, but this is minor for such a simple action.

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 a single front-loaded sentence with no filler. Every word contributes to explaining the action and outcome.

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 one-parameter tool with annotations covering the safety profile, most essentials are present. However, the contradiction between required room and 'Omit for the default room' leaves real ambiguity about whether a call without room is valid, so the definition is not fully reliable.

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 room parameter's schema description is rich, covering name format and common aliases, but it also says 'Omit for the default room' while the schema marks room as required. This is a direct contradiction that makes parameter usage ambiguous, especially since the tool description itself adds no parameter-level guidance.

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 states a specific action and resource: 'Take a room out of whatever group it is in' and clarifies the intended outcome. It clearly differentiates from the sibling tool group_rooms.

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 makes the use case obvious: use it when a grouped room should play standalone again. It does not explicitly name group_rooms as the inverse alternative or state exclusions, but the context is sufficient.

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