set_tempo

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

Discloses behavior well beyond the annotations: the tool writes and reads back the stored value, the set does not survive every scene launch, the exact mechanism (scene.tempo_enabled rewriting song.tempo), and that BPM is a real unit unlike normalized device parameters. The idempotentHint annotation is consistent—setting an absolute tempo is idempotent—and the description adds genuine lifecycle context. No contradiction.

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 main purpose is front-loaded in the first line, with Returns and Note sections structuring the caveats. The parameter-normalization tangent runs a bit long and includes extra set_mix detail, but every sentence carries information useful for correct invocation.

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 single-parameter tool with an output schema and annotations present, the description covers everything needed: global scope, return shape, the scene-launch override caveat, and cross-references to sibling tools. No material gap remains for an agent to call it correctly.

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 bpm schema description already gives the unit and validation range, so baseline is 3. The description adds value by flagging that BPM is 'a real unit, which makes this tool the exception among the setters,' warning the agent not to send a normalized 0..1 value. This goes beyond what the schema states.

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+resource: 'Set the global song tempo in BPM and read back the stored value.' The description immediately distinguishes scope ('One tempo governs the whole set, Session and Arrangement alike. There is no per-track tempo'), which prevents confusion with per-track setters like set_parameter or set_mix.

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?

Provides real routing context: names the scene as the 'one other place a tempo can come from' and advises reading song.tempo back after a launch, and points to set_parameter for normalized device parameters plus describe for min/max. Lacks an explicit 'use this over X when...' framing, but the alternatives and conditions are clearly named.

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