Create control surface

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

The description explains that the tool builds a panel and details the behavior of its components: faders drive parameters and cue buttons recall or morph to named cues with optional crossfade. It also mentions the panel should be opened in Perform/Panel mode. Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) are consistent with the description, and the description adds context beyond annotations about the container mode and cue firing behavior.

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 two sentences: the first succinctly states the tool's purpose and components, the second provides usage guidance and behavioral detail. It is front-loaded with the main action, no redundant information, and every phrase earns its place.

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?

The description covers the tool's behavior, usage mode, and prerequisites (manage_cue). With 5 parameters all having defaults and schema coverage, the description is nearly complete. It lacks explicit error handling or what happens if a cue doesn't exist, but for a creation tool, this is adequate.

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 schema has 100% description coverage, so the baseline is 3. The description adds meaning by explaining that comp_path is the COMP holding cues from manage_cue, and that cue_buttons can have morph_seconds for crossfade. It also clarifies that faders are vertical and drive parameters, and that cue buttons fire scenes. This additional context justifies a 4.

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 clearly states it builds a playable performance panel containing vertical faders and cue buttons for live use, distinguishing it from a parameter dialog. It specifies the tool's purpose with specific verbs and resources, and among many create_* siblings, this one is uniquely for control surfaces.

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 indicates when to use the tool ('for live use, beyond the parameter dialog') and how to use it ('Open the container in Perform/Panel mode'). It references manage_cue as a prerequisite for cue buttons, providing context. However, it does not explicitly state when not to use this tool or list alternatives, though the sibling set includes create_control_panel which might be related.

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