scaffold_track

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

With no annotations, the description carries the full burden and does so admirably. It discloses key behavioral traits: tracks are 'created plain/named/colored', chords/bass/drums are generated across the 'drop' section or the first one, and dry_run returns a plan without modifications. These details go beyond the basic operation and provide valuable insight into side effects and constraints.

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 lengthy but well-structured, with a front-loaded summary, a paragraph of exclusions, and a thorough parameter list. Every sentence provides necessary information without redundancy. While it is verbose, the complexity of the tool (9 parameters) justifies the length, and the format makes it 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?

Given the complexity, absence of annotations, and lack of an output schema, the description is quite complete. It covers all parameters, defaults, side effects, and limitations. It hints at the result structure ('see the `note` field in the result') but does not fully describe the return format, which is a minor gap for such a complex tool.

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 fully compensates. Every parameter is explained with meaning, examples, and defaults. For instance, genre 'drives tempo, default mode, and bass/drum style', progression is described as 'Scale degrees for the chord progression, e.g. [1, 6, 4, 5]', and structure format is explicitly defined. This is comprehensive and leaves little ambiguity.

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 the tool's function: 'Build a playable musical base from an empty (or clean) set in one call: key + tempo, section markers, and chords/bass/drums for the main section.' This specifies a distinct verb, resource, and scope, and differentiates from sibling tools by explicitly noting what it does not do (create groups, load instruments, set loop).

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 clear context for when to use the tool ('from an empty (or clean) set in one call') and what it does not cover ('Does NOT create groups, load instruments, or set a loop — those still need to be done by hand in Live'). It does not explicitly name alternative sibling tools, but the exclusion is clear enough to guide selection.

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