Scaffold a MIDI-mappable VJ deck

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

The description discloses the full set of components created (A/B deck mixer, control surface, midiinCHOP surface) and how bindings are wired, along with default behavior for omitted sources and midi_map. Annotations already indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true; the description aligns and adds useful context about the composed side effects without contradicting the annotations.

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 no wasted words. The first sentence front-loads the main purpose and component breakdown; the second efficiently covers the key parameters and defaults; the third clarifies the tool's relationship to the primitive. Every sentence earns its place and the structure is easy to scan.

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 an 8-parameter tool with no output schema and no required parameters, the description covers the essential context: what is created, how parameters affect the result, default behaviors, and the relationship to sibling primitives. It does not describe return values, but given the absence of an output schema, that is not necessary. Minor gaps include a lack of explicit mention of side effects on the parent container or existing nodes, though the openWorldHint annotation covers this partially.

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 100%, so the baseline is 3. The description adds a small amount of contextual meaning by explaining that deck_a/deck_b are source TOP paths and that omitting them creates test sources, and it summarizes the midi_map default behavior. However, most parameter semantics (defaults, ranges, descriptions) are already fully covered by the input schema, and the description does not significantly extend beyond that.

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 opens with a specific verb and resource: 'Compose a complete, playable VJ deck UI in one call.' It further distinguishes itself from siblings by explicitly naming the primitives it wraps (create_decks, create_control_surface, create_external_io) and positioning itself as the 'deck-scaffold layer on top of the create_decks primitive,' making its unique role 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 explains the intended use case ('Compose a complete, playable VJ deck UI in one call') and contrasts with the primitive by stating it 'wires the existing deck, surface, and I/O tools into one UI container.' It also provides parameter usage guidance (pass source TOP paths or omit for test sources, optional midi_map). However, it does not explicitly state when NOT to use this tool in favor of an alternative, such as 'if you only need a deck, use create_decks.'

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