LiveReacting

Replace a playlist

livereacting_set_playlist

Destructive

Replace the entire contents of a video or audio playlist layer. The files you send become the whole playlist: anything already in it that you do not send again is removed, and playback restarts from the first item. There is no way to append with this tool. So to add, remove or reorder a video, first call livereacting_get_layer and page through every item until nextOffset is null, apply your change to that complete list, and send the complete list back. Sending only the new video deletes everything else. The response reports removedItemCount and warns whenever the playlist got shorter — check it before telling the customer the change worked. Writes are not merged. If two callers write the same playlist at once, the later write replaces the earlier one and both report success, so do not run parallel edits against one playlist. If the customer may be editing it in the LiveReacting Studio at the same moment, read the list again immediately before writing, and tell them not to edit while you work. Files must have finished importing and encoding. A playlist holds at most 600 items. This tool works on videoPlaylist and audioPlaylist layers only. adPlaceholder sets the video that plays during ad breaks (video playlists only; refused for an audio playlist). It is written together with the full playlist in the same call, so send the complete list with it; leave adPlaceholder out to keep the current one. This is NOT idempotent: sending the same list twice produces the same contents, but each call regenerates every playlistItemId and restarts playback. After a timeout, read the layer with livereacting_get_layer rather than calling again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>",
      "layerId": "<layerId>",
      "files": "<files>"
    },
    "name": "livereacting_set_playlist"
  }
}

Input Schema

Name	Required	Description
`loop`	No	Repeat the playlist forever. Refused while the layer auto-switches into another scene, unless the same call also sends autoSwitchToSceneId: null.
`files`	Yes	The COMPLETE playlist in play order. This replaces the current list. An empty array empties the playlist.
`volume`	No	Playback volume, 0 to 10.
`layerId`	Yes	Playlist layer id, from livereacting_get_scenes.
`projectId`	Yes	Project id, from livereacting_list_projects.
`adPlaceholder`	No	Video playlists only. The video that plays during ad breaks. Send fileId for one video or files for several. Every file must be a video that has finished importing and encoding. This replaces the whole current setting; null removes it. A new list or order starts again from the first video. Leave it out to keep the current setting.
`autoSwitchToSceneId`	No	What happens when the playlist ends. A scene id (from livereacting_get_scenes) makes it switch to that scene and turns loop off. null removes the switch, so send loop: true with it to make the playlist repeat instead. Leave it out to keep the current setting.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 4, 2026

addedInput schema / properties / adPlaceholder

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "enabled": {
+          "description": "true plays a placeholder video during every ad break; false turns it off.",
+          "type": "boolean"
+        },
+        "fileId": {
+          "description": "One placeholder video, from livereacting_list_media. Ignored when files is sent.",
+          "pattern": "^[a-fA-F0-9]{24}$",
+          "type": "string"
+        },
+        "files": {
+          "description": "Several placeholder videos, at most 40, each video once. One video plays per ad break and loops to fill it. When both files and fileId are sent, files wins.",
+          "items": {
+            "properties": {
+              "fileId": {
+                "pattern": "^[a-fA-F0-9]{24}$",
+                "type": "string"
+              }
+            },
+            "required": [
+              "fileId"
+            ],
+            "type": "object"
+          },
+          "maxItems": 40,
+          "type": "array"
+        },
+        "shuffle": {
+          "description": "false (default) plays the videos in list order. true plays every video once per round, in a new random order each round. It has an effect only with 3 or more videos.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Video playlists only. The video that plays during ad breaks. Send fileId for one video or files for several. Every file must be a video that has finished importing and encoding. This replaces the whole current setting; null removes it. A new list or order starts again from the first video. Leave it out to keep the current setting."
+}

First observedOct 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already flag destructive and non-idempotent, but the description adds context the annotations cannot: the lost-update race where both writers report success, the 600-item cap, the playlistItemId regeneration and playback restart on every call, the encoding prerequisite, and the removedItemCount warning in the response. This is unusually rich behavioral disclosure beyond structured fields.

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

Conciseness4/5

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

Dense and front-loaded, with the destructive replacement rule first and operational warnings after. It runs long and 'Sending only the new video deletes everything else' restates the opening sentence, though as an explicit anti-pattern it still earns some of its space.

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

Completeness5/5

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

For a destructive, non-idempotent, concurrent-write-prone mutation with no output schema, it covers every gap an agent needs: pre-read procedure, response signal to check, race conditions, Studio co-editing, size limit, and post-timeout recovery. Nothing essential is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: files must be the complete list (an omission deletes), adPlaceholder is written atomically with the playlist and must be left out to preserve the current setting, and it is refused for audio layers. It stops short of covering loop/volume/autoSwitchToSceneId interactions, which the schema handles.

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

Purpose5/5

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

Opens with a specific verb and resource ('Replace the entire contents of a video or audio playlist layer') and immediately defines the replacement semantics. It scopes the tool to videoPlaylist and audioPlaylist layers, which separates it from siblings like create_scene_with_playlist and get_layer.

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

Usage Guidelines5/5

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

States explicitly that there is no append mode, prescribes the read-modify-write alternative (livereacting_get_layer, page until nextOffset is null), warns against parallel edits, and says what to do after a timeout instead of retrying. When-to-use and when-not-to-use are both spelled out.

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

All LiveReacting tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.