Skip to main content
Glama
thenavidm

Wistia MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Update Engagement Customizations

update_engagement_customizations
Destructive

Update a video's engagement customizations partially: only supplied fields change; set a field to null to delete it and revert to default.

Instructions

Applies a partial update to a video's engagement customizations. Only the fields supplied are changed; sending a field as null deletes it (reverting to the default).

Requires api token with one of the following permissions

Read, update & delete anything

Tokens with the "Act with a team member's permissions" permission (all:delegate_to_contact_permissions scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

Input Schema

NameRequiredDescriptionDefault
pluginNo
accountNoNamed private Wistia account; selects credentials, not a remote account ID.
confirmNoSet true only when the user asked for exactly this action.
payloadNoComplete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
media_idYesThe hashed ID of the video to be customized.
payload_fileNoRegular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv3.0.0
    • addedInput schema / $defs
      Added value: +{
+  "plugin": {
+    "description": "Container for engagement plugin configurations.",
+    "properties": {
+      "midrollLink-v1": {
+        "description": "Timed annotation links that appear over the video at specific times.",
+        "properties": {
+          "links": {
+            "description": "The set of annotation links.",
+            "items": {
+              "properties": {
+                "duration": {
+                  "description": "How long (in seconds) the link remains visible.",
+                  "type": "string"
+                },
+                "text": {
+                  "description": "The text of the annotation link.",
+                  "type": "string"
+                },
+                "time": {
+                  "description": "The time (in seconds) at which the link appears.",
+                  "type": "string"
+                },
+                "url": {
+                  "description": "The URL the annotation link points to.",
+                  "type": "string"
+                }
+              },
+              "type": "object",
+              "unevaluatedProperties": false
+            },
+            "type": "array"
+          },
+          "on": {
+            "description": "If set to true, the timed annotation links are enabled.",
+            "type": "boolean"
+          }
+        },
+        "type": "object",
+        "unevaluatedProperties": false
+      },
+      "postRoll-v1": {
+        "description": "Adds a Call To Action to your Video.",
+        "properties": {
+          "autoSize": {
+            "description": "If set to true, the post-roll will automatically adjust its size.",
+            "type": "boolean"
+          },
+          "conversionOpportunityKey": {
+            "description": "The key used for tracking conversion opportunities.",
+            "type": "string"
+          },
+          "ctaType": {
+            "description": "The type of call-to-action to be displayed. Typically set to \"text\". Other options are \"image\" which allows for \"altText\", and \"html\".",
+            "type": "string"
+          },
+          "link": {
+            "description": "The URL of the link to be displayed.",
+            "type": "string"
+          },
+          "on": {
+            "description": "If set to true, the post-roll is enabled.",
+            "type": "boolean"
+          },
+          "rewatch": {
+            "description": "If set to true, allows the video to be rewatched.",
+            "type": "boolean"
+          },
+          "style": {
+            "properties": {
+              "backgroundColor": {
+                "description": "The background color of the post-roll.",
+                "type": "string"
+              }
+            },
+            "type": "object",
+            "unevaluatedProperties": false
+          },
+          "text": {
+            "description": "The text to be displayed.",
+            "type": "string"
+          },
+          "time": {
+            "description": "The time when the post-roll should be displayed. Can be a string like \"end\" or a number representing seconds.",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              }
+            ],
+            "unevaluatedProperties": false
+          }
+        },
+        "type": "object",
+        "unevaluatedProperties": false
+      }
+    },
+    "type": "object",
+    "unevaluatedProperties": false
+  }
+}
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true for the specific user-requested write."New value: +"Set true only when the user asked for exactly this action."
    • addedInput schema / properties / payload / properties / plugin / $ref
      Added value: +"#/$defs/plugin"
    • removedInput schema / properties / payload / properties / plugin / description
      Removed value: -"Container for engagement plugin configurations."
    • removedInput schema / properties / payload / properties / plugin / properties
      Removed value: -{
-  "midrollLink-v1": {
-    "description": "Timed annotation links that appear over the video at specific times.",
-    "properties": {
-      "links": {
-        "description": "The set of annotation links.",
-        "items": {
-          "properties": {
-            "duration": {
-              "description": "How long (in seconds) the link remains visible.",
-              "type": "string"
-            },
-            "text": {
-              "description": "The text of the annotation link.",
-              "type": "string"
-            },
-            "time": {
-              "description": "The time (in seconds) at which the link appears.",
-              "type": "string"
-            },
-            "url": {
-              "description": "The URL the annotation link points to.",
-              "type": "string"
-            }
-          },
-          "type": "object",
-          "unevaluatedProperties": false
-        },
-        "type": "array"
-      },
-      "on": {
-        "description": "If set to true, the timed annotation links are enabled.",
-        "type": "boolean"
-      }
-    },
-    "type": "object",
-    "unevaluatedProperties": false
-  },
-  "postRoll-v1": {
-    "description": "Adds a Call To Action to your Video.",
-    "properties": {
-      "autoSize": {
-        "description": "If set to true, the post-roll will automatically adjust its size.",
-        "type": "boolean"
-      },
-      "conversionOpportunityKey": {
-        "description": "The key used for tracking conversion opportunities.",
-        "type": "string"
-      },
-      "ctaType": {
-        "description": "The type of call-to-action to be displayed. Typically set to \"text\". Other options are \"image\" which allows for \"altText\", and \"html\".",
-        "type": "string"
-      },
-      "link": {
-        "description": "The URL of the link to be displayed.",
-        "type": "string"
-      },
-      "on": {
-        "description": "If set to true, the post-roll is enabled.",
-        "type": "boolean"
-      },
-      "rewatch": {
-        "description": "If set to true, allows the video to be rewatched.",
-        "type": "boolean"
-      },
-      "style": {
-        "properties": {
-          "backgroundColor": {
-            "description": "The background color of the post-roll.",
-            "type": "string"
-          }
-        },
-        "type": "object",
-        "unevaluatedProperties": false
-      },
-      "text": {
-        "description": "The text to be displayed.",
-        "type": "string"
-      },
-      "time": {
-        "description": "The time when the post-roll should be displayed. Can be a string like \"end\" or a number representing seconds.",
-        "oneOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "number"
-          }
-        ],
-        "unevaluatedProperties": false
-      }
-    },
-    "type": "object",
-    "unevaluatedProperties": false
-  }
-}
    • removedInput schema / properties / payload / properties / plugin / type
      Removed value: -"object"
    • removedInput schema / properties / payload / properties / plugin / unevaluatedProperties
      Removed value: -false
    • addedInput schema / properties / plugin / $ref
      Added value: +"#/$defs/plugin"
    • removedInput schema / properties / plugin / description
      Removed value: -"Container for engagement plugin configurations."
    • removedInput schema / properties / plugin / properties
      Removed value: -{
-  "midrollLink-v1": {
-    "description": "Timed annotation links that appear over the video at specific times.",
-    "properties": {
-      "links": {
-        "description": "The set of annotation links.",
-        "items": {
-          "properties": {
-            "duration": {
-              "description": "How long (in seconds) the link remains visible.",
-              "type": "string"
-            },
-            "text": {
-              "description": "The text of the annotation link.",
-              "type": "string"
-            },
-            "time": {
-              "description": "The time (in seconds) at which the link appears.",
-              "type": "string"
-            },
-            "url": {
-              "description": "The URL the annotation link points to.",
-              "type": "string"
-            }
-          },
-          "type": "object",
-          "unevaluatedProperties": false
-        },
-        "type": "array"
-      },
-      "on": {
-        "description": "If set to true, the timed annotation links are enabled.",
-        "type": "boolean"
-      }
-    },
-    "type": "object",
-    "unevaluatedProperties": false
-  },
-  "postRoll-v1": {
-    "description": "Adds a Call To Action to your Video.",
-    "properties": {
-      "autoSize": {
-        "description": "If set to true, the post-roll will automatically adjust its size.",
-        "type": "boolean"
-      },
-      "conversionOpportunityKey": {
-        "description": "The key used for tracking conversion opportunities.",
-        "type": "string"
-      },
-      "ctaType": {
-        "description": "The type of call-to-action to be displayed. Typically set to \"text\". Other options are \"image\" which allows for \"altText\", and \"html\".",
-        "type": "string"
-      },
-      "link": {
-        "description": "The URL of the link to be displayed.",
-        "type": "string"
-      },
-      "on": {
-        "description": "If set to true, the post-roll is enabled.",
-        "type": "boolean"
-      },
-      "rewatch": {
-        "description": "If set to true, allows the video to be rewatched.",
-        "type": "boolean"
-      },
-      "style": {
-        "properties": {
-          "backgroundColor": {
-            "description": "The background color of the post-roll.",
-            "type": "string"
-          }
-        },
-        "type": "object",
-        "unevaluatedProperties": false
-      },
-      "text": {
-        "description": "The text to be displayed.",
-        "type": "string"
-      },
-      "time": {
-        "description": "The time when the post-roll should be displayed. Can be a string like \"end\" or a number representing seconds.",
-        "oneOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "number"
-          }
-        ],
-        "unevaluatedProperties": false
-      }
-    },
-    "type": "object",
-    "unevaluatedProperties": false
-  }
-}
    • removedInput schema / properties / plugin / type
      Removed value: -"object"
    • removedInput schema / properties / plugin / unevaluatedProperties
      Removed value: -false
  2. First observedv2.0.0

