c64bridge 0.8.1 → 0.9.1

package/mcp/schemas/c64_sound.schema.json

@@ -1,644 +1,1159 @@
 {
   "type": "object",
-  "description": "Sound operations available via the c64_sound tool.",
-  "oneOf": [
+  "properties": {
+    "op": {
+      "type": "string",
+      "enum": [
+        "capture_samples",
+        "set_volume",
+        "reset",
+        "note_on",
+        "note_off",
+        "silence_all",
+        "play_sid_file",
+        "play_mod_file",
+        "generate",
+        "compile_play",
+        "play_preset",
+        "pipeline",
+        "analyze",
+        "record_analyze"
+      ],
+      "description": "Selects the operation."
+    },
+    "count": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Number of stereo sample pairs to capture.",
+      "minimum": 1,
+      "maximum": 65536,
+      "default": 256
+    },
+    "encoding": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Encoding used for the PCM sample payload.",
+      "enum": [
+        "base64",
+        "hex"
+      ],
+      "default": "base64"
+    },
+    "volume": {
+      "type": "number",
+      "description": "Desired SID master volume. Values outside 0-15 are clamped.",
+      "minimum": 0,
+      "maximum": 15
+    },
+    "hard": {
+      "type": "boolean",
+      "description": "If true, perform a hard register scrub; otherwise silence voices softly.",
+      "default": false
+    },
+    "voice": {
+      "type": "integer",
+      "description": "SID voice to trigger (1-3).",
+      "minimum": 1,
+      "maximum": 3,
+      "default": 1
+    },
+    "note": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Musical note like A4, C#5, or Bb3. Overrides frequencyHz if provided.",
+      "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$"
+    },
+    "frequencyHz": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Explicit frequency in Hz. Used when note is omitted.",
+      "minimum": 1
+    },
+    "system": {
+      "type": "string",
+      "description": "Video system for frequency calculation.",
+      "enum": [
+        "PAL",
+        "NTSC"
+      ],
+      "default": "PAL"
+    },
+    "waveform": {
+      "type": "string",
+      "description": "SID waveform to enable.",
+      "enum": [
+        "pulse",
+        "saw",
+        "tri",
+        "noise"
+      ],
+      "default": "pulse"
+    },
+    "pulseWidth": {
+      "type": "integer",
+      "description": "Pulse width (0-4095). Used for pulse waveform.",
+      "minimum": 0,
+      "maximum": 4095,
+      "default": 2048
+    },
+    "attack": {
+      "type": "integer",
+      "description": "Attack rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 1
+    },
+    "decay": {
+      "type": "integer",
+      "description": "Decay rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 1
+    },
+    "sustain": {
+      "type": "integer",
+      "description": "Sustain level nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 15
+    },
+    "release": {
+      "type": "integer",
+      "description": "Release rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 3
+    },
+    "verify": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "When true, record audio after silencing to confirm the SID output is quiet.",
+      "default": false
+    },
+    "path": {
+      "type": "string",
+      "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
+      "minLength": 1
+    },
+    "songnr": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Song number within the SID file (0-based index).",
+      "minimum": 0
+    },
+    "root": {
+      "type": "string",
+      "description": "Root note for the arpeggio such as C4 or A#3.",
+      "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$",
+      "default": "C4"
+    },
+    "pattern": {
+      "type": "string",
+      "description": "Comma-separated semitone offsets (e.g. '0,4,7').",
+      "minLength": 1,
+      "default": "0,4,7"
+    },
+    "steps": {
+      "type": "integer",
+      "description": "Number of notes to schedule.",
+      "minimum": 1,
+      "maximum": 128,
+      "default": 16
+    },
+    "tempoMs": {
+      "type": "integer",
+      "description": "Delay in milliseconds between notes.",
+      "minimum": 20,
+      "maximum": 2000,
+      "default": 120
+    },
+    "preset": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional musical preset to influence timing/expression.",
+      "enum": [
+        "classic",
+        "expression"
+      ],
+      "default": "classic"
+    },
+    "sidwave": {
+      "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+      "type": [
+        "string",
+        "object",
+        "null"
+      ]
+    },
+    "cpg": {
+      "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+      "type": [
+        "string",
+        "object",
+        "null"
+      ]
+    },
+    "format": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Source format hint when providing raw text.",
+      "enum": [
+        "yaml",
+        "json"
+      ]
+    },
+    "output": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Playback target format.",
+      "enum": [
+        "prg",
+        "sid"
+      ],
+      "default": "prg"
+    },
+    "dryRun": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "When true, skip playback and only return compilation metadata.",
+      "default": false
+    },
+    "platforms": {
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "type": "string",
+        "description": "Backends to target in sequence.",
+        "minLength": 1,
+        "enum": [
+          "vice",
+          "c64u"
+        ]
+      }
+    },
+    "analysisDurationSeconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Length of the verification recording on analyzable backends.",
+      "minimum": 0.5,
+      "maximum": 20,
+      "default": 4
+    },
+    "waitBeforeCaptureMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between starting playback and beginning verification capture.",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 400
+    },
+    "restoreActiveBackend": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Restore the backend that was active before the workflow started.",
+      "default": true
+    },
+    "expectedSidwave": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional expected SIDWAVE used to refine analysis comparisons.",
+      "minLength": 1
+    },
+    "verifySilenceBefore": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Run silence verification before playback to ensure a quiet baseline.",
+      "default": true
+    },
+    "verifySilenceAfter": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Run silence verification after playback to ensure voices are released.",
+      "default": true
+    },
+    "silenceDurationSeconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Audio capture length used for silence verification.",
+      "minimum": 0.5,
+      "maximum": 10,
+      "default": 1.5
+    },
+    "silenceRmsThreshold": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "RMS threshold applied to silence verification captures.",
+      "minimum": 0,
+      "maximum": 1,
+      "default": 0.02
+    },
+    "postSilenceWaitMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between main analysis capture and the post-playback silence check (milliseconds).",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 200
+    },
+    "silenceWaitMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between silencing the SID and recording during pre/post checks (milliseconds).",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 150
+    },
+    "request": {
+      "type": "string",
+      "description": "Natural language user request describing the verification goal.",
+      "minLength": 1
+    },
+    "durationSeconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Override capture duration in seconds.",
+      "minimum": 0.5,
+      "maximum": 30
+    }
+  },
+  "required": [
+    "op"
+  ],
+  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream. Required inputs: none. Optional inputs: count, encoding.\n- set_volume: Set the SID master volume register at $D418 (0-15). Required inputs: volume.\n- reset: Soft or hard reset of SID registers to clear glitches. Required inputs: none. Optional inputs: hard.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch. Required inputs: none. Optional inputs: voice, note, frequencyHz, system, waveform, pulseWidth, attack, decay, sustain, release.\n- note_off: Release a SID voice by clearing its gate bit. Required inputs: voice.\n- silence_all: Silence all SID voices with optional audio verification. Required inputs: none. Optional inputs: verify.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem. Required inputs: path. Optional inputs: songnr.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player. Required inputs: path.\n- generate: Generate a lightweight SID arpeggio playback sequence. Required inputs: none. Optional inputs: root, pattern, steps, tempoMs, waveform, preset.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately. Required inputs: none. Optional inputs: sidwave, cpg, format, output, dryRun.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven. Required inputs: none. Optional inputs: preset, platforms, verify, analysisDurationSeconds, waitBeforeCaptureMs, restoreActiveBackend.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording. Required inputs: none. Optional inputs: sidwave, cpg, output, waitBeforeCaptureMs, analysisDurationSeconds, expectedSidwave, verifySilenceBefore, verifySilenceAfter, silenceDurationSeconds, silenceRmsThreshold, postSilenceWaitMs, silenceWaitMs.\n- analyze: Automatically analyze SID playback when verification is requested. Required inputs: request. Optional inputs: durationSeconds, expectedSidwave.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics. Required inputs: durationSeconds. Optional inputs: expectedSidwave.",
+  "additionalProperties": false,
+  "x-c64bridge-operations": [
     {
-      "type": "object",
+      "op": "capture_samples",
       "description": "Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.",
-      "properties": {
-        "op": {
-          "const": "capture_samples"
-        },
-        "count": {
-          "type": [
-            "integer",
-            "null"
-          ],
-          "description": "Number of stereo sample pairs to capture.",
-          "minimum": 1,
-          "maximum": 65536,
-          "default": 256
-        },
-        "encoding": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Encoding used for the PCM sample payload.",
-          "enum": [
-            "base64",
-            "hex"
-          ],
-          "default": "base64"
-        }
-      },
-      "required": [
-        "op"
+      "required": [],
+      "optional": [
+        "count",
+        "encoding"
       ],
-      "additionalProperties": false
+      "inputSchema": {
+        "type": "object",
+        "description": "Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.",
+        "properties": {
+          "op": {
+            "const": "capture_samples"
+          },
+          "count": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Number of stereo sample pairs to capture.",
+            "minimum": 1,
+            "maximum": 65536,
+            "default": 256
+          },
+          "encoding": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Encoding used for the PCM sample payload.",
+            "enum": [
+              "base64",
+              "hex"
+            ],
+            "default": "base64"
+          }
+        },
+        "required": [
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "set_volume",
       "description": "Set the SID master volume register at $D418 (0-15).",
-      "properties": {
-        "volume": {
-          "type": "number",
-          "description": "Desired SID master volume. Values outside 0-15 are clamped.",
-          "minimum": 0,
-          "maximum": 15
-        },
-        "op": {
-          "const": "set_volume"
-        }
-      },
       "required": [
-        "volume",
-        "op"
+        "volume"
       ],
-      "additionalProperties": false
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Set the SID master volume register at $D418 (0-15).",
+        "properties": {
+          "volume": {
+            "type": "number",
+            "description": "Desired SID master volume. Values outside 0-15 are clamped.",
+            "minimum": 0,
+            "maximum": 15
+          },
+          "op": {
+            "const": "set_volume"
+          }
+        },
+        "required": [
+          "volume",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "reset",
       "description": "Soft or hard reset of SID registers to clear glitches.",
-      "properties": {
-        "hard": {
-          "type": "boolean",
-          "description": "If true, perform a hard register scrub; otherwise silence voices softly.",
-          "default": false
+      "required": [],
+      "optional": [
+        "hard"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Soft or hard reset of SID registers to clear glitches.",
+        "properties": {
+          "hard": {
+            "type": "boolean",
+            "description": "If true, perform a hard register scrub; otherwise silence voices softly.",
+            "default": false
+          },
+          "op": {
+            "const": "reset"
+          }
         },
-        "op": {
-          "const": "reset"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "note_on",
       "description": "Trigger a SID voice with configurable waveform, ADSR, and pitch.",
-      "properties": {
-        "voice": {
-          "type": "integer",
-          "description": "SID voice to trigger (1-3).",
-          "minimum": 1,
-          "maximum": 3,
-          "default": 1
-        },
-        "note": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Musical note like A4, C#5, or Bb3. Overrides frequencyHz if provided.",
-          "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$"
-        },
-        "frequencyHz": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Explicit frequency in Hz. Used when note is omitted.",
-          "minimum": 1
-        },
-        "system": {
-          "type": "string",
-          "description": "Video system for frequency calculation.",
-          "enum": [
-            "PAL",
-            "NTSC"
-          ],
-          "default": "PAL"
-        },
-        "waveform": {
-          "type": "string",
-          "description": "SID waveform to enable.",
-          "enum": [
-            "pulse",
-            "saw",
-            "tri",
-            "noise"
-          ],
-          "default": "pulse"
-        },
-        "pulseWidth": {
-          "type": "integer",
-          "description": "Pulse width (0-4095). Used for pulse waveform.",
-          "minimum": 0,
-          "maximum": 4095,
-          "default": 2048
-        },
-        "attack": {
-          "type": "integer",
-          "description": "Attack rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 1
-        },
-        "decay": {
-          "type": "integer",
-          "description": "Decay rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 1
-        },
-        "sustain": {
-          "type": "integer",
-          "description": "Sustain level nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 15
-        },
-        "release": {
-          "type": "integer",
-          "description": "Release rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 3
+      "required": [],
+      "optional": [
+        "voice",
+        "note",
+        "frequencyHz",
+        "system",
+        "waveform",
+        "pulseWidth",
+        "attack",
+        "decay",
+        "sustain",
+        "release"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Trigger a SID voice with configurable waveform, ADSR, and pitch.",
+        "properties": {
+          "voice": {
+            "type": "integer",
+            "description": "SID voice to trigger (1-3).",
+            "minimum": 1,
+            "maximum": 3,
+            "default": 1
+          },
+          "note": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Musical note like A4, C#5, or Bb3. Overrides frequencyHz if provided.",
+            "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$"
+          },
+          "frequencyHz": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Explicit frequency in Hz. Used when note is omitted.",
+            "minimum": 1
+          },
+          "system": {
+            "type": "string",
+            "description": "Video system for frequency calculation.",
+            "enum": [
+              "PAL",
+              "NTSC"
+            ],
+            "default": "PAL"
+          },
+          "waveform": {
+            "type": "string",
+            "description": "SID waveform to enable.",
+            "enum": [
+              "pulse",
+              "saw",
+              "tri",
+              "noise"
+            ],
+            "default": "pulse"
+          },
+          "pulseWidth": {
+            "type": "integer",
+            "description": "Pulse width (0-4095). Used for pulse waveform.",
+            "minimum": 0,
+            "maximum": 4095,
+            "default": 2048
+          },
+          "attack": {
+            "type": "integer",
+            "description": "Attack rate nibble (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 1
+          },
+          "decay": {
+            "type": "integer",
+            "description": "Decay rate nibble (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 1
+          },
+          "sustain": {
+            "type": "integer",
+            "description": "Sustain level nibble (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 15
+          },
+          "release": {
+            "type": "integer",
+            "description": "Release rate nibble (0-15).",
+            "minimum": 0,
+            "maximum": 15,
+            "default": 3
+          },
+          "op": {
+            "const": "note_on"
+          }
         },
-        "op": {
-          "const": "note_on"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "note_off",
       "description": "Release a SID voice by clearing its gate bit.",
-      "properties": {
-        "voice": {
-          "type": "integer",
-          "description": "SID voice to release (1-3).",
-          "minimum": 1,
-          "maximum": 3
-        },
-        "op": {
-          "const": "note_off"
-        }
-      },
       "required": [
-        "voice",
-        "op"
+        "voice"
       ],
-      "additionalProperties": false
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Release a SID voice by clearing its gate bit.",
+        "properties": {
+          "voice": {
+            "type": "integer",
+            "description": "SID voice to release (1-3).",
+            "minimum": 1,
+            "maximum": 3
+          },
+          "op": {
+            "const": "note_off"
+          }
+        },
+        "required": [
+          "voice",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "silence_all",
       "description": "Silence all SID voices with optional audio verification.",
-      "properties": {
-        "verify": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "When true, record audio after silencing to confirm the SID output is quiet.",
-          "default": false
+      "required": [],
+      "optional": [
+        "verify"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Silence all SID voices with optional audio verification.",
+        "properties": {
+          "verify": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "When true, record audio after silencing to confirm the SID output is quiet.",
+            "default": false
+          },
+          "op": {
+            "const": "silence_all"
+          }
         },
-        "op": {
-          "const": "silence_all"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "play_sid_file",
       "description": "Play a SID file stored on the Ultimate filesystem.",
-      "properties": {
-        "path": {
-          "type": "string",
-          "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
-          "minLength": 1
-        },
-        "songnr": {
-          "type": [
-            "integer",
-            "null"
-          ],
-          "description": "Song number within the SID file (0-based index).",
-          "minimum": 0
-        },
-        "op": {
-          "const": "play_sid_file"
-        }
-      },
       "required": [
-        "path",
-        "op"
+        "path"
+      ],
+      "optional": [
+        "songnr"
       ],
-      "additionalProperties": false
+      "inputSchema": {
+        "type": "object",
+        "description": "Play a SID file stored on the Ultimate filesystem.",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
+            "minLength": 1
+          },
+          "songnr": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "Song number within the SID file (0-based index).",
+            "minimum": 0
+          },
+          "op": {
+            "const": "play_sid_file"
+          }
+        },
+        "required": [
+          "path",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "play_mod_file",
       "description": "Play a MOD tracker module via the Ultimate SID player.",
-      "properties": {
-        "path": {
-          "type": "string",
-          "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
-          "minLength": 1
-        },
-        "op": {
-          "const": "play_mod_file"
-        }
-      },
       "required": [
-        "path",
-        "op"
+        "path"
       ],
-      "additionalProperties": false
+      "optional": [],
+      "inputSchema": {
+        "type": "object",
+        "description": "Play a MOD tracker module via the Ultimate SID player.",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
+            "minLength": 1
+          },
+          "op": {
+            "const": "play_mod_file"
+          }
+        },
+        "required": [
+          "path",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "generate",
       "description": "Generate a lightweight SID arpeggio playback sequence.",
-      "properties": {
-        "root": {
-          "type": "string",
-          "description": "Root note for the arpeggio such as C4 or A#3.",
-          "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$",
-          "default": "C4"
-        },
-        "pattern": {
-          "type": "string",
-          "description": "Comma-separated semitone offsets (e.g. '0,4,7').",
-          "minLength": 1,
-          "default": "0,4,7"
-        },
-        "steps": {
-          "type": "integer",
-          "description": "Number of notes to schedule.",
-          "minimum": 1,
-          "maximum": 128,
-          "default": 16
-        },
-        "tempoMs": {
-          "type": "integer",
-          "description": "Delay in milliseconds between notes.",
-          "minimum": 20,
-          "maximum": 2000,
-          "default": 120
-        },
-        "waveform": {
-          "type": "string",
-          "description": "Waveform for playback.",
-          "enum": [
-            "pulse",
-            "saw",
-            "tri",
-            "noise"
-          ],
-          "default": "tri"
-        },
-        "preset": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Optional musical preset to influence timing/expression.",
-          "enum": [
-            "classic",
-            "expression"
-          ],
-          "default": "classic"
+      "required": [],
+      "optional": [
+        "root",
+        "pattern",
+        "steps",
+        "tempoMs",
+        "waveform",
+        "preset"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Generate a lightweight SID arpeggio playback sequence.",
+        "properties": {
+          "root": {
+            "type": "string",
+            "description": "Root note for the arpeggio such as C4 or A#3.",
+            "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$",
+            "default": "C4"
+          },
+          "pattern": {
+            "type": "string",
+            "description": "Comma-separated semitone offsets (e.g. '0,4,7').",
+            "minLength": 1,
+            "default": "0,4,7"
+          },
+          "steps": {
+            "type": "integer",
+            "description": "Number of notes to schedule.",
+            "minimum": 1,
+            "maximum": 128,
+            "default": 16
+          },
+          "tempoMs": {
+            "type": "integer",
+            "description": "Delay in milliseconds between notes.",
+            "minimum": 20,
+            "maximum": 2000,
+            "default": 120
+          },
+          "waveform": {
+            "type": "string",
+            "description": "Waveform for playback.",
+            "enum": [
+              "pulse",
+              "saw",
+              "tri",
+              "noise"
+            ],
+            "default": "tri"
+          },
+          "preset": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional musical preset to influence timing/expression.",
+            "enum": [
+              "classic",
+              "expression"
+            ],
+            "default": "classic"
+          },
+          "op": {
+            "const": "generate"
+          }
         },
-        "op": {
-          "const": "generate"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "compile_play",
       "description": "Compile SIDWAVE or CPG source and optionally play it immediately.",
-      "properties": {
-        "sidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "cpg": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "format": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Source format hint when providing raw text.",
-          "enum": [
-            "yaml",
-            "json"
-          ]
-        },
-        "output": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Playback target format.",
-          "enum": [
-            "prg",
-            "sid"
-          ],
-          "default": "prg"
-        },
-        "dryRun": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "When true, skip playback and only return compilation metadata.",
-          "default": false
+      "required": [],
+      "optional": [
+        "sidwave",
+        "cpg",
+        "format",
+        "output",
+        "dryRun"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Compile SIDWAVE or CPG source and optionally play it immediately.",
+        "properties": {
+          "sidwave": {
+            "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+            "type": [
+              "string",
+              "object",
+              "null"
+            ]
+          },
+          "cpg": {
+            "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+            "type": [
+              "string",
+              "object",
+              "null"
+            ]
+          },
+          "format": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Source format hint when providing raw text.",
+            "enum": [
+              "yaml",
+              "json"
+            ]
+          },
+          "output": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Playback target format.",
+            "enum": [
+              "prg",
+              "sid"
+            ],
+            "default": "prg"
+          },
+          "dryRun": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "When true, skip playback and only return compilation metadata.",
+            "default": false
+          },
+          "op": {
+            "const": "compile_play"
+          }
         },
-        "op": {
-          "const": "compile_play"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "play_preset",
       "description": "Compile and play a built-in SID preset such as Für Elise by Beethoven.",
-      "properties": {
-        "preset": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Named SID preset to compile and play. Canonical public preset: fuer_elise.",
-          "minLength": 1,
-          "default": "fuer_elise"
-        },
-        "platforms": {
-          "type": [
-            "array",
-            "null"
-          ],
-          "items": {
-            "type": "string",
-            "description": "Backends to target in sequence.",
+      "required": [],
+      "optional": [
+        "preset",
+        "platforms",
+        "verify",
+        "analysisDurationSeconds",
+        "waitBeforeCaptureMs",
+        "restoreActiveBackend"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Compile and play a built-in SID preset such as Für Elise by Beethoven.",
+        "properties": {
+          "preset": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Named SID preset to compile and play. Canonical public preset: fuer_elise.",
             "minLength": 1,
-            "enum": [
-              "vice",
-              "c64u"
-            ]
+            "default": "fuer_elise"
+          },
+          "platforms": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string",
+              "description": "Backends to target in sequence.",
+              "minLength": 1,
+              "enum": [
+                "vice",
+                "c64u"
+              ]
+            }
+          },
+          "verify": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Capture and analyze audio on supported backends after playback starts.",
+            "default": true
+          },
+          "analysisDurationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Length of the verification recording on analyzable backends.",
+            "minimum": 0.5,
+            "maximum": 20,
+            "default": 4
+          },
+          "waitBeforeCaptureMs": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Delay between starting playback and beginning verification capture.",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 400
+          },
+          "restoreActiveBackend": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Restore the backend that was active before the workflow started.",
+            "default": true
+          },
+          "op": {
+            "const": "play_preset"
           }
         },
-        "verify": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Capture and analyze audio on supported backends after playback starts.",
-          "default": true
-        },
-        "analysisDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Length of the verification recording on analyzable backends.",
-          "minimum": 0.5,
-          "maximum": 20,
-          "default": 4
-        },
-        "waitBeforeCaptureMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between starting playback and beginning verification capture.",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 400
-        },
-        "restoreActiveBackend": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Restore the backend that was active before the workflow started.",
-          "default": true
-        },
-        "op": {
-          "const": "play_preset"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "pipeline",
       "description": "Compile a SIDWAVE score, play it, and analyze the recording.",
-      "properties": {
-        "sidwave": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "SIDWAVE source in YAML or JSON format.",
-          "minLength": 1
-        },
-        "cpg": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Legacy CPG input format.",
-          "minLength": 1
-        },
-        "output": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Playback artifact format.",
-          "enum": [
-            "prg",
-            "sid"
-          ],
-          "default": "prg"
-        },
-        "waitBeforeCaptureMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between starting playback and beginning analysis capture (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 500
-        },
-        "analysisDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Audio capture length in seconds.",
-          "minimum": 0.5,
-          "maximum": 20,
-          "default": 3
-        },
-        "expectedSidwave": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Optional expected SIDWAVE used to refine analysis comparisons.",
-          "minLength": 1
-        },
-        "verifySilenceBefore": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Run silence verification before playback to ensure a quiet baseline.",
-          "default": true
-        },
-        "verifySilenceAfter": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Run silence verification after playback to ensure voices are released.",
-          "default": true
-        },
-        "silenceDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Audio capture length used for silence verification.",
-          "minimum": 0.5,
-          "maximum": 10,
-          "default": 1.5
-        },
-        "silenceRmsThreshold": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "RMS threshold applied to silence verification captures.",
-          "minimum": 0,
-          "maximum": 1,
-          "default": 0.02
-        },
-        "postSilenceWaitMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between main analysis capture and the post-playback silence check (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 200
-        },
-        "silenceWaitMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between silencing the SID and recording during pre/post checks (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 150
+      "required": [],
+      "optional": [
+        "sidwave",
+        "cpg",
+        "output",
+        "waitBeforeCaptureMs",
+        "analysisDurationSeconds",
+        "expectedSidwave",
+        "verifySilenceBefore",
+        "verifySilenceAfter",
+        "silenceDurationSeconds",
+        "silenceRmsThreshold",
+        "postSilenceWaitMs",
+        "silenceWaitMs"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "description": "Compile a SIDWAVE score, play it, and analyze the recording.",
+        "properties": {
+          "sidwave": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "SIDWAVE source in YAML or JSON format.",
+            "minLength": 1
+          },
+          "cpg": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Legacy CPG input format.",
+            "minLength": 1
+          },
+          "output": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Playback artifact format.",
+            "enum": [
+              "prg",
+              "sid"
+            ],
+            "default": "prg"
+          },
+          "waitBeforeCaptureMs": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Delay between starting playback and beginning analysis capture (milliseconds).",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 500
+          },
+          "analysisDurationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Audio capture length in seconds.",
+            "minimum": 0.5,
+            "maximum": 20,
+            "default": 3
+          },
+          "expectedSidwave": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional expected SIDWAVE used to refine analysis comparisons.",
+            "minLength": 1
+          },
+          "verifySilenceBefore": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Run silence verification before playback to ensure a quiet baseline.",
+            "default": true
+          },
+          "verifySilenceAfter": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Run silence verification after playback to ensure voices are released.",
+            "default": true
+          },
+          "silenceDurationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Audio capture length used for silence verification.",
+            "minimum": 0.5,
+            "maximum": 10,
+            "default": 1.5
+          },
+          "silenceRmsThreshold": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "RMS threshold applied to silence verification captures.",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.02
+          },
+          "postSilenceWaitMs": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Delay between main analysis capture and the post-playback silence check (milliseconds).",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 200
+          },
+          "silenceWaitMs": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Delay between silencing the SID and recording during pre/post checks (milliseconds).",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 150
+          },
+          "op": {
+            "const": "pipeline"
+          }
         },
