Tool reference
On this page
Find a tool below for its arguments, example request, response, and recovery path. All 57 registered tools are documented; live availability depends on the connected bridge.
Calling and safety
The MCP server returns successful tool results as JSON text. A failed call returns an Error: ... result; that error alone is not proof that a preceding host request did or did not reach Bitwig. For timeouts or ambiguous submitted responses, read current state before retrying.
Examples are illustrative, not recorded responses or executable project recipes. Replace every token, UUID, module, port, control, action, path, and session identifier with values from your current reads. Argument contracts are generated from source registrations by tools/tool_reference.py; response and recovery guidance is authored alongside them.
A graph mutation uses the exact lowercase 64-hex expected_revision returned by a fresh graph read and, for guarded writes, confirm: true or explicitly authorized cooperative: true. Project, selection, mix, graph, shaping-session, and composition revisions/tokens are different authorities and must never be substituted for one another. Selected-device values are exposed as 0–128; normalized native controls use 0–1. Graph revisions are 64-hex strings; shaping and patch-session revisions are integers; composition revisions are 64-hex strings.
The offline composition and audio families do not connect to Bitwig. Composition export writes a real Type-1 MIDI artifact and digest-bound manifest only; audio tools inspect bounded local files and do not record, render a project, or make perceptual quality claims.
Core and Grid tools (30)
get_selected_device_state
Purpose. Read the currently selected device, including Grid graph topology and editable module parameters when the Grid bridge is available.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "get_selected_device_state",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object containing available, graph_available, bridge, properties, parameters, and selection; when graph data is available it may also contain graph, and unavailable fallback includes error.
Recovery. If available or graph_available is false, call get_grid_capabilities and keep graph work unavailable until the bridge reports it; do not treat fallback device properties as a live Grid graph.
get_grid_capabilities
Purpose. Inspect bridge capabilities and selected-device container flags. Use this before attempting automated Grid reconstruction.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "get_grid_capabilities",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object with available, bridge, and (when available) capabilities and inspection; an unavailable response can include graph_available and error.
Recovery. If the bridge is unavailable, do not attempt graph writes; restore the local bridge/runtime first and call this read again.
get_grid_graph
Purpose. Read the selected Grid's module instances, ports, connections, coordinates, and editable module parameters.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "get_grid_graph",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object with available, bridge, and graph fields from the bridge, including the graph identity/revision, modules, ports, and connections; unavailable responses include capability flags and may include error.
Recovery. If the read is unavailable or returns an error, stop mutations, call get_grid_capabilities, then re-read the graph before reviewing a write.
search_grid_modules
Purpose. Search installed Bitwig Grid modules by name or package UUID.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None.
Optional arguments. query
Registered argument contract.
query— optional; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "search_grid_modules",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object with available, bridge, and modules (an array of catalog entries); unavailable or failed reads return an empty array and may include error.
Recovery. Use an empty or narrower query when there are no matches; use only package IDs returned by a fresh catalog read, never a guessed alias.
search_grid_modulators
Purpose. Search the installed Grid modulation catalog. Results include semantic roles, input/output hints, and tuning parameters.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None.
Optional arguments. query
Registered argument contract.
query— optional; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "search_grid_modulators",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object with available, bridge, and modulators (an array of semantic catalog entries); unavailable or failed reads return an empty array and may include error.
Recovery. Broaden the query if the result is empty, then use the returned module and parameter metadata; do not invent a modulator ID or port.
grid_soundscape_plan
Purpose. Create a generic, non-mutating Grid soundscape recipe from an artistic brief. The result names live-resolvable module roles, routing order, tuning targets, and safety guardrails; it never contains a preset payload.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. brief
Optional arguments. style, density, motion, contrast, temperature
Registered argument contract.
brief— required; stringstyle— optional; stringdensity— optional; number; minimum:0; maximum:1motion— optional; number; minimum:0; maximum:1contrast— optional; number; minimum:0; maximum:1temperature— optional; number; minimum:0; maximum:1- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_soundscape_plan",
"arguments": {
"brief": "A restrained, slowly moving one-voice texture.",
"density": 0.35,
"motion": 0.4
}
}
Representative response shape (illustrative, not observed evidence). An object with ok, normalized brief/style/controls, principles, layers, module_queries, assembly_order, resolution, and guardrails.
Recovery. Treat module_queries as search terms, not a patch payload: resolve them with search_grid_modules, then follow the returned resolution steps.
grid_list_soundscape_styles
Purpose. List the internal generic Grid soundscape style vocabulary without exposing external patch or preset content.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_list_soundscape_styles",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An array of style objects with id, aliases, and principles.
Recovery. Use a returned style id or omit the style; an absent style is not evidence that a private preset is available.
get_grid_host_modulators
Purpose. Inspect host-level modulation sources exposed by the selected Grid device, including names and mapping state. This is read-only; resolve module parameters from the live graph.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "get_grid_host_modulators",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object with available, bridge, and sources; unavailable or failed reads return an empty sources array and may include error.
Recovery. If unavailable or sources is empty, leave host mapping unresolved and re-read selected-device state rather than claiming a mapping.
grid_insert_modulator
Purpose. Insert a cataloged Grid modulator or Modulator Out at graph coordinates. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. package_id, x, y, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
package_id— required; stringx— required; integer; minimum:-4096; maximum:4096y— required; integer; minimum:-4096; maximum:4096confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_insert_modulator",
"arguments": {
"package_id": "00000000-0000-4000-8000-000000000000",
"x": 0,
"y": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. On a stale revision, unavailable bridge, or failed read-back, call get_grid_graph, review the intended insertion, and submit a new exact revision; never replay the old request.
grid_connect_modulator
Purpose. Connect a cataloged Grid modulator output to a Grid input. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. source_module_id, source_port, target_module_id, target_port, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
source_module_id— required; stringsource_port— required; integer; minimum:0target_module_id— required; stringtarget_port— required; integer; minimum:0confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_connect_modulator",
"arguments": {
"source_module_id": "source-module-from-grid-graph",
"source_port": 0,
"target_module_id": "target-module-from-grid-graph",
"target_port": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. Re-read the graph and catalog for exact module IDs and symbolic ports after any rejection; use a new graph revision and do not replay an ambiguous connection.
grid_set_modulator_parameter
Purpose. Tune one parameter on a cataloged Grid modulator. Use the catalog and live graph metadata for valid ranges and options. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. module_id, parameter_id, value, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
module_id— required; stringparameter_id— required; stringvalue— required; number or boolean- Alternatives (
anyOf):- Option 1: number
- Option 2: boolean
- Alternatives (
confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_set_modulator_parameter",
"arguments": {
"module_id": "module-from-grid-graph",
"parameter_id": "parameter-from-grid-graph",
"value": 0.5,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. Read the live graph for the parameter's range/options and exact module ID, then retry only with a fresh graph revision and reviewed value.
grid_insert_module
Purpose. Insert a known Grid module at graph coordinates. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. package_id, x, y, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
package_id— required; stringx— required; integer; minimum:-4096; maximum:4096y— required; integer; minimum:-4096; maximum:4096confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_insert_module",
"arguments": {
"package_id": "00000000-0000-4000-8000-000000000000",
"x": 0,
"y": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. On a stale revision or catalog rejection, search the catalog and re-read the graph before submitting a newly reviewed insertion; do not guess a package ID.
grid_set_module_parameter
Purpose. Set one editable Grid module parameter. Use get_grid_graph for the parameter's native range or discrete options; toggles use booleans. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. module_id, parameter_id, value, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
module_id— required; stringparameter_id— required; stringvalue— required; number or boolean- Alternatives (
anyOf):- Option 1: number
- Option 2: boolean
- Alternatives (
confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_set_module_parameter",
"arguments": {
"module_id": "module-from-grid-graph",
"parameter_id": "parameter-from-grid-graph",
"value": 0.5,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. Use get_grid_graph to resolve the native range or discrete options, then use its fresh revision; a failed write is not permission to clamp or guess.
grid_connect_modules
Purpose. Connect a Grid module output to an input port. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. source_module_id, source_port, target_module_id, target_port, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
source_module_id— required; stringsource_port— required; integer; minimum:0target_module_id— required; stringtarget_port— required; integer; minimum:0confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_connect_modules",
"arguments": {
"source_module_id": "source-module-from-grid-graph",
"source_port": 0,
"target_module_id": "target-module-from-grid-graph",
"target_port": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. Re-read the graph for exact module IDs and port names/indices, review the route, and submit a new revision after any stale or ambiguous result.
grid_disconnect_module
Purpose. Disconnect a Grid input port. This mutates the project and requires confirmation unless the prompt or active skill explicitly requests cooperative work.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. target_module_id, target_port, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
target_module_id— required; stringtarget_port— required; integer; minimum:0confirm— optional; booleancooperative— optional; booleanexpected_revision— required; string; pattern:^[0-9a-f]{64}$; Exact revision returned by the reviewed live graph.- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_disconnect_module",
"arguments": {
"target_module_id": "module-from-grid-graph",
"target_port": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful object payload, normally carrying ok: true plus the resulting graph-edit fields; the exact returned fields are host/runtime data.
Recovery. Treat this as a topology mutation: re-read the graph, confirm the target input, and use a fresh revision instead of retrying after an uncertain response.
grid_list_style_presets
Purpose. List the repository's authored Grid style profiles and their behavioral principles.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_list_style_presets",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An array of authored style profile objects; the exact profile keys and values come from the current source implementation.
Recovery. Use only the returned authored profile names and values; if a profile is missing, choose another returned profile rather than fabricating one.
grid_shape_start
Purpose. Start a preview-first Bitwig Grid shaping session. Compose a style draft without mutating Bitwig.
Authority / capability. Process-local preview or snapshot state only; this call does not apply a Bitwig parameter change.
Required arguments. brief
Optional arguments. preset, style, intensity, controls
Registered argument contract.
brief— required; string; Human intent for the Grid sound and interaction.preset— optional; string; enum:"acid","ember","glass","hollow"; Optional parameter scaffold; style profiles choose one when omitted.style— optional; string; enum:"slow-air","deep-bed","distant-events","soft-drift","night-motion","layered-motion","pulse-lab"; Optional authored style profile for motion, density, and space.intensity— optional; number; minimum:0; maximum:1; Blend amount; style profiles provide a conservative default.controls— optional; object; Optional exposed parameter names or indexes mapped to 0-1 values.- Additional property values: number; minimum:
0; maximum:1.
- Additional property values: number; minimum:
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_shape_start",
"arguments": {
"brief": "A restrained, slowly moving Grid texture.",
"preset": "glass",
"style": "slow-air",
"intensity": 0.5,
"controls": {
"parameter-name-from-state": 0.5
}
}
}
Representative response shape (illustrative, not observed evidence). A shaping-session object containing a process-local session_id, integer revision, status, selected-device data, draft controls, and a preview of changes.
Recovery. If the selected device or bridge is unavailable, keep the draft unapplied and restore capability first; otherwise review the returned draft before composing or applying.
grid_shape_compose
Purpose. Revise a Grid shaping draft. This is a non-mutating preview step; apply only after reviewing the returned changes.
Authority / capability. Process-local preview or snapshot state only; this call does not apply a Bitwig parameter change.
Required arguments. session_id
Optional arguments. preset, style, intensity, controls
Registered argument contract.
session_id— required; stringpreset— optional; string; enum:"acid","ember","glass","hollow"style— optional; string; enum:"slow-air","deep-bed","distant-events","soft-drift","night-motion","layered-motion","pulse-lab"intensity— optional; number; minimum:0; maximum:1controls— optional; object- Additional property values: number; minimum:
0; maximum:1.
- Additional property values: number; minimum:
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_shape_compose",
"arguments": {
"session_id": "session-id-from-grid-shape-start",
"intensity": 0.45
}
}
Representative response shape (illustrative, not observed evidence). The updated shaping-session object with the current integer revision, draft/status, selected-device data, and preview; it does not apply Bitwig changes.
Recovery. For an unknown session, start a new draft; for a rejected compose, call grid_shape_status and use the current session state instead of reusing stale assumptions.
grid_shape_status
Purpose. Return the live state and current preview for a Grid shaping session.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. session_id
Optional arguments. None.
Registered argument contract.
session_id— required; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_shape_status",
"arguments": {
"session_id": "session-id-from-grid-shape-start"
}
}
Representative response shape (illustrative, not observed evidence). The current shaping-session object with session_id, integer revision, status, selected-device data, draft controls, and history count.
Recovery. If the session ID is unknown, start a new shaping session; if state changed externally, discard the draft and re-read the selected device.
grid_shape_apply
Purpose. Apply an exact reviewed Grid shaping revision. Requires confirmation unless the prompt or active skill explicitly requests cooperative work; stale or externally changed state is always rejected.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. session_id, revision
Optional arguments. confirm, cooperative
Registered argument contract.
session_id— required; stringrevision— required; integer; minimum:1confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_shape_apply",
"arguments": {
"session_id": "session-id-from-grid-shape-start",
"revision": 1,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). An applied-session object including revision, changed, before, and after, plus current session/status fields; application is guarded and should be verified by a fresh read.
Recovery. On a stale revision or external state change, call grid_shape_status, review a current draft, and apply only that revision with explicit authority; never replay the old apply.
grid_shape_undo
Purpose. Restore the previous parameter state for a Grid shaping session.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. session_id
Optional arguments. None.
Registered argument contract.
session_id— required; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_shape_undo",
"arguments": {
"session_id": "session-id-from-grid-shape-start"
}
}
Representative response shape (illustrative, not observed evidence). The updated shaping-session object including an undone summary (changed and from_revision) and a new integer revision.
Recovery. If there is no completed apply in the session, keep the current state and start a reviewed draft; do not treat undo as project-wide history.
grid_project_undo
Purpose. Undo the latest Bitwig host operation through the Grid bridge.
Authority / capability. No confirmation field is registered; this uses the existing selected-device/host shaping path. Read state back after the operation.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_project_undo",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful host-operation object, normally carrying ok: true and host history/state fields.
Recovery. After an ambiguous or unavailable host response, read selected-device/project state before deciding whether another undo is safe; do not blindly repeat it.
grid_project_redo
Purpose. Redo the latest Bitwig host operation through the Grid bridge.
Authority / capability. No confirmation field is registered; this uses the existing selected-device/host shaping path. Read state back after the operation.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_project_redo",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful host-operation object, normally carrying ok: true and host history/state fields.
Recovery. After an ambiguous or unavailable host response, read selected-device/project state before deciding whether another redo is safe; do not blindly repeat it.
grid_navigate_device
Purpose. Navigate the selected device to its next, previous, or parent device.
Authority / capability. No confirmation field is registered; this uses the existing selected-device/host shaping path. Read state back after the operation.
Required arguments. direction
Optional arguments. None.
Registered argument contract.
direction— required; string; enum:"next","previous","parent"- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_navigate_device",
"arguments": {
"direction": "next"
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful selection/device-state object, normally carrying ok: true and the resulting selection fields.
Recovery. If navigation fails, re-read selected-device state and use only next, previous, or parent; do not infer the resulting selection.
grid_list_tracks
Purpose. List existing main tracks and their zero-based live bank indexes.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_list_tracks",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's track-bank object, or an unavailable object with available: false and bridge: false.
Recovery. Use the returned zero-based live bank indexes; if unavailable, restore bridge availability and read again rather than assuming track names or indexes.
grid_select_track
Purpose. Select a main track by the zero-based index returned by grid_list_tracks.
Authority / capability. No confirmation field is registered; this uses the existing selected-device/host shaping path. Read state back after the operation.
Required arguments. track_index
Optional arguments. None.
Registered argument contract.
track_index— required; integer; minimum:0; maximum:63- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_select_track",
"arguments": {
"track_index": 0
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful selection object, normally carrying ok: true and the resulting track/selection fields.
Recovery. If selection fails, re-list tracks and submit the current zero-based index; then read state before acting on the selection.
set_selected_device_parameters
Purpose. Set multiple parameters on the currently selected device.
Authority / capability. No confirmation field is registered; this uses the existing selected-device/host shaping path. Read state back after the operation.
Required arguments. parameters
Optional arguments. None.
Registered argument contract.
parameters— required; object; Map exposed parameter indexes to values in the 0-128 bridge range.- Additional property values: number.
- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "set_selected_device_parameters",
"arguments": {
"parameters": {
"1": 64
}
}
}
Representative response shape (illustrative, not observed evidence). A JSON array of changed parameter indexes; the server wraps this as {"changed": [...]} for MCP execution.
Recovery. If a parameter write fails, re-read selected-device state and use its exposed indexes and 0–128 values; do not silently clamp or substitute native 0–1 values.
save_parameter_snapshot
Purpose. Save observable parameters of the selected device in memory.
Authority / capability. Process-local preview or snapshot state only; this call does not apply a Bitwig parameter change.
Required arguments. name
Optional arguments. None.
Registered argument contract.
name— required; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "save_parameter_snapshot",
"arguments": {
"name": "before-review"
}
}
Representative response shape (illustrative, not observed evidence). An object with the snapshot name and a parameters map of exposed indexes to selected-device values.
Recovery. If the selected device is unavailable, resolve that state first; snapshot names are process-local, so recreate a missing snapshot rather than assuming it persisted.
compare_parameter_snapshots
Purpose. Compare two in-memory selected-device parameter snapshots.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. first, second
Optional arguments. None.
Registered argument contract.
first— required; stringsecond— required; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "compare_parameter_snapshots",
"arguments": {
"first": "before-review",
"second": "after-review"
}
}
Representative response shape (illustrative, not observed evidence). An object with first, second, changed entries (index, before, after), and boolean identical.
Recovery. If either name is unknown, save or select an existing process-local snapshot; do not infer differences from a live read alone.
apply_parameter_snapshot
Purpose. Apply an in-memory parameter snapshot to the selected device.
Authority / capability. Writes the selected device's exposed parameters; read selected-device state first and verify afterward.
Required arguments. name
Optional arguments. None.
Registered argument contract.
name— required; string- Top-level additional properties: allowed by registration; runtime dispatch may still reject unknown fields.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "apply_parameter_snapshot",
"arguments": {
"name": "before-review"
}
}
Representative response shape (illustrative, not observed evidence). A JSON array of changed parameter indexes; the server wraps this as {"changed": [...]} for MCP execution.
Recovery. If the snapshot is missing or stale, re-read state and recreate a reviewed snapshot; applying a snapshot is not a project-wide undo.
Native host tools (14)
grid_song_state
Purpose. Observe project identity, transport, meter, loop and recording state.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_song_state",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's song-state object, normally carrying ok: true plus project token, transport, meter, loop, recording, and capability fields.
Recovery. If the read is unavailable, call get_grid_capabilities and restore the bridge; never treat an absent token as authorization for transport writes.
grid_song_transport
Purpose. Submit one guarded transport change; observe song state to verify completion.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. expected_project_token, operation
Optional arguments. position_beats, tempo_bpm, numerator, denominator, enabled, start_beats, duration_beats, confirm, cooperative
Registered argument contract.
expected_project_token— required; string; pattern:^[0-9a-f]{64}$operation— required; string; enum:"play","continue","restart","stop","seek","tempo","meter","loop"position_beats— optional; number; minimum:0; maximum:24576tempo_bpm— optional; number; minimum:40; maximum:220numerator— optional; integer; minimum:2; maximum:12denominator— optional; integer; enum:4,8enabled— optional; booleanstart_beats— optional; number; minimum:0duration_beats— optional; number; greater than:0confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_song_transport",
"arguments": {
"expected_project_token": "0000000000000000000000000000000000000000000000000000000000000000",
"operation": "tempo",
"tempo_bpm": 120,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's submitted-operation object, normally carrying ok: true, status: "submitted", and a proxy observation; verify completion with grid_song_state.
Recovery. After rejection, timeout, or an ambiguous submitted response, call grid_song_state, then use the fresh project token and only fields for the chosen operation.
grid_set_track_state
Purpose. Submit mute/arm changes for one observed main-bank track; recording is rejected.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. expected_project_token, track_index
Optional arguments. muted, armed, confirm, cooperative
Registered argument contract.
expected_project_token— required; string; pattern:^[0-9a-f]{64}$track_index— required; integer; minimum:0; maximum:63muted— optional; booleanarmed— optional; booleanconfirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_set_track_state",
"arguments": {
"expected_project_token": "0000000000000000000000000000000000000000000000000000000000000000",
"track_index": 0,
"muted": false,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's submitted track-operation object, normally carrying ok: true, status: "submitted", and a proxy observation; read song state again.
Recovery. On a stale token or rejected recording/automation state, call grid_song_state, review the track, and submit a fresh token with at least one requested state field.
grid_inspect_mix
Purpose. Read gain, pan and available send controls, automation state and exact mix revision.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. track_index
Optional arguments. None.
Registered argument contract.
track_index— required; integer; minimum:0; maximum:63- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_inspect_mix",
"arguments": {
"track_index": 0
}
}
Representative response shape (illustrative, not observed evidence). The bridge's mix-state object, including the track's controls, automation/control capabilities, and exact mix revision.
Recovery. Re-read this track after a rejected or ambiguous mix operation; use the returned mix revision and control IDs, not cached values.
grid_set_mix
Purpose. Submit one non-automated mix control change using observed identity, revision and normalized value.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. track_index, expected_project_token, expected_mix_revision, control_id, expected_normalized, normalized
Optional arguments. confirm, cooperative
Registered argument contract.
track_index— required; integer; minimum:0; maximum:63expected_project_token— required; string; pattern:^[0-9a-f]{64}$expected_mix_revision— required; string; pattern:^[0-9a-f]{64}$control_id— required; stringexpected_normalized— required; number; minimum:0; maximum:1normalized— required; number; minimum:0; maximum:1confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_set_mix",
"arguments": {
"track_index": 0,
"expected_project_token": "0000000000000000000000000000000000000000000000000000000000000000",
"expected_mix_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"control_id": "control-id-from-grid-inspect-mix",
"expected_normalized": 0.5,
"normalized": 0.65,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's submitted mix-operation object, normally carrying ok: true, status: "submitted", and a proxy observation; inspect the mix again.
Recovery. On a stale mix revision, automation rejection, or uncertain result, call grid_inspect_mix and submit a reviewed normalized value with fresh project and mix tokens.
grid_list_devices
Purpose. Read the selected sibling device bank and current selection token without navigating.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_list_devices",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's selected-device bank object, including device entries and the current selection token.
Recovery. Use the returned selection token and UUIDs; after any device change, list the bank again because its window and token may change.
grid_insert_device
Purpose. Insert a known device UUID at an explicit position guarded by the current selection token.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. device_id, position, expected_selection_token
Optional arguments. confirm, cooperative
Registered argument contract.
device_id— required; string; format:uuidposition— required; string; enum:"before","after","start","end","replace"expected_selection_token— required; string; pattern:^[0-9a-f]{64}$confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_insert_device",
"arguments": {
"device_id": "00000000-0000-4000-8000-000000000000",
"position": "before",
"expected_selection_token": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's submitted device-operation object, normally carrying ok: true, status: "submitted", and a proxy observation; list devices again.
Recovery. On a stale selection token or uncertain response, call grid_list_devices, review the exact UUID and position, and submit a new guarded request.
grid_remove_device
Purpose. Remove the exactly observed selected device; this is destructive and requires explicit authority.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. expected_selection_token
Optional arguments. confirm, cooperative
Registered argument contract.
expected_selection_token— required; string; pattern:^[0-9a-f]{64}$confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_remove_device",
"arguments": {
"expected_selection_token": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's submitted destructive-operation object, normally carrying ok: true, status: "submitted", and a proxy observation; list devices again.
Recovery. This is destructive: after any stale or ambiguous result, list devices and inspect selection before deciding whether removal occurred; never repeat blindly.
grid_move_module
Purpose. Move one live Grid module in Grid-point units with native undo and an exact graph revision.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. module_id, x, y, expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
module_id— required; stringx— required; integer; minimum:-4096; maximum:4096y— required; integer; minimum:-4096; maximum:4096expected_revision— required; string; pattern:^[0-9a-f]{64}$confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_move_module",
"arguments": {
"module_id": "module-from-grid-graph",
"x": 0,
"y": 0,
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful graph-edit object, normally carrying ok: true and the resulting graph revision/state fields.
Recovery. On a stale graph revision or uncertain response, call get_grid_graph, confirm the module coordinates, and submit a new reviewed move.
grid_clear_graph
Purpose. Clear the selected Grid in one native operation, retaining its before snapshot; destructive, never implicit recovery.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. expected_revision
Optional arguments. confirm, cooperative
Registered argument contract.
expected_revision— required; string; pattern:^[0-9a-f]{64}$confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_clear_graph",
"arguments": {
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). An object containing the bridge clear result plus before, the graph snapshot read before clearing; this is a destructive operation.
Recovery. Treat failure or timeout as ambiguous: call get_grid_graph and review the before/after topology; never repeat a destructive clear without a fresh explicit review.
grid_resolve_parameter_value
Purpose. Resolve a numeric display quantity through Bitwig's native definition, an exact enum label, or a boolean/integer literal. Read-only; returns a guarded native value for separate reviewed application. Numeric units: Hz, kHz, s, ms, st, oct, dB, %, bpm, beats, bars, k, m, cents, c.
Authority / capability. Requires the exact current lowercase 64-hex graph revision; review the graph immediately before this operation.
Required arguments. module_id, parameter_id, display_value, expected_revision
Optional arguments. None.
Registered argument contract.
module_id— required; stringparameter_id— required; stringdisplay_value— required; string; min length:1; max length:256expected_revision— required; string; pattern:^[0-9a-f]{64}$- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_resolve_parameter_value",
"arguments": {
"module_id": "module-from-grid-graph",
"parameter_id": "parameter-from-grid-graph",
"display_value": "440 Hz",
"expected_revision": "0000000000000000000000000000000000000000000000000000000000000000"
}
}
Representative response shape (illustrative, not observed evidence). The bridge's resolution object, normally carrying ok: true and a guarded native value/definition for a separate reviewed application.
Recovery. Re-read the graph for the exact module, parameter, and revision when resolution fails; this read resolves a value but does not apply it.
search_grid_devices
Purpose. Search the installed factory device catalog for actual package UUIDs; excludes third-party plug-ins.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None.
Optional arguments. query
Registered argument contract.
query— optional; string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "search_grid_devices",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's factory device-catalog object, normally carrying ok: true and matching package UUID entries.
Recovery. Use only returned factory package UUIDs; broaden the query or re-check bridge availability when no device matches, and do not substitute a plug-in ID.
grid_list_actions
Purpose. List actual Bitwig host action IDs; listing does not authorize invocation.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None.
Optional arguments. query
Registered argument contract.
query— optional; string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_list_actions",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). The bridge's action-catalog object, normally carrying ok: true and the currently available exact action IDs.
Recovery. Review the exact returned action IDs; if invocation later fails or state is unclear, list actions again before selecting another ID.
grid_invoke_action
Purpose. Invoke one exact discovered host action. Actions may open dialogs or affect global state; review the exact action first.
Authority / capability. Guarded write path: pass confirm: true or explicitly authorized cooperative: true; use fresh observed identity/revision values.
Required arguments. action_id
Optional arguments. confirm, cooperative
Registered argument contract.
action_id— required; stringconfirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_invoke_action",
"arguments": {
"action_id": "action-id-from-grid-list-actions",
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The bridge's successful action object, normally carrying ok: true and host action/result fields; it is not a project-delivery response.
Recovery. After an action may have run, read the affected state and list actions again; do not retry an ambiguous action because actions can open dialogs or change global state.
Guarded patch session tools (6)
grid_analyze
Purpose. Read the selected Grid topology and report exact edges, signal/control lanes, upstream reachability, disconnected outputs, cycles and uncertainty.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. None. Optional arguments. None.
Registered argument contract.
- This registration declares no named arguments; the request is an empty object.
- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_analyze",
"arguments": {}
}
Representative response shape (illustrative, not observed evidence). An object describing graph topology, edges/lanes, reachability, disconnected outputs, cycles, and uncertainty.
Recovery. If the graph is unavailable, restore bridge capability and analyze again; topology reachability is not evidence that a patch sounds correct.
grid_patch_start
Purpose. Preview a bounded additive Grid recipe. Nodes use explicit aliases, live package IDs or existing instance IDs, coordinates, native parameter values, and exact symbolic port names; this never mutates the graph.
Authority / capability. Process-local preview or snapshot state only; this call does not apply a Bitwig parameter change.
Required arguments. nodes
Optional arguments. connections, protected_routes, controls, musical_intent, feedback_review
Registered argument contract.
nodes— required; array; min items:1- Items: object
- Object members (additional properties rejected; required:
alias):alias— required; stringpackage_id— optional; stringcoordinates— optional; object- Object members (additional properties rejected; required:
x,y):x— required; integery— required; integer
- Object members (additional properties rejected; required:
existing_instance_id— optional; string or integerparameters— optional; one of: object; array- Alternatives (
oneOf):- Option 1: object
- Object members are not constrained by this registration.
- Option 2: array
- Items: object
- Object members (additional properties rejected; required:
parameter_id,value):parameter_id— required; stringvalue— required; any JSON value
- Object members (additional properties rejected; required:
- Items: object
- Option 1: object
- Alternatives (
- Object members (additional properties rejected; required:
- Items: object
connections— optional; array- Items: object
- Object members (additional properties rejected; required:
input,output,source,target):source— required; string or integeroutput— required; stringtarget— required; string or integerinput— required; string
- Object members (additional properties rejected; required:
- Items: object
protected_routes— optional; array- Items: object
- Object members (additional properties rejected; required:
input,output,source,target):source— required; string or integeroutput— required; stringtarget— required; string or integerinput— required; string
- Object members (additional properties rejected; required:
- Items: object
controls— optional; object or array- Items: any JSON value (items are not constrained by registration).
- Object members are not constrained by this registration.
musical_intent— optional; stringfeedback_review— optional; boolean or string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_patch_start",
"arguments": {
"nodes": [
{
"alias": "voice",
"package_id": "00000000-0000-4000-8000-000000000000",
"coordinates": {
"x": 0,
"y": 0
}
}
],
"connections": [],
"musical_intent": "One bounded voice; illustration only."
}
}
Representative response shape (illustrative, not observed evidence). A patch-session object with session_id, integer revision, status, graph identity/revision, bindings, next_action, completed, failure, preview, analysis, and verification scope.
Recovery. Fix the recipe using fresh catalog/graph identities, explicit coordinates, exact symbolic ports, and feedback_review for feedback; start a new reviewed session rather than replaying a rejected recipe.
grid_patch_status
Purpose. Read and verify a Grid patch session without mutation.
Authority / capability. Read-only; no confirmation or mutation authority is registered.
Required arguments. session_id
Optional arguments. None.
Registered argument contract.
session_id— required; string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_patch_status",
"arguments": {
"session_id": "patch-session-id-from-grid-patch-start"
}
}
Representative response shape (illustrative, not observed evidence). The current patch-session object with status, integer revision, graph identity/revision, bindings, next action, completed operations, failure/recovery state, and verification scope.
Recovery. If the session is frozen, stop it and re-read the selected Grid before starting a new patch; do not replay the frozen session's next action.
grid_patch_step
Purpose. Apply at most one reviewed, guarded Grid patch operation — including one staged control destination — and read back the actual graph. Confirm or explicitly authorized cooperative work is required.
Authority / capability. Guarded mutation path: pass confirm: true or explicitly authorized cooperative: true; use the current integer session revision.
Required arguments. session_id, revision
Optional arguments. confirm, cooperative
Registered argument contract.
session_id— required; stringrevision— required; integer; minimum:1confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_patch_step",
"arguments": {
"session_id": "patch-session-id-from-grid-patch-start",
"revision": 1,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The updated patch-session object plus a step detail and fresh graph/read-back fields; a frozen session includes a structured failure and recovery message.
Recovery. On a stale revision, failed read-back, or frozen session, call grid_patch_status, stop for review, and never replay the same step against a new revision without a new decision.
grid_patch_control
Purpose. Preview and stage a bounded named control change against live native parameter metadata. This call never writes; an authorized grid_patch_step applies one staged destination.
Authority / capability. Process-local preview or snapshot state only; this call does not apply a Bitwig parameter change.
Required arguments. session_id, revision, control, value
Optional arguments. None.
Registered argument contract.
session_id— required; stringrevision— required; integer; minimum:1control— required; stringvalue— required; number- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_patch_control",
"arguments": {
"session_id": "patch-session-id-from-grid-patch-start",
"revision": 1,
"control": "control-name-from-completed-session",
"value": 0.5
}
}
Representative response shape (illustrative, not observed evidence). The updated patch-session object plus a staged control preview; this call does not write the control to Bitwig.
Recovery. Use only a completed parameter-only session and the current integer session revision; if rejected, read status and keep the staged control unapplied.
grid_patch_restore
Purpose. Preview exact original values for a completed parameter-only patch. A separately authorized call may restore one parameter at a time.
Authority / capability. Guarded mutation path: pass confirm: true or explicitly authorized cooperative: true; use the current integer session revision.
Required arguments. session_id, revision
Optional arguments. confirm, cooperative
Registered argument contract.
session_id— required; stringrevision— required; integer; minimum:1confirm— optional; booleancooperative— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_patch_restore",
"arguments": {
"session_id": "patch-session-id-from-grid-patch-start",
"revision": 1,
"confirm": true
}
}
Representative response shape (illustrative, not observed evidence). The updated patch-session object plus a scoped restore preview or restore-step detail; restoration is one parameter at a time.
Recovery. Use only the completed parameter-only session's recorded values; on rejection or stale revision, read status and preview again rather than restoring blindly.
Offline composition tools (5)
grid_track_plan
Purpose. Create an offline, bounded composition plan from a brief; this does not mutate Bitwig.
Authority / capability. Offline/process-local operation; it does not connect to or mutate the Bitwig project.
Required arguments. brief
Optional arguments. style, tempo_bpm, key, scale, meter, bars, duration_seconds, phrase_bars, density, motion, seed, negative_constraints, sections, intent, locks, source_policy
Registered argument contract.
brief— required; string; min length:1; max length:8192style— optional; stringtempo_bpm— optional; number; minimum:40; maximum:220key— optional; stringscale— optional; stringmeter— optional; string or object- Object members are not constrained by this registration.
bars— optional; integer; minimum:1; maximum:2048duration_seconds— optional; number; maximum:1800.0; greater than:0phrase_bars— optional; integer; enum:2,4,8,16,32density— optional; number; minimum:0; maximum:1motion— optional; number; minimum:0; maximum:1seed— optional; integer; minimum:0; maximum:4294967295negative_constraints— optional; array; max items:32- Items: string
sections— optional; array; max items:128- Items: any JSON value (items are not constrained by registration).
intent— optional; object- Object members are not constrained by this registration.
locks— optional; array- Items: any JSON value (items are not constrained by registration).
source_policy— optional; object- Object members are not constrained by this registration.
- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_track_plan",
"arguments": {
"brief": "A restrained pulse with one moving voice.",
"tempo_bpm": 120,
"bars": 8,
"seed": 7
}
}
Representative response shape (illustrative, not observed evidence). An offline plan object containing normalized controls, sections/phrases/roles, duration metadata, and a deterministic plan_digest; it does not touch Bitwig.
Recovery. Correct the brief or bounded controls named by the validation error; this offline plan cannot be repaired by connecting to Bitwig.
grid_track_start
Purpose. Start a process-local reviewed composition session from an offline plan.
Authority / capability. Offline/process-local operation; it does not connect to or mutate the Bitwig project.
Required arguments. brief
Optional arguments. style, tempo_bpm, key, scale, meter, bars, duration_seconds, phrase_bars, density, motion, seed, negative_constraints, sections, intent, locks, source_policy
Registered argument contract.
brief— required; string; min length:1; max length:8192style— optional; stringtempo_bpm— optional; number; minimum:40; maximum:220key— optional; stringscale— optional; stringmeter— optional; string or object- Object members are not constrained by this registration.
bars— optional; integer; minimum:1; maximum:2048duration_seconds— optional; number; maximum:1800.0; greater than:0phrase_bars— optional; integer; enum:2,4,8,16,32density— optional; number; minimum:0; maximum:1motion— optional; number; minimum:0; maximum:1seed— optional; integer; minimum:0; maximum:4294967295negative_constraints— optional; array; max items:32- Items: string
sections— optional; array; max items:128- Items: any JSON value (items are not constrained by registration).
intent— optional; object- Object members are not constrained by this registration.
locks— optional; array- Items: any JSON value (items are not constrained by registration).
source_policy— optional; object- Object members are not constrained by this registration.
- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_track_start",
"arguments": {
"brief": "A restrained pulse with one moving voice.",
"tempo_bpm": 120,
"bars": 8,
"seed": 7
}
}
Representative response shape (illustrative, not observed evidence). A process-local composition-session object with session_id, 64-hex revision, revision_number, plan, exports, and mutates_project: false.
Recovery. If the process-local session limit is reached or inputs are rejected, adjust the bounded plan and retry after reviewing existing sessions; no Bitwig state is changed.
grid_track_revise
Purpose. Apply a scoped role, section, phrase, or arrangement revision to the current reviewed score.
Authority / capability. Offline/process-local operation; it does not connect to or mutate the Bitwig project.
Required arguments. session_id, revision, scope, changes
Optional arguments. target, regenerate
Registered argument contract.
session_id— required; stringrevision— required; string; pattern:^[0-9a-f]{64}$scope— required; string; enum:"role","section","phrase","arrangement"target— optional; string or object- Alternatives (
anyOf):- Option 1: string
- Option 2: object
- Object members are not constrained by this registration.
- Alternatives (
changes— required; object- Object members are not constrained by this registration.
regenerate— optional; boolean- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_track_revise",
"arguments": {
"session_id": "song-session-id-from-grid-track-start",
"revision": "0000000000000000000000000000000000000000000000000000000000000000",
"scope": "arrangement",
"changes": {
"density": 0.55
}
}
}
Representative response shape (illustrative, not observed evidence). The updated composition-session object plus a diff describing scope/target, regeneration, changed note IDs, and preservation; prior exports become stale.
Recovery. On a stale 64-hex revision or lock/target conflict, call grid_track_status, use the current revision and exact target, and keep changes flat.
grid_track_status
Purpose. Read the current reviewed MIDI score, revision, and export authority without mutating Bitwig.
Authority / capability. Offline/process-local operation; it does not connect to or mutate the Bitwig project.
Required arguments. session_id
Optional arguments. None.
Registered argument contract.
session_id— required; string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_track_status",
"arguments": {
"session_id": "song-session-id-from-grid-track-start"
}
}
Representative response shape (illustrative, not observed evidence). The current composition-session object with session/revision authority, plan, export records, and mutates_project: false.
Recovery. If the process-local session ID is unknown, start a new composition session; a status response is the authority for the current revision.
grid_track_export
Purpose. Write a real type-1 Standard MIDI File and digest-bound manifest into a unique private directory.
Authority / capability. Offline local filesystem write only; no Bitwig project mutation or native instrument assignment.
Required arguments. session_id, revision
Optional arguments. output_dir
Registered argument contract.
session_id— required; stringrevision— required; string; pattern:^[0-9a-f]{64}$output_dir— optional; string- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_track_export",
"arguments": {
"session_id": "song-session-id-from-grid-track-start",
"revision": "0000000000000000000000000000000000000000000000000000000000000000",
"output_dir": "./illustrative-midi-output"
}
}
Representative response shape (illustrative, not observed evidence). An object with ok, artifact schema/digest, byte count, MIDI format, session/revision, output paths, duration metadata, note-track count, and mutates_project: false.
Recovery. On a stale revision, call grid_track_status and export only the current review; if the output directory fails, fix local permissions and verify the returned manifest before using the artifact.
Offline audio tools (2)
grid_audio_analyze
Purpose. Probe, decode, and measure a bounded local mono/stereo audio file. This is technical evidence only; it does not capture audio or make a listening-quality judgment.
Authority / capability. Offline local-file analysis; it never uses Bitwig controller state or performs live capture.
Required arguments. path
Optional arguments. max_duration_seconds, max_size_bytes, max_channels
Registered argument contract.
path— required; string; min length:1max_duration_seconds— optional; number; maximum:1800.0; greater than:0max_size_bytes— optional; integer; maximum:536870912; greater than:0max_channels— optional; integer; minimum:1; maximum:2- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_audio_analyze",
"arguments": {
"path": "./illustrative-input.wav",
"max_duration_seconds": 30.0,
"max_channels": 2
}
}
Representative response shape (illustrative, not observed evidence). An object with ok, source path/size/SHA-256, sample/channel/duration metrics, RMS/peak/silence/clipping and envelope/tail/low-band/channel metrics, plus technical-pass scope.
Recovery. Use a regular local file within the duration, size, and channel limits; if probing/decoding fails, fix the file or ffprobe/ffmpeg availability and do not claim a listening judgment.
grid_audio_compare
Purpose. Measure two bounded local audio files, report observed technical differences, and optionally render unique WAVs using attenuation-only whole-file RMS matching. This is not LUFS normalization or perceptual quality approval.
Authority / capability. Offline local-file analysis; it never uses Bitwig controller state or performs live capture.
Required arguments. first_path, second_path
Optional arguments. output_dir, max_duration_seconds, max_size_bytes, max_channels
Registered argument contract.
first_path— required; string; min length:1second_path— required; string; min length:1output_dir— optional; string; min length:1max_duration_seconds— optional; number; maximum:1800.0; greater than:0max_size_bytes— optional; integer; maximum:536870912; greater than:0max_channels— optional; integer; minimum:1; maximum:2- Top-level additional properties: rejected by registration.
Example request. Illustrative only. Replace identity, revision, path, and session values with your current observations; see Calling and safety.
{
"name": "grid_audio_compare",
"arguments": {
"first_path": "./illustrative-first.wav",
"second_path": "./illustrative-second.wav",
"max_duration_seconds": 30.0
}
}
Representative response shape (illustrative, not observed evidence). An object with ok, first and second analysis objects, same_digest, differences, rms_match, artifacts, and optional output_dir; matching is attenuation-only and verified.
Recovery. Use two regular bounded files and a writable output directory only when rendering is requested; if a rendered RMS verification fails, discard the output and do not accept it as matched.
Explicitly unavailable capabilities
The registered surface does not implement native arranger note/clip/automation editing, MIDI import or voice realization, live capture, audio rendering/export, or project save/new/load/delivery. Do not replace an unavailable capability with UI automation, a guessed private call, a fake success response, or an offline artifact claim.