Skip to main content
Glama

Soclo

by app.soclo
OverviewDiscussionsAdmin

Store a plan with chosen sources

soclo_host_plan_import_selected
Idempotent

Store a host-authored plan with selected Library/Brand Kit image ids and saved actor ids (using exact current versions) and the guides and catalogueVersion from soclo_host_plan_prepare. Reuse each selected reference id in scene.referenceIds where needed. brandVisualMode sets the Brand Kit visual rule: "use" (default) inherits Brand Kit visuals; "exclude" keeps brand facts in prose while refusing Brand Kit imagery (ordinary Library photos remain selectable). A first import requires a "render" design on every scene on-screen-text cue. Spends no credits and makes no AI, quote, reservation or render call. Refused fields are named in "details"; on an uncertain reply, reconcile under the same ids with soclo_host_plan_recover. Soclo revalidates owner, actor and voice bindings before import and before paid work without substituting defaults.

Input Schema

NameRequiredDescriptionDefault
planYes
guidesYesBy default carry the exact guides returned by prepare into import/import_selected. Soclo selected them from the brief; keep their revision and digest unchanged. An unavailable selector may return [], allowing the host to proceed.
projectIdYes
selectedInputYes
brandVisualModeNoFor import_selected only: the owner’s explicit visual Brand Kit choice. "use" (default) inherits Brand Kit visuals; "exclude" keeps every brand fact in the plan’s prose while refusing automatic Brand Kit imagery — an explicitly selected Brand Kit picture is refused under exclude, and ordinary Library photos stay selectable. Part of the stored plan identity: changing it on a replay is a conflict.
clientRequestIdYes
catalogueVersionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / clientRequestId / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / projectId / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / actors / items / properties / actorVersion / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / actors / items / properties / id / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / references / items / properties / id / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / voices / items / properties / actorVoice / properties / actorId / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / voices / items / properties / actorVoice / properties / actorVersion / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / voices / items / properties / actorVoice / properties / bindingVersion / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    • changedInput schema / properties / selectedInput / properties / voices / items / properties / actorVoice / properties / ownerId / pattern
      Previous value: -"^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"New value: +"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
  2. Changed5 schema fields changed
    • changedInput schema / properties / brandVisualMode / description
      Previous value: -"For import_selected only: the owner’s explicit visual Brand Kit choice. \"use\" (default) inherits Brand Kit visuals; \"exclude\" keeps every brand fact in the plan’s prose while refusing automatic Brand Kit imagery — MAIN refuses an explicitly selected Brand Kit row under exclude, and ordinary Library photos stay selectable. Part of the stored plan identity: changing it on a replay is a conflict."New value: +"For import_selected only: the owner’s explicit visual Brand Kit choice. \"use\" (default) inherits Brand Kit visuals; \"exclude\" keeps every brand fact in the plan’s prose while refusing automatic Brand Kit imagery — an explicitly selected Brand Kit picture is refused under exclude, and ordinary Library photos stay selectable. Part of the stored plan identity: changing it on a replay is a conflict."
    • changedInput schema / properties / guides / description
      Previous value: -"By default carry the exact guides returned by prepare into import/import_selected. Jev selected them from the brief; keep their certified revision and whole-entry digest. An unavailable selector may return [], allowing the host to proceed."New value: +"By default carry the exact guides returned by prepare into import/import_selected. Soclo selected them from the brief; keep their revision and digest unchanged. An unavailable selector may return [], allowing the host to proceed."
    • changedInput schema / properties / selectedInput / properties / actors / items / properties / referenceIds / description
      Previous value: -"Empty; MAIN resolves actor images itself."New value: +"Empty; Soclo finds the actor’s own photos itself."
    • changedInput schema / properties / selectedInput / properties / references / items / properties / mediaVersion / description
      Previous value: -"Exact current asset updated_at; MAIN checks version and reviewed evidence."New value: +"Exact current asset updated_at; Soclo checks it is still the current version."
    • changedInput schema / properties / selectedInput / properties / voices / description
      Previous value: -"Exact Soclo-hosted selection from soclo_hosted_voices_autoload after the owner hears its private audition and transcript. MAIN revalidates the original owner, actor and binding before new work."New value: +"Exact Soclo-hosted selection from soclo_hosted_voices_autoload after the owner hears its private audition and transcript. Soclo checks the owner, actor and voice again before new work."
  3. Changed2 schema fields changed
    • addedInput schema / definitions
      Added value: +{
+  "s1": {
+    "additionalProperties": false,
+    "properties": {
+      "basis": {
+        "const": "planned-scene",
+        "type": "string"
+      },
+      "fromSeconds": {
+        "description": "Scene-relative start, non-negative.",
+        "type": "number"
+      },
+      "sceneSeconds": {
+        "description": "Must equal the scene’s own seconds.",
+        "type": "number"
+      },
+      "toSeconds": {
+        "description": "Scene-relative end, later than fromSeconds and not past sceneSeconds.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "basis",
+      "sceneSeconds",
+      "fromSeconds",
+      "toSeconds"
+    ],
+    "type": "object"
+  }
+}
    • changedInput schema / properties / plan / properties / scenes / items / properties / onScreenText / items / properties / render / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "placement": {
-        "description": "Where and how the model should show the text in the generated shot.",
-        "type": "string"
-      },
-      "timing": {
-        "additionalProperties": false,
-        "properties": {
-          "basis": {
-            "const": "planned-scene",
-            "type": "string"
-          },
-          "fromSeconds": {
-            "description": "Scene-relative start, non-negative.",
-            "type": "number"
-          },
-          "sceneSeconds": {
-            "description": "Must equal the scene’s own seconds.",
-            "type": "number"
-          },
-          "toSeconds": {
-            "description": "Scene-relative end, later than fromSeconds and not past sceneSeconds.",
-            "type": "number"
-          }
-        },
-        "required": [
-          "basis",
-          "sceneSeconds",
-          "fromSeconds",
-          "toSeconds"
-        ],
-        "type": "object"
-      },
-      "version": {
-        "const": "model-text.1",
-        "type": "string"
-      }
-    },
-    "required": [
-      "version",
-      "timing",
-      "placement"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "layout": {
-        "additionalProperties": false,
-        "properties": {
-          "baselineYN": {
-            "type": "number"
-          },
-          "centerXN": {
-            "type": "number"
-          },
-          "color": {
-            "description": "Six-digit #RRGGBB.",
-            "type": "string"
-          },
-          "fontSizeHeightN": {
-            "type": "number"
-          }
-        },
-        "required": [
-          "centerXN",
-          "baselineYN",
-          "fontSizeHeightN",
-          "color"
-        ],
-        "type": "object"
-      },
-      "motion": {
-        "oneOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "kind": {
-                "const": "hold",
-                "type": "string"
-              }
-            },
-            "required": [
-              "kind"
-            ],
-            "type": "object"
-          },
-          {
-            "additionalProperties": false,
-            "properties": {
-              "completeAtSeconds": {
-                "type": "number"
-              },
-              "kind": {
-                "const": "word-reveal",
-                "type": "string"
-              }
-            },
-            "required": [
-              "kind",
-              "completeAtSeconds"
-            ],
-            "type": "object"
-          },
-          {
-            "additionalProperties": false,
-            "properties": {
-              "kind": {
-                "const": "pop",
-                "type": "string"
-              },
-              "peakAfterSeconds": {
-                "type": "number"
-              },
-              "peakScale": {
-                "type": "number"
-              },
-              "revealAtSeconds": {
-                "type": "number"
-              },
-              "settleAfterSeconds": {
-                "type": "number"
-              },
-              "startScale": {
-                "type": "number"
-              },
-              "target": {
-                "enum": [
-                  "whole-cue",
-                  "last-word"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "kind",
-              "target",
-              "revealAtSeconds",
-              "peakAfterSeconds",
-              "settleAfterSeconds",
-              "startScale",
-              "peakScale"
-            ],
-            "type": "object"
-          }
-        ]
-      },
-      "timing": {
-        "additionalProperties": false,
-        "properties": {
-          "basis": {
-            "const": "planned-scene",
-            "type": "string"
-          },
-          "fromSeconds": {
-            "description": "Scene-relative start, non-negative.",
-            "type": "number"
-          },
-          "sceneSeconds": {
-            "description": "Must equal the scene’s own seconds.",
-            "type": "number"
-          },
-          "toSeconds": {
-            "description": "Scene-relative end, later than fromSeconds and not past sceneSeconds.",
-            "type": "number"
-          }
-        },
-        "required": [
-          "basis",
-          "sceneSeconds",
-          "fromSeconds",
-          "toSeconds"
-        ],
-        "type": "object"
-      },
-      "version": {
-        "const": "caption-design.1",
-        "type": "string"
-      }
-    },
-    "required": [
-      "version",
-      "timing",
-      "layout",
-      "motion"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "placement": {
+        "description": "Where and how the model should show the text in the generated shot.",
+        "type": "string"
+      },
+      "timing": {
+        "$ref": "#/definitions/s1"
+      },
+      "version": {
+        "const": "model-text.1",
+        "type": "string"
+      }
+    },
+    "required": [
+      "version",
+      "timing",
+      "placement"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "layout": {
+        "additionalProperties": false,
+        "properties": {
+          "baselineYN": {
+            "type": "number"
+          },
+          "centerXN": {
+            "type": "number"
+          },
+          "color": {
+            "description": "Six-digit #RRGGBB.",
+            "type": "string"
+          },
+          "fontSizeHeightN": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "centerXN",
+          "baselineYN",
+          "fontSizeHeightN",
+          "color"
+        ],
+        "type": "object"
+      },
+      "motion": {
+        "oneOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "const": "hold",
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "completeAtSeconds": {
+                "type": "number"
+              },
+              "kind": {
+                "const": "word-reveal",
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "completeAtSeconds"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "const": "pop",
+                "type": "string"
+              },
+              "peakAfterSeconds": {
+                "type": "number"
+              },
+              "peakScale": {
+                "type": "number"
+              },
+              "revealAtSeconds": {
+                "type": "number"
+              },
+              "settleAfterSeconds": {
+                "type": "number"
+              },
+              "startScale": {
+                "type": "number"
+              },
+              "target": {
+                "enum": [
+                  "whole-cue",
+                  "last-word"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "target",
+              "revealAtSeconds",
+              "peakAfterSeconds",
+              "settleAfterSeconds",
+              "startScale",
+              "peakScale"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "timing": {
+        "$ref": "#/definitions/s1"
+      },
+      "version": {
+        "const": "caption-design.1",
+        "type": "string"
+      }
+    },
+    "required": [
+      "version",
+      "timing",
+      "layout",
+      "motion"
+    ],
+    "type": "object"
+  }
+]
  4. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the annotations, the description discloses that the call spends no credits and makes no AI, quote, reservation or render call — a material and non-obvious behavior. It explains refusal semantics ('refused fields are named in "details"'), the reconciliation path under the same ids, and that Soclo revalidates owner, actor and voice bindings before import without substituting defaults. This adds substantial value over the readOnly/idempotent/destructive hints alone.

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?

The core identity is front-loaded and nearly every sentence carries operational information (cost, first-import constraint, error path, binding revalidation). It is a dense single block with no wasted sentences, though its length and run-on phrasing make it harder to scan than it needs to be.

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

Completeness4/5

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

For a complex, deeply nested, no-output-schema tool, the description covers the important behavioral context: no credit spend, no generation calls, the first-import render requirement, brand visual mode semantics, and the recover path on uncertainty. Missing pieces are what a successful response returns and the role of clientRequestId in idempotent replay, which would round out an otherwise strong definition.

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

Parameters3/5

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

Schema description coverage is only 29% across a large nested schema, so the description must compensate. It does add real meaning for brandVisualMode (use vs exclude, and that changing it on replay is a conflict), for reusing reference ids, and for sourcing guides/catalogueVersion. But it says nothing about selectedInput, projectId, clientRequestId, or the plan's required shape, leaving most of the parameter surface to the schema.

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

Purpose4/5

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

The description states a specific verb and resource ('Store a host-authored plan') and names the concrete ingredients: selected Library/Brand Kit image ids, saved actor ids with exact current versions, and the guides/catalogueVersion from soclo_host_plan_prepare. It is clear what the tool does, but it never explicitly contrasts with the sibling soclo_host_plan_import, so differentiation between the two import tools is only implied.

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

Usage Guidelines4/5

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

It gives concrete usage context: carry guides and catalogueVersion from soclo_host_plan_prepare, reuse selected reference ids in scene.referenceIds, and require a 'render' design on every scene on-screen-text cue for a first import. It also routes failures to soclo_host_plan_recover when a reply is uncertain. It stops short of stating when to prefer soclo_host_plan_import or soclo_host_plan_edit instead.

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

All Soclo toolsInspect
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.

Resources