set_song_options

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

No annotations are provided, so the description carries the full burden. It is silent on whether omitted parameters are left unchanged, whether changes persist, whether this interrupts playback, or what permissions are needed — all critical for a 7-parameter mutation tool. Only the song_time/start_time playback-state nuance is 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?

Two short sentences: the first front-loads the affected settings, the second carries the highest-value caveat. Nearly zero waste, though the fragment style of the opening sentence sacrifices some grammatical clarity for brevity.

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 7-parameter mutation tool with no annotations, no output schema and 0% schema coverage, the description covers parameter meanings but omits the update semantics (partial vs. full replacement), side effects on playback, and error behavior. Adequate but with clear gaps given the tool's complexity.

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 compensate, and it largely does: it maps metronome, loop, loop_start, loop_length, song_time, start_time and record_mode to their meanings, adds the unit (beats) for loop start/length, and gives a precise semantic distinction between song_time and start_time. It falls short of full compensation but adds substantial meaning beyond the bare schema titles.

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 enumerates the configurable state (metronome, arrangement loop, playhead, record mode) but never names the verb or resource explicitly — no 'sets song-level options' or equivalent. An agent can infer it is a setter for song playback settings, but the purpose is implied rather than stated, and no sibling (e.g. transport, set_tempo) is differentiated.

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 one genuinely useful conditional rule: song_time moves the playhead only while playing, while stopped use start_time. That is real when-to-use guidance, but it covers only the playhead params and never contrasts this tool with alternatives like transport or set_tempo, nor says when the tool should not be called.

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