-        "op": {
-          "const": "pipeline"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+        "additionalProperties": false,
+        "required": [
+          "op"
+        ]
+      }
     },
     {
-      "type": "object",
+      "op": "analyze",
       "description": "Automatically analyze SID playback when verification is requested.",
-      "properties": {
-        "request": {
-          "type": "string",
-          "description": "Natural language user request describing the verification goal.",
-          "minLength": 1
-        },
-        "durationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Override capture duration in seconds.",
-          "minimum": 0.5,
-          "maximum": 30
-        },
-        "expectedSidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "op": {
-          "const": "analyze"
-        }
-      },
       "required": [
-        "request",
-        "op"
+        "request"
+      ],
+      "optional": [
+        "durationSeconds",
+        "expectedSidwave"
       ],
-      "additionalProperties": false
+      "inputSchema": {
+        "type": "object",
+        "description": "Automatically analyze SID playback when verification is requested.",
+        "properties": {
+          "request": {
+            "type": "string",
+            "description": "Natural language user request describing the verification goal.",
+            "minLength": 1
+          },
+          "durationSeconds": {
+            "type": [
+              "number",
+              "null"
+            ],
+            "description": "Override capture duration in seconds.",
+            "minimum": 0.5,
+            "maximum": 30
+          },
+          "expectedSidwave": {
+            "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+            "type": [
+              "string",
+              "object",
+              "null"
+            ]
+          },
+          "op": {
+            "const": "analyze"
+          }
+        },
+        "required": [
+          "request",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     },
     {
-      "type": "object",
+      "op": "record_analyze",
       "description": "Record audio for a fixed duration and return SID analysis metrics.",
-      "properties": {
-        "durationSeconds": {
-          "type": "number",
-          "description": "Capture duration in seconds (0.5 - 30).",
-          "minimum": 0.5,
-          "maximum": 30
-        },
-        "expectedSidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "op": {
-          "const": "record_analyze"
-        }
-      },
       "required": [
-        "durationSeconds",
-        "op"
+        "durationSeconds"
+      ],
+      "optional": [
+        "expectedSidwave"
       ],
-      "additionalProperties": false
+      "inputSchema": {
+        "type": "object",
+        "description": "Record audio for a fixed duration and return SID analysis metrics.",
+        "properties": {
+          "durationSeconds": {
+            "type": "number",
+            "description": "Capture duration in seconds (0.5 - 30).",
+            "minimum": 0.5,
+            "maximum": 30
+          },
+          "expectedSidwave": {
+            "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+            "type": [
+              "string",
+              "object",
+              "null"
+            ]
+          },
+          "op": {
+            "const": "record_analyze"
+          }
+        },
+        "required": [
+          "durationSeconds",
+          "op"
+        ],
+        "additionalProperties": false
+      }
     }
-  ],
-  "discriminator": {
-    "propertyName": "op"
-  }
+  ]
 }