TDQS

A3.9/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the partial-update contract (only supplied fields change; null deletes a field and reverts to default), the exact auth/permission requirements including delegated tokens, the confirm=true gate for mutations, and side-effect warnings (may share access, notify people, incur provider charges) that align with and enrich destructiveHint=true and openWorldHint=true.

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?

Front-loaded with the core partial-update behavior and the field-deletion rule in the first sentence, then prerequisites. The permissions section is somewhat heavy and formatted with headers/fences, but every block carries operational value.

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 destructive, non-idempotent mutation with nested plugin objects and no output schema, the description covers the mutation contract, auth, the confirm gate and side effects. It is only slightly short on routing guidance against the many sibling update_*_customizations tools.

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 coverage is 83%, so the schema already documents media_id, account, confirm, payload and payload_file. The description adds the meaningful null-deletion and partial-update semantics for the plugin/payload fields, but gives no guidance on mutually exclusive body flags vs payload vs payload_file beyond what the schema says.

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?

States a specific verb ('Applies a partial update') and resource ('engagement customizations'), plus the key semantic that only supplied fields change. It is distinguishable from siblings like get_engagement_customizations, but it never explicitly contrasts itself with the broader update_customizations or the other update_*_customizations tools, so an agent must infer the boundary.

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

Usage Guidelines3/5

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

Gives concrete prerequisites (required api token permission, the delegate_to_contact scope, confirm=true) but no statement of when to choose this tool over update_customizations or the other per-category update tools. Usage context is implied rather than specified.

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

Deploy Server

Other Tools