tempo_set_map

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

Annotations declare idempotent and non-destructive, and the description adds genuinely useful context the annotations cannot: musical positions of clips/automation/markers/loop are preserved, the operation is undoable, and step vs ramp are interpreted differently by context (section boundary vs inside a MIDI clip, block by block). It stops short of saying what happens to points beyond the 256 cap or how conflicting existing maps are merged/replaced, but coverage is strong.

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?

Four short sentences, front-loaded with the core action and model, then edge-case behavior. Dense but not padded. The dotted "transport.set_tempo" reference is the one element that could be tighter or dropped.

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 one-parameter, no-output-schema mutation tool, the description covers the data model, the empty case, side effects on musical positions, playback interpretation, and undoability. Only ordering/duplicate-beat rules and the 256-point limit are left entirely to the schema.

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% and the schema already documents beat, bpm, and the curve enum, so the baseline is 3. The description earns above that by explaining inter-point semantics ("each a step or a linear ramp to the next") and the empty-array case, which the schema's "Tempo points in time order" does not convey.

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?

"Replace the tempo map: points at song beats with a tempo, each a step or a linear ramp to the next" gives a specific verb (replace), resource (tempo map), and the data model (beat/bpm points with step vs linear interpolation). It is clearly distinguished from the sibling transport_set_tempo, which it names as the single-tempo fallback.

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?

Explicitly states the alternative for the degenerate case: "Empty points = one tempo (transport.set_tempo)", so an agent knows where to go for a plain tempo change. It does not spell out when NOT to use this tool (e.g., vs tempo_set_time_signatures or arrangement tools), and the sibling is referenced as "transport.set_tempo" rather than the sibling name transport_set_tempo, which is a minor routing friction.

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