Control playlist playback

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

Annotations already mark this as non-read-only live playback control, but the description adds valuable behavior beyond them: it explicitly calls out error conditions (empty playlist or disabled mode), the one-time browser click requirement for audio, and the required permission. This goes well beyond what annotations 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?

Three tightly packed sentences cover action, lookup semantics, error behavior, browser restrictions, and permissions without a single wasted word. The most important usage facts are front-loaded before the edge-case 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 three-parameter tool with no output schema, this description is unusually complete: it explains the synchronous playback effect, identifier resolution, failure cases, browser autoplay limitation, and authorization requirement. An agent has enough context to call it correctly without additional investigation.

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?

Even though the schema has full descriptions for all three parameters, the tool description enriches them significantly: it explains exact name matching with case insensitivity when unique, forbids partial-name matches, and clarifies that 'sound' is required for track-specific commands. This materially improves parameter understanding.

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 specific verb and resource scope: 'Play or stop a playlist or one of its tracks, or switch its mode'. It also clarifies the mechanism ('through Foundry's own playback') and clearly distinguishes this from management or scene-music siblings by focusing on live, synced playback control.

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 clear context for when to use the tool: whenever you want Foundry's playback controls to affect all connected browsers. It does not explicitly name alternatives or exclusion cases, but the synced-playback framing and command semantics make the intended usage clear without being misleading.

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