Reaper Daemon

Overview Schema Source Related Servers Discussions Admin

insert_midi_events

Create a new MIDI item on one track from a list of raw events (notes, CC, pitch bend, program change), with no humanizing.

Instructions

Create a new MIDI item on one track from a list of raw events (notes, CC, pitch bend, program change), with no humanizing. Use this for exact, hand-specified MIDI; use insert_midi_file when a .mid already exists, insert_groove for humanized drums, insert_riff for humanized guitar or bass, cut_band for a whole four-track jam. Two timing units. Default time_unit "seconds": start_seconds + length_seconds, event time and duration in seconds from the item start. time_unit "beats" (use this to write music): start_bar (1-based) or start_beats (project quarter notes), length_beats, and event time and duration in quarter notes from the item start, so notes follow the tempo map. Mixing units is refused. For drums, keep the golden rule yourself: no drum hits the same velocity twice in a row. Returns {track_guid, notes, controls, time_unit, start_seconds, length_seconds} plus start_bar/start_beats/length_beats in beats mode. Errors: BAD_PAYLOAD (an event or the timing is out of range; nothing is written), INSERT_FAILED / VERIFY_FAILED (the new item is deleted again). Undoable.

Input Schema

Name	Required	Description
`track`	No	Exact track name (case-insensitive); "master" targets the master track. Used when no GUID is given; errors if two tracks share the name.
`events`	Yes	1..10000 events. Each needs type and time; the other fields depend on type.
`dry_run`	No	Preview: return what would run without changing the project.
`start_bar`	No	beats mode: 1-based bar the item starts on (or use start_beats).
`time_unit`	No	Default seconds. beats = quarter notes, tempo-map aware.
`start_beats`	No	beats mode: project quarter-note position the item starts on.
`length_beats`	No	beats mode: item length in quarter notes (4 = one 4/4 bar).
`start_seconds`	No	seconds mode: project time where the new item starts.
`length_seconds`	No	seconds mode: item length; every event must fit inside it.
`track_contains`	No	Case-insensitive substring; used only when no GUID or exact name is given. Errors if it matches more than one track.
`target_track_guid`	No	Stable REAPER track GUID; preferred when available. Wins over every other track selector.
`use_selected_track`	No	Target the first selected track; ignored when any other track selector is given. Errors if nothing is selected.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv3.23.1Oct 21, 2026

changedInput schema / properties / events / items / properties / duration / description

Previous value: -"note only: seconds; must end inside the item."New value: +"note only: in the payload's time_unit; must end inside the item."

changedInput schema / properties / events / items / properties / time / description

Previous value: -"Seconds from item start."New value: +"From item start, in the payload's time_unit."

addedInput schema / properties / length_beats

Added value: +{
+  "description": "beats mode: item length in quarter notes (4 = one 4/4 bar).",
+  "exclusiveMinimum": 0,
+  "type": "number"
+}

changedInput schema / properties / length_seconds / description

Previous value: -"Item length in seconds; every event must fit inside it."New value: +"seconds mode: item length; every event must fit inside it."

addedInput schema / properties / start_bar

