Scaffold a show

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

The description discloses exactly what gets created (new container, master and tempo nodes), what is intentionally omitted (scenes/look), and what is returned (container path plus node paths). It goes beyond the basic readOnlyHint=false and destructiveHint=false annotations by describing the structural side effects and the blank-canvas nature, while avoiding any 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 description is three sentences with clear front-loading: what the tool does, how it differs from a sibling, and what it returns plus next steps. Every sentence adds value without redundancy or fluff.

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?

Despite the absence of an output schema, the description explicitly names the return values (container path, 'master' and 'tempo' node paths) and the absence of scenes/look. It covers all essential context for a simple creation tool with 2 parameters, and the workflow guidance completes the picture.

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?

The input schema already provides 100% coverage with clear descriptions for both parameters ('Name of the show container to create' and 'Parent COMP path the show container is created inside'). The description adds no additional parameter-level detail beyond what the schema states, so the baseline of 3 applies.

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 uses a specific verb ('Create a starting skeleton for a live show') and clearly enumerates what is included ('master' output Null, 'tempo' beat clock) and excluded ('NO scenes or look'). It explicitly names scaffold_genre as a distinct sibling tool, making the tool's purpose unambiguous.

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?

The description gives an explicit alternative with a condition: 'Use scaffold_genre instead when you want a genre-flavored start.' It also implies the use case for scaffold_show (blank-canvas start) and outlines a recommended workflow ('then add scenes, audio features, a layer mixer into master, cues and a control surface').

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