YouTube MCP

Overview Schema Source Related Servers Discussions Admin

youtube_update_caption

Destructive

Update an approved caption track on an owned YouTube video with a local caption file, chosen language, MIME type, and display name after preview approval.

Instructions

Update an approved owned caption track.

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": {
      "videoId": "<videoId>",
      "filePath": "<filePath>",
      "mimeType": "<mimeType>",
      "language": "<language>",
      "name": "<name>",
      "captionId": "<captionId>",
      "approvalId": "<approvalId>"
    },
    "name": "youtube_update_caption"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Caption track name shown to viewers, up to 150 characters.
`confirm`	No	Must be true to execute; set it only after youtube_approve approved this exact preview.
`isDraft`	No	Whether the caption track is a draft that is not shown to viewers.
`videoId`	Yes	ID of an owned video the caption belongs to.
`filePath`	Yes	Absolute path to the local caption file.
`language`	Yes	Caption language code, e.g. en.
`mimeType`	Yes	Caption file MIME type: application/octet-stream, application/ttml+xml, text/plain or text/vtt.
`captionId`	Yes	Caption track ID, from youtube_list_caption_tracks.
`approvalId`	Yes	Approval ID from the youtube_preflight_caption_update preview, after approving it with youtube_approve.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.3.1Oct 31, 2026

addedInput schema / properties / approvalId / description

Added value: +"Approval ID from the youtube_preflight_caption_update preview, after approving it with youtube_approve."

addedInput schema / properties / captionId / description

Added value: +"Caption track ID, from youtube_list_caption_tracks."

addedInput schema / properties / confirm / description

Added value: +"Must be true to execute; set it only after youtube_approve approved this exact preview."

addedInput schema / properties / filePath / description

Added value: +"Absolute path to the local caption file."

addedInput schema / properties / isDraft / description

Added value: +"Whether the caption track is a draft that is not shown to viewers."

addedInput schema / properties / language / description
```
Added value: +"Caption language code, e.g. en."
```

addedInput schema / properties / mimeType / description

Added value: +"Caption file MIME type: application/octet-stream, application/ttml+xml, text/plain or text/vtt."

addedInput schema / properties / name / description

Added value: +"Caption track name shown to viewers, up to 150 characters."

addedInput schema / properties / videoId / description

Added value: +"ID of an owned video the caption belongs to."

First observedv0.1.0Oct 29, 2026

TDQS

C2.6/5.0

Behavior2/5

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

Annotations declare only destructiveHint=true, so the description owes the agent an explanation of what is destroyed or overwritten (the existing caption payload? the name? the draft status?) and does not provide one. "Approved owned" does hint at an authorization prerequisite, which is modest added value, but for a destructive mutation with a confirm/approvalId gate the disclosure burden is largely unmet here.

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?

A single short sentence with the scoping qualifiers front-loaded and zero filler. It is efficient, though the brevity is achieved partly by omitting information rather than by tight editing.

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

Completeness2/5

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

This is a destructive, approval-gated mutation with 9 parameters and 7 required fields, and no output schema. The description never states that the call requires a prior preflight preview plus youtube_approve, never says which video/caption it acts on, and never says what a successful update replaces. The schema carries the mechanics, but the description leaves the agent without the operational picture.

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 100%, so all nine parameters, including the confirm gate and the approvalId provenance, are already documented in the schema. The description adds nothing beyond that and therefore sits at the baseline 3 for a fully documented schema.

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

Purpose3/5

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

"Update an approved owned caption track" gives a specific verb and resource, and the qualifiers "approved" and "owned" narrow the scope. However it does nothing to distinguish this from the siblings it sits beside, notably youtube_upload_caption, youtube_preflight_caption_update and youtube_delete_caption, nor does it say what aspect of the track is updated (file content, name, draft flag).

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?

No statement of when to call this versus the preflight/approve pair or versus upload_caption. The only usage signal is the adjective "approved", which implies the youtube_preflight_caption_update → youtube_approve sequence, but the agent has to infer that ordering rather than being told it. No exclusions are stated.

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

Deploy Server