Skip to main content
Glama
Sign In
mategog

mateai-youtube

by mategog
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

yt_upload_draft

Upload a local MP4/MOV file to YouTube Studio as a private draft, optionally adding a thumbnail, pinned comment, or future publish schedule.

Instructions

Upload a local MP4/MOV video file to YouTube Studio via YouTube Data API v3 (videos.insert, costs ~1,600 daily quota units) and optionally attach a custom thumbnail (thumbnails.set) and top-level pinned comment (commentThreads.insert). Requires channel OAuth2 with youtube.upload scope. Non-idempotent: each call creates a new YouTube video resource and returns {videoId, studioUrl, watchUrl, privacyStatus, publishAt}. Defaults to privacy_status='private' (unpublished draft); when publish_at (ISO 8601 future timestamp) is provided, privacy_status is forced to 'private' until YouTube automatically publishes the video at publish_at. Inline parameters (title, description, tags, hashtags, pinned_comment) override values parsed from spec_path.

Input Schema

NameRequiredDescriptionDefault
tagsNoYouTube SEO keyword tags (combined length up to 500 characters).
titleNoVideo title (1–100 characters). Required unless spec_path provides a '## Title' section.
hashtagsNoHashtags to append to the end of description (e.g. ['#AINews', '#Shorts']).
languageNoBCP-47 language code for defaultLanguage and defaultAudioLanguage (default: 'en').en
spec_pathNoOptional local path to a Markdown upload spec file ('## Title', '## Description', '## Tags', '## Pinned comment') used as fallback when inline fields are omitted.
publish_atNoOptional future ISO 8601 timestamp with timezone offset for scheduled publication (e.g. '2026-11-04T18:00:00+01:00'). Forces privacy_status='private' until release.
video_pathYesAbsolute local filesystem path to a readable MP4 or MOV video file to upload.
category_idNoYouTube numeric category ID (default: '28' for Science & Technology).28
descriptionNoVideo description (up to 5,000 characters). Hashtags from 'hashtags' are appended if not already present.
made_for_kidsNoCOPPA selfDeclaredMadeForKids flag (default: false).
pinned_commentNoTop-level comment text to post on the video when auto_post_comment is true.
privacy_statusNoInitial visibility in YouTube Studio (default: 'private'). Forced to 'private' whenever publish_at is set.private
thumbnail_pathNoOptional absolute local path to a PNG/JPG custom thumbnail image (<=2MB, requires verified YouTube account).
auto_post_commentNoIf true and pinned_comment is non-empty, immediately posts pinned_comment as a top-level comment (requires video to allow comments).
contains_synthetic_mediaNoYouTube Studio altered/synthetic media disclosure flag (status.containsSyntheticMedia, default: false).

Output Schema

