create_scene

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

Annotations only say it is a non-destructive write; the description adds the important side effect that inserting shifts later scenes down by one, and that copy_of duplicates all clips in the source scene and places the copy directly below. The 16-scene ceiling is a real environmental limit worth surfacing. It still doesn't say what happens on invalid input (e.g. both params supplied) or what the call returns.

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 definition, then the parameter rules, then the environment caveat. Every sentence carries information, though the copy_of sentence packs three clauses separated by a semicolon, which makes the placement rule slightly harder to scan than it needs to be.

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 three-optional-parameter mutation with no output schema, the description covers what is created, where it lands, ordering side effects, and the environment's scene limit. The remaining gap is the return value (e.g. the new scene's index), which an agent would need to address the created scene afterward.

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 carry the parameters, and it largely does: index semantics (-1 or none appends), copy_of semantics (source scene copied with all clips, inserted directly below), and the mutual exclusion between the two. The name parameter is only obliquely covered via 'name and reuse empty scenes' rather than stating that it sets the new scene's label.

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 concrete verb plus resource ('Add a scene') and immediately defines what a scene is ('a row of clip slots across all tracks'), which disambiguates it from the clip-creation siblings like create_midi_clip. It does not explicitly contrast itself with any named sibling, but the resource is specific enough that confusion is unlikely.

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?

Gives clear decision rules: omit index (or use -1) to append, use copy_of to duplicate a scene, and never pass both. It also adds a practical constraint driven by the environment (Live Lite caps at 16 scenes, so reuse empty scenes). No alternatives to this tool are named, so it stops short of a full when/when-not map.

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