Skip to main content
Glama

write_clip

Destructive

Create a MIDI clip in a Session slot or edit an existing clip and write its notes. Replace or add notes in one undo step, with rejected notes and reasons returned.

Instructions

Create a MIDI clip in a Session slot, or change one (also a timeline clip, clip t0/a1), and write its notes.

An empty slot gets a new clip. mode=replace (default) leaves exactly the given notes in the clip; mode=add keeps the existing ones. All of it is one undo step. Notes that fail a check come back in "rejected" with the reason; the rest are written. Works on MIDI tracks only; read_set shows the tracks and scenes. Notes may carry probability, velocity_deviation and release_velocity.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "write_clip"
  }
}

Input Schema

NameRequiredDescriptionDefault
clipNoA clip by address instead of track and slot: t0/s2 (Session slot 2 of t0) or t0/a1 (the second timeline clip of t0, see arrangement list).
modeNoreplace: the clip ends up with exactly these notes (old ones removed). add: keep the old notes and add these.replace
nameNoOptional new clip name; empty keeps the current name.
slotNoClip slot: the scene row, from 0. Example: 0 for the first scene.
notesNoNotes to write. Example: [{"pitch": "C3", "start": 0, "length": 1, "velocity": 100}, {"pitch": "E3", "start": 1, "length": 1, "velocity": 90}]
trackNoTrack address of a Session clip, e.g. t0 (with slot).
length_beatsNoClip length in beats (16 = four 4/4 bars). 0 or empty: a new clip gets whole bars that fit the notes, an existing clip keeps its length.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.1

TDQS

A3.7/5.0
Behavior4/5

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

Beyond the destructive annotation, the description discloses that all changes are one undo step, that rejected notes are returned with reasons while the rest are written, and that the tool is MIDI-only. These are meaningful behavioral details not captured by 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then adds operational details in a logical order. It is slightly long but every sentence contributes useful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with no output schema, the description covers the key behaviors: creation vs update, note replacement vs addition, undo grouping, partial rejection handling, and MIDI-only scope. It could say more about the success response, but the critical operational details are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all seven parameters. The description reinforces mode semantics and clip addressing, but it adds little beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: create or change a MIDI clip and write its notes. It distinguishes Session slots from timeline clips and mentions read_set for tracks and scenes, but it does not explicitly differentiate from siblings like update_clip or edit_notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives useful context: empty slots create clips, mode=replace vs add controls note retention, and it works only on MIDI tracks. However, it does not explicitly say when to use this tool instead of update_clip, edit_notes, or create_audio_clip.

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