Added value: +{
+  "description": "beats mode: 1-based bar the item starts on (or use start_beats).",
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / start_beats

Added value: +{
+  "description": "beats mode: project quarter-note position the item starts on.",
+  "minimum": 0,
+  "type": "number"
+}

changedInput schema / properties / start_seconds / description

Previous value: -"Project time in seconds where the new item starts."New value: +"seconds mode: project time where the new item starts."

addedInput schema / properties / time_unit

Added value: +{
+  "description": "Default seconds. beats = quarter notes, tempo-map aware.",
+  "enum": [
+    "seconds",
+    "beats"
+  ],
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "start_seconds",
-  "length_seconds",
-  "events"
-]New value: +[
+  "events"
+]

Changed18 schema fields changedv3.21.0Sep 19, 2026

addedInput schema / properties / events / description

Added value: +"1..10000 events. Each needs type and time; the other fields depend on type."

addedInput schema / properties / events / items / properties

Added value: +{
+  "channel": {
+    "description": "0-based MIDI channel, default 0.",
+    "maximum": 15,
+    "minimum": 0,
+    "type": "integer"
+  },
+  "controller": {
+    "description": "cc only: controller number.",
+    "maximum": 127,
+    "minimum": 0,
+    "type": "integer"
+  },
+  "duration": {
+    "description": "note only: seconds; must end inside the item.",
+    "type": "number"
+  },
+  "pitch": {
+    "description": "note only: MIDI note number (60 = middle C).",
+    "maximum": 127,
+    "minimum": 0,
+    "type": "integer"
+  },
+  "time": {
+    "description": "Seconds from item start.",
+    "minimum": 0,
+    "type": "number"
+  },
+  "type": {
+    "enum": [
+      "note",
+      "cc",
+      "pitch_bend",
+      "program_change"
+    ],
+    "type": "string"
+  },
+  "value": {
+    "description": "cc and program_change: 0..127. pitch_bend: 0..16383, 8192 = centre.",
+    "maximum": 16383,
+    "minimum": 0,
+    "type": "integer"
+  },
+  "velocity": {
+    "description": "note only.",
+    "maximum": 127,
+    "minimum": 1,
+    "type": "integer"
+  }
+}

addedInput schema / properties / events / items / required
```
Added value: +[
+  "type",
+  "time"
+]
```
addedInput schema / properties / events / maxItems
```
Added value: +10000
```
addedInput schema / properties / events / minItems
```
Added value: +1
```

removedInput schema / properties / fx_guid

Removed value: -{
-  "type": "string"
-}

removedInput schema / properties / fx_index

Removed value: -{
-  "type": "integer"
-}

removedInput schema / properties / fx_name_contains
```
Removed value: -{
-  "type": "string"
-}
```

removedInput schema / properties / fx_scope

Removed value: -{
-  "type": "string"
-}

addedInput schema / properties / length_seconds / description

Added value: +"Item length in seconds; every event must fit inside it."

addedInput schema / properties / length_seconds / maximum
```
Added value: +86400
```
addedInput schema / properties / length_seconds / minimum
```
Added value: +0.001
```

addedInput schema / properties / start_seconds / description

Added value: +"Project time in seconds where the new item starts."

addedInput schema / properties / start_seconds / minimum
```
Added value: +0
```

changedInput schema / properties / target_track_guid / description

Previous value: -"Stable REAPER track GUID; preferred when available."New value: +"Stable REAPER track GUID; preferred when available. Wins over every other track selector."

changedInput schema / properties / track / description

Previous value: -"Exact track name (case-insensitive)."New value: +"Exact track name (case-insensitive); \"master\" targets the master track. Used when no GUID is given; errors if two tracks share the name."

changedInput schema / properties / track_contains / description

Previous value: -"Case-insensitive substring; errors if it matches more than one track."New value: +"Case-insensitive substring; used only when no GUID or exact name is given. Errors if it matches more than one track."

changedInput schema / properties / use_selected_track / description

Previous value: -"Target the currently selected track instead of naming one."New value: +"Target the first selected track; ignored when any other track selector is given. Errors if nothing is selected."

First observedv0.1.0Sep 13, 2026

TDQS

A4.5/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden and largely meets it: it discloses the no-humanizing behavior, that mixed time units are refused, the exact return shape, the error codes and their side effects (BAD_PAYLOAD writes nothing; INSERT_FAILED/VERIFY_FAILED rolls the item back), and that the operation is undoable. The main remaining gap is track-selection fallback behavior when multiple selectors are omitted.

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?

Front-loaded with purpose, then alternatives, then the two timing modes, then returns and errors — a logical reading order with no filler sentences. The parenthetical sibling enumeration and the inline drum-velocity 'golden rule' add length, though both carry real information.

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 12-parameter mutation tool with no annotations and no output schema, the description covers return values, failure modes, undoability, and the key timing-mode logic, which is most of what an agent needs. It stops short of describing the default track-targeting behavior when no selector is supplied, which for a tool with four optional selectors is a meaningful omission.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining cross-parameter semantics the schema can't express — the two mutually exclusive timing modes (seconds vs. beats), the tempo-map awareness of beats, and the refusal to mix units. It also flags the 1-based bar convention and the per-event duration containment rule.

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

Purpose5/5

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

States a specific verb and resource ('Create a new MIDI item on one track from a list of raw events') plus the differentiator ('with no humanizing') and the event types accepted. It explicitly distinguishes itself from four named siblings, so an agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use ('exact, hand-specified MIDI') and when-to-use-an-alternative for each sibling: insert_midi_file for existing .mid files, insert_groove for humanized drums, insert_riff for guitar/bass, cut_band for a full band. It also advises which time_unit to pick ('beats (use this to write music)'), leaving nothing to inference.

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

insert_midi_events

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools