Skip to main content
Glama
Sign In
mateai-youtube

mateai-youtube

by mategog
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

yt_channel_snapshot

Idempotent

Fetches live YouTube channel stats, recent long-form videos, and Shorts metrics using OAuth for private owner analytics. Writes an updated local report.html dashboard and JSON cache.

Instructions

Fetch live YouTube channel statistics, recent long-form videos, and Shorts metrics, and write an updated local report.html dashboard and channel_snapshot.json cache on disk. When YouTube OAuth2 credentials are present (and force_public is false), queries YouTube Data API v3 (~3 quota units) and YouTube Analytics API v2 for private owner metrics (averageViewPercentage, swipedAwayRate, engagedViews, estimatedMinutesWatched, subscribersGained); public page scraping is opt-in only (force_public=true or MATEAI_YT_PUBLIC_SCRAPE=1); without OAuth or opt-in it returns setup instructions. Overwrites report.html idempotently on each run.

Input Schema

NameRequiredDescriptionDefault
handleNoYouTube channel handle (with or without leading '@', e.g. '@mateai-c6m'). Defaults to '@mateai-c6m'.@mateai-c6m
force_publicNoOpt in to public page scraping for this call (bypasses OAuth2; public views/likes only). Only set when the user asks for it.

Output Schema

NameRequiredDescriptionDefault
modeYes
shortsYes
videosYes
channelYes
dashboardPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • changedInput schema / properties / force_public / description
      Previous value: -"If true, bypass stored OAuth2 tokens and use zero-config public scraping only."New value: +"Opt in to public page scraping for this call (bypasses OAuth2; public views/likes only). Only set when the user asks for it."
  2. Changed6 schema fields changedv0.2.0
    • addedInput schema / properties / force_public / default
      Added value: +false
    • changedInput schema / properties / force_public / description
      Previous value: -"If true, use zero-config public snapshot even if OAuth token exists."New value: +"If true, bypass stored OAuth2 tokens and use zero-config public scraping only."
    • addedInput schema / properties / handle / default
      Added value: +"@mateai-c6m"
    • changedInput schema / properties / handle / description
      Previous value: -"YouTube channel handle (e.g. '@mateai-c6m'). Defaults to '@mateai-c6m'."New value: +"YouTube channel handle (with or without leading '@', e.g. '@mateai-c6m'). Defaults to '@mateai-c6m'."
    • addedInput schema / properties / handle / pattern
      Added value: +"^@?[A-Za-z0-9._-]+$"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "channel": {
+      "type": "object"
+    },
+    "dashboardPath": {
+      "type": "string"
+    },
+    "mode": {
+      "enum": [
+        "studio_oauth",
+        "public_scrape"
+      ],
+      "type": "string"
+    },
+    "shorts": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "videos": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "mode",
+    "channel",
+    "videos",
+    "shorts",
+    "dashboardPath"
+  ],
+  "type": "object"
+}
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: quota cost (~3 units), which APIs are queried for which private metrics, the auth precondition for private metrics, the opt-in gate for scraping, the fallback of returning setup instructions, and that report.html is overwritten idempotently. This is exactly the disk-write/auth/quota context the annotations alone (readOnlyHint=false, idempotentHint=true) do not convey.

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-loads the purpose and side effects, then layers auth/quota/fallback details. It is dense with parenthetical metric lists and would benefit from slight trimming, but nearly every clause carries actionable 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 tool with disk side effects, auth branching, and quota cost, the description covers the decision points an agent needs: auth requirement, opt-in scraping, fallback behavior, and idempotent overwrite. An output schema exists, so return-value detail is correctly omitted.

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 100%, so baseline is 3, but the description adds real meaning: force_public bypasses OAuth2 and yields public views/likes only, is opt-in, and should only be set on user request. That clarifies the parameter's consequence in a way the schema text alone does not fully convey.

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?

States a specific verb and resource set — fetch live channel stats, recent long-form videos, Shorts metrics — and names the concrete side effects (report.html dashboard, channel_snapshot.json cache). No sibling tool does a snapshot-style fetch, and the description makes that scope unmistakable.

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?

Clearly describes the two operating modes: OAuth-present path hits Data API v3 / Analytics API v2, while public scraping only happens with force_public=true or the env var, and without either it returns setup instructions. It stops short of explicitly routing against siblings (e.g. yt_video_details) or stating when-not-to-use, so it is not a full 5.

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