create_arrangement_midi_clip

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that it uses the Arrangement API, requires Live 11+, and that note start_time is clip-relative. However, it omits potential side effects, such as whether an existing clip at the given position is overwritten, and does not describe what happens upon success or failure. This is average but not exceptional.

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 well-structured, starting with a clear one-sentence purpose, then a brief note about API distinctions, and a parameter list. It stays efficient without unnecessary fluff. The parameter list is necessary given the lack of schema descriptions, so the added length is justified.

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 creation tool with optional nested notes, no output schema, and no annotations, the description covers the essential aspects: purpose, location, version requirement, all parameters with units, and note shape. Minor omissions include behavior on existing clips and return value, but the provided information is largely sufficient for an agent to use the tool correctly.

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 coverage is 0%, so the description must explain all parameters, and it does. It lists each parameter and adds meaning: track_index is the MIDI track index, start_time is in beats, length is in beats, and notes are optional with a description of the note dict format including probability and relative start_time. This fully compensates for the bare schema and adds crucial context.

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 purpose: 'Create a MIDI clip in the Arrangement view, optionally filled with notes.' It uses a specific verb (create), identifies the resource (MIDI clip), and specifies the scope (Arrangement view). It also distinguishes itself from session clip tools by noting 'This is the Arrangement path (Live 11+).'

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 provides context for when to use this tool: 'Session clips and Arrangement clips use different Live APIs. This is the Arrangement path.' This implies it should be used for arrangement clips rather than session clips. It also references the note format from 'add_notes_with_probability', helping the agent understand the options. However, it does not explicitly state when not to use it or name alternative tools, leaving a minor gap.

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