Reaper Daemon

Overview Schema Source Related Servers Discussions Admin

insert_midi_events

Insert a new MIDI item from raw events (notes, CC, pitch bend, program change) with exact timing and no humanizing. Specify events in seconds from item start.

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. Event times are seconds from the item start. For drums, keep the golden rule yourself: no drum hits the same velocity twice in a row. Returns {track_guid, notes, controls, start_seconds, length_seconds}. Errors: BAD_PAYLOAD (an event is out of range; nothing is written), INSERT_FAILED / VERIFY_FAILED (the new item is deleted again). Undoable.

Input Schema

TableJSON 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_seconds`	Yes	Project time in seconds where the new item starts.
`length_seconds`	Yes	Item length in seconds; 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.

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.7/5.0

Behavior5/5

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

With no annotations present, the description carries the full burden and succeeds: it states there is no humanizing, explains event timing, gives the drum velocity rule, lists the return shape, details error conditions and their side effects (nothing written on BAD_PAYLOAD, item deleted on INSERT_FAILED/VERIFY_FAILED), and notes the operation is undoable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Although dense, every sentence earns its place: purpose, sibling routing, timing clarification, domain rule, return shape, error behavior, and undoability. It is front-loaded with the core action and does not repeat the schema's parameter-by-parameter details.

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

Completeness5/5

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

For a complex tool with 8 parameters, no annotations, and no output schema, the description is remarkably complete. It covers the return value, error semantics, rollback behavior, and selection criteria, while the fully-covered schema handles parameter-level detail.

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 description coverage is 100%, so the schema already documents every parameter thoroughly. The description mostly restates event-time semantics already present in the schema and adds no new per-parameter meaning beyond that, meeting the baseline for full schema coverage.

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?

The description opens with a specific verb and resource: 'Create a new MIDI item on one track from a list of raw events.' It also explicitly names what this tool is not for by distinguishing itself from insert_midi_file, insert_groove, insert_riff, and cut_band, so an agent can clearly differentiate it from siblings.

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?

The description provides direct when-to-use guidance: 'Use this for exact, hand-specified MIDI' and then lists the exact alternative tool for each other scenario (.mid exists, humanized drums, humanized guitar/bass, four-track jam). This leaves no ambiguity about tool selection.

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