NameRequiredDescriptionDefault
videoIdYes
watchUrlYes
publishAtNo
studioUrlYes
privacyStatusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed24 schema fields changedv0.2.0
    • addedInput schema / properties / auto_post_comment / default
      Added value: +false
    • changedInput schema / properties / auto_post_comment / description
      Previous value: -"If true, automatically post the pinned_comment onto the video."New value: +"If true and pinned_comment is non-empty, immediately posts pinned_comment as a top-level comment (requires video to allow comments)."
    • addedInput schema / properties / category_id / default
      Added value: +"28"
    • changedInput schema / properties / category_id / description
      Previous value: -"YouTube category ID (default: '28' for Science & Technology)."New value: +"YouTube numeric category ID (default: '28' for Science & Technology)."
    • addedInput schema / properties / contains_synthetic_media / default
      Added value: +false
    • changedInput schema / properties / contains_synthetic_media / description
      Previous value: -"Altered/synthetic media disclosure flag in YouTube Studio (default: false)."New value: +"YouTube Studio altered/synthetic media disclosure flag (status.containsSyntheticMedia, default: false)."
    • changedInput schema / properties / description / description
      Previous value: -"Full video description (up to 5000 characters)."New value: +"Video description (up to 5,000 characters). Hashtags from 'hashtags' are appended if not already present."
    • addedInput schema / properties / description / maxLength
      Added value: +5000
    • changedInput schema / properties / hashtags / description
      Previous value: -"Hashtags to append to description (e.g. ['#AINews', '#Shorts'])."New value: +"Hashtags to append to the end of description (e.g. ['#AINews', '#Shorts'])."
    • addedInput schema / properties / language / default
      Added value: +"en"
    • changedInput schema / properties / language / description
      Previous value: -"BCP-47 language code for title/audio (default: 'en')."New value: +"BCP-47 language code for defaultLanguage and defaultAudioLanguage (default: 'en')."
    • addedInput schema / properties / made_for_kids / default
      Added value: +false
    • changedInput schema / properties / made_for_kids / description
      Previous value: -"Whether video is made for kids (default: false)."New value: +"COPPA selfDeclaredMadeForKids flag (default: false)."
    • changedInput schema / properties / pinned_comment / description
      Previous value: -"Top-level comment to post on the video."New value: +"Top-level comment text to post on the video when auto_post_comment is true."
    • addedInput schema / properties / privacy_status / default
      Added value: +"private"
    • changedInput schema / properties / privacy_status / description
      Previous value: -"Visibility in YouTube Studio (default: 'private'). Automatically set to 'private' when publish_at is used."New value: +"Initial visibility in YouTube Studio (default: 'private'). Forced to 'private' whenever publish_at is set."
    • changedInput schema / properties / publish_at / description
      Previous value: -"Optional ISO 8601 timestamp to schedule automatic publication (e.g. '2026-11-04T18:00:00+01:00')."New value: +"Optional future ISO 8601 timestamp with timezone offset for scheduled publication (e.g. '2026-11-04T18:00:00+01:00'). Forces privacy_status='private' until release."
    • changedInput schema / properties / spec_path / description
      Previous value: -"Optional path to upload markdown file (fallback if title/description omitted)."New value: +"Optional local path to a Markdown upload spec file ('## Title', '## Description', '## Tags', '## Pinned comment') used as fallback when inline fields are omitted."
    • changedInput schema / properties / tags / description
      Previous value: -"YouTube SEO keyword tags."New value: +"YouTube SEO keyword tags (combined length up to 500 characters)."
    • changedInput schema / properties / thumbnail_path / description
      Previous value: -"Optional absolute path to thumbnail PNG/JPG."New value: +"Optional absolute local path to a PNG/JPG custom thumbnail image (<=2MB, requires verified YouTube account)."
    • changedInput schema / properties / title / description
      Previous value: -"Video title (up to 100 characters)."New value: +"Video title (1–100 characters). Required unless spec_path provides a '## Title' section."
    • addedInput schema / properties / title / maxLength
      Added value: +100
    • changedInput schema / properties / video_path / description
      Previous value: -"Absolute path to MP4/MOV file."New value: +"Absolute local filesystem path to a readable MP4 or MOV video file to upload."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "privacyStatus": {
+      "type": "string"
+    },
+    "publishAt": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "studioUrl": {
+      "type": "string"
+    },
+    "videoId": {
+      "type": "string"
+    },
+    "watchUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "videoId",
+    "studioUrl",
+    "watchUrl"
+  ],
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, it discloses the ~1,600-unit quota cost, the required youtube.upload OAuth scope, the fact that a new video resource is created each call, and the exact return payload ({videoId, studioUrl, watchUrl, privacyStatus, publishAt}). It also explains the publish_at/privacy_status interaction and that inline fields override spec_path values, which the annotations do not cover.

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 description is dense but front-loaded, leading with the action, API call and quota before optional behaviors. The enumeration of return fields is slightly redundant given an output schema exists, but otherwise every sentence carries decision-relevant information.

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 15-parameter mutation with rich annotations and an output schema, the description supplies the remaining essentials: authentication scope, cost, idempotency consequences, default state, scheduling semantics and parameter precedence. An agent has enough to call it correctly without further exploration.

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 coverage is already 100%, so the schema carries most of the burden, but the description still adds real meaning by stating the precedence rule (inline title/description/tags/hashtags/pinned_comment override spec_path) and clarifying that publish_at overrides privacy_status. Those cross-parameter interactions are not expressed in the schema.

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

Purpose5/5

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

The description names a specific verb and resource ('Upload a local MP4/MOV video file to YouTube Studio'), plus the underlying API call (videos.insert) and the two optional side-operations (thumbnails.set, commentThreads.insert). It is clearly distinct from siblings like yt_update_video and yt_post_comment, which modify or comment on an existing video rather than create one.

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 clear operating context: defaults to an unpublished private draft, and publish_at triggers scheduled release with privacy forced to 'private'. It does not explicitly say when to prefer yt_update_video or the dedicated yt_post_comment over the inline pinned_comment option, so the boundary with siblings is left implied rather than stated.

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