Play a sound

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the 15-second duration cap and the platform-dependent codec support (WAV everywhere; MP3/M4A/AIFF on macOS or with ffmpeg), which an agent cannot infer from structured fields. It does not say whether playback blocks, whether the call errors on multiple sources, or how stock names are discovered or validated.

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?

Dense and front-loaded: the selection rule comes first, then file formats, then the melody grammar, with the duration cap last as a constraint. Every clause carries information; no filler or restatement of the tool name.

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 must cover inputs and constraints, and it does: source exclusivity, codec matrix, melody grammar, and a size limit. For a four-parameter, all-optional playback tool this is close to everything an agent needs to construct a valid call.

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%: file and wave are documented, stock and melody are not. The description compensates strongly for melody by specifying the token grammar, NOTE:ms syntax, R rests, and + chord notation with a worked example. It leaves stock under-specified — "a stock sound (bar_stock)" hints at provenance but gives no naming convention or discovery route.

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?

Opens with a specific verb and resource ("Play") and immediately enumerates the three mutually exclusive input modalities: stock sound, audio file, and written melody. The reference to bar_stock ties it to the sibling that supplies stock names, so an agent can distinguish this from bar_text/bar_image/bar_pixels without opening the 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 phrase "Play exactly one of" is an explicit selection rule that resolves the otherwise confusing four-optional-parameter schema. What is missing is guidance on what happens if more than one is supplied, and no explicit statement of when to prefer a melody over a file.

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