create_sequence

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

With no annotations, the description carries the full burden, and it does disclose real behavior: audio analysis happens, a .xsq file is written, and omitting show_name/vocal_assignments triggers a multi-turn clarification response rather than a failure. However, it never says whether an existing sequence is overwritten, what permissions or show-folder preconditions apply, or that audio analysis is long-running — meaningful gaps for a file-writing operation.

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?

Front-loaded with the one-line purpose, then a behavioral sentence, then per-parameter detail — good ordering. The vocal_assignments entry is the longest but its length is justified by two distinct formats; overall there is little filler.

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 six-parameter generative tool with no annotations and no output schema, the description covers inputs, mode semantics, and the clarification-return behavior well. It is only slightly incomplete on the success return (path to the generated .xsq, effect summary) and on overwrite semantics.

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%, yet the description documents all six parameters: mode's three accepted values (which the schema does not enumerate), palette_hint and theme with example strings, show_name with example folder names, and vocal_assignments with two concrete mapping formats ('{"all": ...}' vs per-model). It fully compensates for the empty schema.

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?

States a specific verb and resource ('Create an xLights sequence') plus the source input (music file) and the concrete artifact produced (.xsq with effects on light models). This clearly separates it from siblings such as remap_sequence, preview_plan, analyze_song, and inspect_sequence.

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 mode parameter is explained in terms of intent — 'auto' (AI picks everything), 'guided' (interactive), 'template' (apply saved recipes) — which is genuine when-to-use guidance. It also explains the fallback flow when show_name or vocal_assignments are omitted. It stops short of naming alternatives like preview_plan for a dry run or analyze_song for analysis-only.

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