build_song_structure

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

Annotations only declare the write-but-not-destructive profile; the description goes further by explaining exactly what is created (one clip block per scene row, plus a named locator per section), how 'bars' drives repetition versus the fallback of the longest clip, and that tracks with no clip in the row stay silent. It does not say whether pre-existing arrangement content at the target range is overwritten, which is the main remaining behavioral unknown.

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 core action is front-loaded in the first sentence and the payload shape follows immediately, with an inline example instead of prose. The second half becomes a long run-on covering copy semantics, bar-filling and silent tracks, so it is dense but not padded.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, an agent cannot tell from the description what start_beat does (offset origin?) or what name_scenes toggles, and overwrite behavior on the target timeline is unstated.

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 0%, so the description carries the full burden, and for the one required parameter it does: the sections array format is spelled out with a concrete literal example, and the meaning of 'name', 'scene' and 'bars' plus the default behavior when 'bars' is omitted is stated explicitly. The remaining two parameters, start_beat and name_scenes, get no explanation in the description, which is the only gap.

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: 'Lay a song out in the Arrangement from Session scenes, with a named locator per section.' That is far more than a restatement of the name and clearly separates it from a one-off duplicate_to_arrangement. It stops short of naming that sibling outright, so an agent must still infer the boundary.

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 by the mechanics ('from Session scenes', 'copies every clip in that scene row to the timeline'), which tells an agent this is a bulk layout operation rather than a single-clip move. There is no explicit when-to-use or when-not-to-use statement, and no routing to duplicate_to_arrangement or create_locator for partial cases.

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