mateai-youtube

Overview Schema Source Related Servers Discussions Admin

yt_update_video

Idempotent

Updates an existing YouTube video's metadata, visibility, schedule, or custom thumbnail while preserving any fields you omit, so partial edits do not clear current settings.

Instructions

Perform a partial, idempotent update on an existing YouTube video's metadata, visibility, schedule, or custom thumbnail in YouTube Studio via YouTube Data API v3 (videos.list + videos.update, costs ~51 quota units). Requires channel-owner OAuth2. Fetches current snippet/status first so omitted parameters (title, description, tags, privacy_status, publish_at) are preserved unchanged rather than cleared. Setting publish_at automatically forces privacy_status='private' as required by YouTube's scheduling API. Returns {videoId, studioUrl, updatedFields}.

Input Schema

Name	Required	Description
`tags`	No	Replacement list of YouTube SEO keyword tags. Leave omitted to keep existing tags.
`title`	No	New video title (1–100 characters). Leave omitted to keep existing title.
`video_id`	Yes	11-character YouTube video ID to update.
`publish_at`	No	Future ISO 8601 timestamp with timezone offset to schedule publication (e.g. '2026-11-05T17:00:00+01:00'). Forces privacy_status='private'.
`description`	No	New video description (up to 5,000 characters). Leave omitted to keep existing description.
`privacy_status`	No	Updated visibility status. Ignored and forced to 'private' if publish_at is provided.
`thumbnail_path`	No	Optional absolute local filesystem path to a readable PNG/JPG image (<=2MB) to upload via thumbnails.set.

Output Schema

Name	Required	Description	Default
`videoId`	Yes
`studioUrl`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.2.0Nov 3, 2026

changedInput schema / properties / description / description

Previous value: -"New video description (up to 5000 characters)."New value: +"New video description (up to 5,000 characters). Leave omitted to keep existing description."

addedInput schema / properties / description / maxLength
```
Added value: +5000
```

changedInput schema / properties / privacy_status / description

Previous value: -"Updated visibility status in YouTube Studio."New value: +"Updated visibility status. Ignored and forced to 'private' if publish_at is provided."

changedInput schema / properties / publish_at / description

Previous value: -"ISO 8601 schedule time (e.g. '2026-11-05T17:00:00+01:00')."New value: +"Future ISO 8601 timestamp with timezone offset to schedule publication (e.g. '2026-11-05T17:00:00+01:00'). Forces privacy_status='private'."

changedInput schema / properties / tags / description

Previous value: -"Updated list of YouTube SEO keyword tags."New value: +"Replacement list of YouTube SEO keyword tags. Leave omitted to keep existing tags."

changedInput schema / properties / thumbnail_path / description

Previous value: -"Optional absolute path to new thumbnail image."New value: +"Optional absolute local filesystem path to a readable PNG/JPG image (<=2MB) to upload via thumbnails.set."

changedInput schema / properties / title / description

Previous value: -"New video title (up to 100 characters)."New value: +"New video title (1–100 characters). Leave omitted to keep existing title."

addedInput schema / properties / title / maxLength
```
Added value: +100
```

changedInput schema / properties / video_id / description

Previous value: -"11-character YouTube video ID."New value: +"11-character YouTube video ID to update."

addedInput schema / properties / video_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{11}$"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "studioUrl": {
+      "type": "string"
+    },
+    "videoId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "videoId",
+    "studioUrl"
+  ],
+  "type": "object"
+}

First observedv0.1.0Nov 3, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses the ~51 quota unit cost, the OAuth2 authorization requirement, and the crucial fetch-then-merge behavior that preserves omitted fields rather than clearing them. It also flags the non-obvious side effect that publish_at forcibly overrides privacy_status to 'private', which an agent could not predict from the schema 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?

Dense but front-loaded: purpose first, then prerequisites, then behavioral caveats, then return shape. Every sentence carries information, though the final sentence listing the return keys is redundant given an output schema exists.

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 7-parameter mutation tool with an output schema, the description covers authorization, quota cost, side effects, and merge semantics — everything an agent needs to call it correctly. Return values are documented in the output schema, so the brief mention of them is harmless surplus rather than a gap.

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 description coverage is 100%, so the baseline is 3, and the description does consolidate the merge semantics (omitted params preserved) and the publish_at/privacy_status interaction into one readable statement. However, most of this detail — 'Leave omitted to keep existing', 'Forces privacy_status=private' — is already duplicated verbatim in the schema, so the added meaning is modest.

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 and resource — 'partial, idempotent update on an existing YouTube video's metadata, visibility, schedule, or custom thumbnail' — and enumerates exactly which fields are touched. The word 'existing' implicitly separates it from yt_upload_draft, but no sibling is named explicitly, so an agent must infer the boundary rather than read it.

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?

Gives clear operating context: channel-owner OAuth2 is required, and the underlying calls (videos.list + videos.update) with their quota cost are disclosed. It does not state when to prefer this over yt_video_details (read) or yt_upload_draft (create), so the exclusion guidance is inferential rather than explicit.

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

Deploy Server