Skip to main content
Glama

YouTube Transcript

youtube_transcript
Read-onlyIdempotent

Returns the caption transcript of one YouTube video as text with [seconds] timestamps, plus segments_count; text is capped at 12,000 characters (truncated and total_chars say whether it was cut). Use it when the video ID is known. It does not find videos (use search_youtube) and does not translate captions. 5 credits per successful call. Required: video_id.

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": {
      "video_id": "<video_id>"
    },
    "name": "youtube_transcript"
  }
}

Input Schema

NameRequiredDescriptionDefault
countryNoTwo-letter country code the transcript is requested from, e.g. "us" or "gb". Omit for the source default, us.
languageNoTwo-letter code of the caption language wanted, e.g. "en" or "it"; captions are not translated. Omit for the source default, en.
video_idYesYouTube video ID, the v= value of a watch URL, e.g. "jNQXAC9IVRw".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Two-letter country code used for transcript retrieval."New value: +"Two-letter country code the transcript is requested from, e.g. \"us\" or \"gb\". Omit for the source default, us."
    • changedInput schema / properties / language / description
      Previous value: -"Preferred two-letter transcript language code."New value: +"Two-letter code of the caption language wanted, e.g. \"en\" or \"it\"; captions are not translated. Omit for the source default, en."
    • changedInput schema / properties / video_id / description
      Previous value: -"YouTube video ID whose transcript should be returned."New value: +"YouTube video ID, the v= value of a watch URL, e.g. \"jNQXAC9IVRw\"."
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond that with cost ('5 credits per successful call') and truncation semantics (12,000-char cap, truncated and total_chars flags), which materially affect how an agent should treat the result. It stops short of describing failure modes, e.g. what happens for videos without captions or when the requested language is unavailable.

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

Conciseness5/5

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

Three tight sentences: output shape first, then usage conditions and exclusions, then cost and the required parameter. No filler, and the most decision-relevant facts are front-loaded.

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?

With no output schema, the description carries the return-value burden itself and does so: format, timestamps, segments_count, truncation fields. Combined with pricing and the sibling pointer, an agent has everything needed to call it and interpret the result.

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%, and the enums plus per-parameter descriptions already document video_id, language, and country thoroughly. The description only restates 'Required: video_id,' adding no meaning beyond the schema, so the baseline of 3 applies.

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 ('Returns the caption transcript of one YouTube video') and immediately characterizes the output: text with [seconds] timestamps plus segments_count, capped at 12,000 characters. This is distinguishable from every sibling at a glance, since none of them return caption data.

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

Usage Guidelines5/5

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

Gives both a positive condition ('when the video ID is known') and explicit exclusions with routing: 'does not find videos (use search_youtube) and does not translate captions.' An agent knows exactly when to pick this tool and where to go otherwise.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources