Wistia MCP Server

Update Media

update_media

Destructive

Change a Wistia media item’s name, description, tags, custom metadata, or still image using its hashed ID.

Instructions

Updates the attributes on a media.

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.

An expiring access token created with the all:delegate_to_contact_permissions scope and an authorization granting the update permission on this media can also be used. Requires confirm=true for the requested mutation. May share access, notify people or incur provider charges.

Input Schema

Name	Required	Description
`name`	No	The media’s new name.
`tags`	No
`account`	No	Named private Wistia account; selects credentials, not a remote account ID.
`confirm`	No	Set true only when the user asked for exactly this action.
`payload`	No	Complete JSON request body instead of body flags. Supports current nested customization, caption and nullable values.
`description`	No	A new description for this media. Accepts plain text or markdown.
`payload_file`	No	Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload.
`custom_metadata`	No
`media_hashed_id`	Yes	The hashed ID of the media.
`new_still_media_id`	No	The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv3.0.0Oct 7, 2026

addedInput schema / $defs

Added value: +{
+  "custom_metadata": {
+    "additionalProperties": true,
+    "description": "Custom metadata field values to set, keyed by field key. Values take the\nsame shapes as the Set Custom Metadata Field Value endpoint; a null value\nclears that field and omitted fields are untouched. Requires the custom\nmetadata feature on the account.\n",
+    "type": "object",
+    "unevaluatedProperties": false
+  },
+  "tags": {
+    "description": "An array of tag names to apply to the media. This replaces any existing tags. To add tags without replacing existing tags, use bulk-tag-media.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+}

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 / custom_metadata / $ref
```
Added value: +"#/$defs/custom_metadata"
```
removedInput schema / properties / custom_metadata / additionalProperties
```
Removed value: -true
```

removedInput schema / properties / custom_metadata / description

Removed value: -"Custom metadata field values to set, keyed by field key. Values take the\nsame shapes as the Set Custom Metadata Field Value endpoint; a null value\nclears that field and omitted fields are untouched. Requires the custom\nmetadata feature on the account.\n"

removedInput schema / properties / custom_metadata / type
```
Removed value: -"object"
```
removedInput schema / properties / custom_metadata / unevaluatedProperties
```
Removed value: -false
```
addedInput schema / properties / payload / properties / custom_metadata / $ref
```
Added value: +"#/$defs/custom_metadata"
```
removedInput schema / properties / payload / properties / custom_metadata / additionalProperties
```
Removed value: -true
```

removedInput schema / properties / payload / properties / custom_metadata / description

Removed value: -"Custom metadata field values to set, keyed by field key. Values take the\nsame shapes as the Set Custom Metadata Field Value endpoint; a null value\nclears that field and omitted fields are untouched. Requires the custom\nmetadata feature on the account.\n"

removedInput schema / properties / payload / properties / custom_metadata / type
```
Removed value: -"object"
```
removedInput schema / properties / payload / properties / custom_metadata / unevaluatedProperties
```
Removed value: -false
```
addedInput schema / properties / payload / properties / tags / $ref
```
Added value: +"#/$defs/tags"
```

removedInput schema / properties / payload / properties / tags / description

Removed value: -"An array of tag names to apply to the media. This replaces any existing tags. To add tags without replacing existing tags, use bulk-tag-media."

removedInput schema / properties / payload / properties / tags / items
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / payload / properties / tags / type
```
Removed value: -"array"
```
addedInput schema / properties / tags / $ref
```
Added value: +"#/$defs/tags"
```

removedInput schema / properties / tags / description

Removed value: -"An array of tag names to apply to the media. This replaces any existing tags. To add tags without replacing existing tags, use bulk-tag-media."

removedInput schema / properties / tags / items
```
Removed value: -{
-  "type": "string"
-}
```
removedInput schema / properties / tags / type
```
Removed value: -"array"
```

First observedv2.0.0Oct 2, 2026

TDQS

B3.4/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds substantial context beyond them: required permissions/scopes, delegated-token behavior, the confirm=true gate, and the warning that the mutation "may share access, notify people or incur provider charges." It stops short of explaining what specifically gets overwritten (e.g., that tags replace existing ones), which the schema carries instead.

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

Conciseness3/5

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

The purpose sentence is properly front-loaded, but the bulk of the text is boilerplate permission prose repeated in full, including a long explanation of delegated and expiring tokens. Much of that is only marginally relevant to an agent deciding or invoking, making the definition top-heavy.

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 10-parameter mutation with no output schema, the description covers the things annotations cannot: authorization requirements, the confirm gate, and side-effect risk. It leaves partial-vs-full update semantics and sibling relationships to the schema, but is otherwise sufficient to call the tool correctly.

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 80% and the schema already documents each field (name, description, tags, custom_metadata, payload, media_hashed_id). The description adds no parameter-level detail whatsoever, so it merely meets the baseline where the schema does the work.

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 clear verb and resource ("Updates the attributes on a media") and names the required identifier. However, "attributes" is generic and the description never distinguishes this tool from siblings like bulk_tag, move_media, or swap_media that also mutate a media.

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

Usage Guidelines2/5

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

The description gives no when-to-use guidance and no comparison to alternatives (e.g., bulk-tag-media for additive tagging, move_media for folder changes). The only routing hint in the whole definition lives in the schema's tags description, not the prose, so the description itself provides no selection help.

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

Deploy Server