Allows fetching video transcripts and downloading video content directly from the platform.
Utilizes OpenAI's Whisper API to perform AI-powered speech-to-text for generating subtitles and transcriptions from video audio.
Enables downloading video content and generating subtitles using AI-powered speech-to-text tools.
Provides capabilities to download video content and generate transcriptions or subtitles for Twitch videos.
Supports downloading videos and extracting existing transcripts from the Vimeo platform.
Provides tools to retrieve transcripts in multiple languages, list available subtitle tracks, and download videos in various qualities and formats.
A Model Context Protocol (MCP) server that provides comprehensive video tools: transcript retrieval, video downloading, automatic subtitle generation, and direct audio transcription. Works with YouTube, Bilibili, Vimeo, and any platform supported by yt-dlp.
Multi-Platform Support: Works with YouTube, Bilibili, Vimeo, and any platform supported by yt-dlp
Video Transcripts: Extract existing transcripts/captions from videos
Video Downloads: Download videos to local storage in various formats and qualities
Auto Subtitle Generation: Generate subtitles using OpenAI Whisper API or local Whisper
Client Audio Transcription: audio_url fetch (allowlisted), small audio_base64, chunked uploads, optional async jobs, server-side Opus compression, structured JSON results
Multiple URL Formats: Support for various URL formats from different platforms
Timestamp Support: Include or exclude timestamps in transcript output
Language Selection: Request transcripts or generate subtitles in specific languages
Related MCP server: MCP YouTube Transcript Server
Tool | Description |
| Retrieve existing transcripts from video platforms |
| List available transcript languages for a video |
| Download videos to local storage |
| List downloaded video files |
| Generate subtitles using AI speech-to-text |
| Transcribe client-provided audio (URL / base64 / path / resource URI) |
| Start chunked upload for large audio payloads |
| Append one base64 chunk to an upload session |
| Finish upload and run transcription |
| Poll async transcription jobs |
| Cancel an async transcription job |
Node.js >= 16.0.0
yt-dlp - Required for transcript fetching and video downloads
ffmpeg - Required for subtitle generation, audio normalization, Opus compression, and silence-aware splitting (install a build with libopus)
yt-dlp (required):
# Using Homebrew (macOS)
brew install yt-dlp
# Using pip
pip install yt-dlpffmpeg (required for subtitle generation):
# Using Homebrew (macOS)
brew install ffmpeg
# Using apt (Ubuntu/Debian)
sudo apt install ffmpegLocal Whisper (optional, for local subtitle generation):
pip install openai-whispergit clone <repository-url>
cd transcript-mcp
npm install
npm run buildnpm install -g transcript-mcpAdd the MCP server to your configuration file:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"transcript-mcp": {
"command": "node",
"args": ["/path/to/transcript-mcp/dist/index.js"],
"env": {
"TRANSCRIPT_MCP_STORAGE_DIR": "/path/to/downloads",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"transcript-mcp": {
"command": "node",
"args": ["/path/to/transcript-mcp/dist/index.js"],
"env": {
"TRANSCRIPT_MCP_STORAGE_DIR": "/path/to/downloads",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}Variable | Description | Default |
| Default directory for downloaded videos |
|
| OpenAI API key for Whisper-based subtitle generation | None |
| Preferred whisper engine: |
|
| Legacy alias for | — |
| Legacy alias for | — |
| Path to local whisper binary |
|
| Path to whisper model (for local whisper) | Auto-download |
| Path to yt-dlp binary |
|
| Path to ffmpeg binary |
|
| Path to ffprobe binary | Derived from |
| Comma-separated host patterns allowed for | empty |
| Enable debug logging |
|
Retrieve existing transcripts from video platforms.
Parameters:
url (required): Video URL
lang (optional): Language code (e.g., 'en', 'es', 'zh')
include_timestamps (optional): Include timestamps (default: true)
Example:
Get the transcript from https://www.youtube.com/watch?v=VIDEO_IDList available transcript languages for a video.
Parameters:
url (required): Video URL
Example:
What transcript languages are available for https://www.youtube.com/watch?v=VIDEO_ID?Download a video to local storage.
Parameters:
url (required): Video URL to download
output_dir (optional): Custom output directory
filename (optional): Custom filename
format (optional): Video format - mp4, webm, mkv (default: mp4)
quality (optional): Quality - best, 1080p, 720p, 480p, 360p, audio (default: best)
Example:
Download this video: https://www.youtube.com/watch?v=VIDEO_IDList all downloaded video files.
Parameters:
directory (optional): Directory to list (default: storage directory)
Example:
List my downloaded videosGenerate subtitles for a local video file using AI speech-to-text.
Parameters:
video_path (required): Absolute path to the video file
engine (optional): openai or local (default: auto-detect)
language (optional): Language code for transcription
output_format (optional): srt or vtt (default: srt)
Example:
Generate subtitles for /path/to/video.mp4Transcribes audio via Whisper. Prefer audio_url (server fetches bytes; configure TRANSCRIPT_MCP_URL_ALLOWLIST). Use audio_base64 only for small clips (about 60KB raw per call; larger payloads should use chunked upload or a URL). audio_path / file:// only work when the MCP host shares a filesystem with the caller (often false in sandboxed clients).
By default the server re-encodes to Opus 16 kHz mono 16 kbps before Whisper. Set skip_compression: true if you already optimized the file.
Audio longer than 5 minutes (or when async: true) returns { job_id, status: "processing" }; poll transcribe_get_job.
Parameters (one required input):
audio_url, audio_path, audio_base64, or audio_resource_uri (file:// / data:...;base64,...)
filename (optional): Hint when magic-byte detection is inconclusive
skip_compression (optional): Skip Opus recompression (default: false)
engine (optional): openai, local, or auto (default: auto)
language (optional): Language hint for transcription
include_timestamps (optional): When as_text is true, include [MM:SS] lines (default: true)
as_text (optional): If true, return plain transcript text; if false, return structured JSON (default: false)
async (optional): Force async job (default: false)
Examples:
Transcribe this presigned URL (after allowlisting the host): audio_url=...Transcribe this audio file on the MCP host: /path/to/interview.m4aFor large files, split the raw bytes into base64 chunks of at most max_chunk_bytes (~60KB) from transcribe_upload_start, call transcribe_upload_append for each index, then transcribe_upload_finalize. Abandoned uploads are garbage-collected after about an hour.
Poll or cancel async jobs created by transcribe-audio (long audio or async: true).
Pros: High accuracy, no local setup needed, supports 50+ languages
Cons: Requires API key, costs per audio minute
Setup: Set OPENAI_API_KEY environment variable
Pros: Free, runs locally, no API limits
Cons: Requires setup, uses local CPU/GPU
Setup: pip install openai-whisper
The tool auto-detects which engine to use:
If OPENAI_API_KEY is set, uses OpenAI Whisper
If local whisper is installed, uses local whisper
Returns an error if neither is available
For transcribe-audio, auto uses OpenAI first and falls back to local whisper when local whisper is available.
1. Download this video: https://www.youtube.com/watch?v=VIDEO_ID
2. Generate subtitles for the downloaded fileGet the transcript from https://www.youtube.com/watch?v=VIDEO_ID and summarize the key points1. Download the video: https://vimeo.com/123456789
2. Generate English subtitles for itAny platform supported by yt-dlp, including:
YouTube
Bilibili
Vimeo
Twitter/X
TikTok
Twitch
And many more...
Full list: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
transcript-mcp/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── transcript-fetcher.ts # Transcript fetching using yt-dlp
│ ├── video-downloader.ts # Video download functionality
│ ├── subtitle-generator.ts # AI-powered subtitle generation
│ ├── config.ts # Configuration management
│ ├── url-detector.ts # Platform detection from URLs
│ ├── parser.ts # Transcript parsing (SRT, VTT, JSON)
│ └── errors.ts # Custom error classes
├── test/
│ └── transcript.test.ts # Unit tests
├── dist/ # Compiled JavaScript (after build)
└── package.json# Build
npm run build
# Test
npm test
# Development mode
npm run devbrew install yt-dlp
# or
pip install yt-dlpbrew install ffmpegbrew install ffmpegEither:
Set OPENAI_API_KEY environment variable, or
Install local whisper: pip install openai-whisper
Check if the video is publicly accessible
Some platforms may have rate limits
Private/restricted videos cannot be downloaded
OpenAI Whisper API is faster than local
Local whisper performance depends on your hardware
Consider using a smaller model for local whisper
MIT
yt-dlp for video platform support
OpenAI Whisper for speech-to-text
Model Context Protocol for the MCP framework
Download a video from any supported platform (YouTube, Vimeo, etc.) to local storage. Returns the file path of the downloaded video.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL from any supported platform (e.g., YouTube, Vimeo) | |
| output_dir | No | Custom output directory. Default: configured storage directory | |
| filename | No | Custom filename for the downloaded video. Default: video title | |
| format | No | Output video format. Default: mp4 | |
| quality | No | Video quality. Default: best |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that it downloads videos and returns a file path, omitting details like overwrite behavior, error handling, download progress, or network requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two short sentences that immediately convey the tool's purpose and output. Every word is necessary, and the structure is front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a straightforward download tool, but it lacks details on file overwriting, default behavior for omitted parameters, and potential limitations (e.g., large files, timeout). Given the 5 parameters and no output schema, more context would improve usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters are documented in the input schema with descriptions, achieving 100% coverage. The description adds no additional parameter information beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (download), the resource (video from supported platforms like YouTube, Vimeo), and the result (returns file path). It effectively distinguishes itself from sibling tools focused on subtitles, transcription, and listing downloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance. While the purpose is clear and siblings are functionally distinct (e.g., transcribe vs. download), no context is given about alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate subtitles for a local video file using AI speech-to-text (OpenAI Whisper or local whisper). Creates an SRT or VTT file alongside the video.
| Name | Required | Description | Default |
|---|---|---|---|
| video_path | Yes | Absolute path to the local video file to generate subtitles for | |
| engine | No | Whisper engine to use. 'openai' uses OpenAI Whisper API (requires OPENAI_API_KEY), 'local' uses locally installed whisper. Default: auto-detect | |
| language | No | Language code for transcription (e.g., 'en', 'es', 'fr'). Default: auto-detect | |
| output_format | No | Subtitle format. Default: srt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the engines (OpenAI Whisper, local whisper) and output formats, but does not disclose potential side effects (e.g., file creation, processing time, API key requirements for some engines). With no annotations, it partially covers behavioral traits but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 20 words, no filler. Front-loaded with the core purpose and key details. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main functionality and output, but lacks mention of return value (e.g., actual path to created subtitle file) and prerequisites. For a 4-parameter tool with high schema coverage, it's mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear descriptions; the description adds value by noting that the subtitle file is created 'alongside the video', which is not in the schema. This extra context enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool generates subtitles for a local video file using AI speech-to-text, specifying the output format (SRT or VTT) and placement (alongside video). Distinguishes from siblings like 'transcribe-audio' which produces transcripts, not subtitle files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when subtitles are needed, but lacks explicit guidance on when to use this tool versus alternatives like 'transcribe-audio' or 'get-transcript'. Does not mention prerequisites (e.g., video file existence, API key for OpenAI engine).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the transcript of a video from supported platforms (YouTube, Bilibili, Vimeo, etc.). Accepts various URL formats and returns the full transcript with timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL from any supported platform (e.g., YouTube, Bilibili, Vimeo). Examples: https://www.youtube.com/watch?v=VIDEO_ID, https://www.bilibili.com/video/BVxxxxx, https://vimeo.com/123456789 | |
| lang | No | Language code for transcript (e.g., 'en', 'es', 'fr', 'zh'). Default: video's default language | |
| include_timestamps | No | Include timestamps in the transcript output. Default: true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description says it returns transcript with timestamps but fails to disclose behavior when transcript is unavailable, supported platforms limitations, or any rate limits. Missing critical operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information, no redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description indicates return format (transcript with timestamps). Missing error handling or platform constraints, but adequate for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds context about URL format flexibility but does not significantly enhance meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves transcripts from multiple platforms (YouTube, Bilibili, Vimeo) with various URL formats. Differentiates from siblings like download-video and generate-subtitles by focusing on existing transcript retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives like transcribe-audio or generate-subtitles. Does not mention prerequisites (video must have captions) or conditions like requiring authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all downloaded video files in the storage directory or a specified directory.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Directory to list. Default: configured storage directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation by using 'list', but does not explicitly disclose behavioral traits such as safety, authorization needs, or side effects. Given no annotations, the absence of detail is acceptable for a simple list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description provides sufficient context. It lacks details on output format (e.g., file names vs. metadata), but is still complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines one parameter with a description. Since schema coverage is 100%, the description adds no extra semantics beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists downloaded video files, specifying both the action and resource. It distinguishes itself from sibling tools like download-video and transcript-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The purpose is clear, but there is no mention of exclusions or comparison to other listing operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available transcript languages for a video from any supported platform.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Video URL from any supported platform (YouTube, Bilibili, Vimeo, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description states it lists languages from supported platforms, but does not disclose read-only nature, authentication needs, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Clearly front-loads the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, list operation), the description is sufficient. However, lack of output schema specification slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the 'url' parameter. The description adds no additional parameter information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List' and the resource 'available transcript languages for a video', distinguishing it from siblings like 'get-transcript' and 'generate-subtitles'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking available languages before requesting a transcript, but lacks explicit when-to-use, when-not-to-use, or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribes audio via Whisper. Preferred: audio_url (most token-efficient; server fetches bytes). audio_base64 is for small clips only (<= ~60KB raw per call). audio_path only works when the MCP host shares a filesystem with the caller (often false on Claude.ai / Claude Code). For larger payloads in sandboxed environments, use transcribe_upload_start / transcribe_upload_append / transcribe_upload_finalize. Server re-encodes to Opus 16kHz mono 16kbps before Whisper unless skip_compression=true. Long audio (>5min) or async=true returns a job_id; poll transcribe_get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| audio_path | No | Absolute path to a local audio file on the MCP host (often unusable from sandboxed clients). | |
| audio_base64 | No | Base64-encoded audio payload (single-call max ~60KB raw; use chunked upload for larger). | |
| audio_resource_uri | No | Audio resource URI, supported schemes: file:// and data:...;base64,... | |
| audio_url | No | HTTP(S) URL the server will fetch (requires TRANSCRIPT_MCP_URL_ALLOWLIST). | |
| filename | No | Optional filename hint (used when magic-byte detection is inconclusive). | |
| skip_compression | No | If true, skip Opus 16kbps recompression (caller already optimized). Default: false | |
| engine | No | Transcription engine preference. 'auto' uses OpenAI first and falls back to local whisper when available. | |
| language | No | Language code for transcription (e.g., 'en', 'es', 'fr'). Default: auto-detect | |
| include_timestamps | No | When as_text=true, include [MM:SS] timestamps in the plain text output. Default: true | |
| as_text | No | If true, return only the joined transcript string. If false, return structured JSON. Default: false | |
| async | No | If true, always enqueue an async job (returns job_id). Default: false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses server-side behavior: fetches bytes, re-encodes to Opus 16kHz unless skip_compression, returns job_id for long audio or async, and references polling endpoint. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the most critical information (preferred method, limits, async). Slightly lengthy but every sentence earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters and no output schema, the description covers input methods, async handling, job polling, and compression. Lacks explicit output format details, but the as_text parameter clarifies the two return types. Sufficient for complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, but the tool description adds significant value: token efficiency for audio_url, size limit for audio_base64 (<=60KB), semantics of skip_compression, and async behavior. Goes well beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it transcribes audio using Whisper, and distinguishes between sibling tools for upload and job polling (transcribe_upload_start/append/finalize, transcribe_get_job). Specific verb+resource+method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use each input method (audio_url most efficient, audio_base64 for small clips, audio_path only with shared filesystem), and when to use chunked upload vs this tool. Also covers async usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel an async transcription job (best-effort).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The phrase 'best-effort' hints at non-guaranteed success, but no disclosure of side effects, what happens if job already complete, or required permissions. Annotations absent, so description carries full burden but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one short phrase with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple cancellation tool with one parameter and no output schema, the description lacks completeness: no indication of return value (e.g., success/failure message), no error states, and no confirmation that the job was cancelled. The 'best-effort' is the only extra context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter job_id with 0% schema description coverage. Description does not explain the parameter (format, source, or how to obtain it). Fails to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Cancel an async transcription job (best-effort)' clearly identifies the action (cancel) and the resource (async transcription job). It distinguishes from siblings like transcribe_get_job (status check) and upload tools, but doesn't explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., checking job status first). No mention of context like job must be in progress.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll an async transcription job created by transcribe-audio.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| as_text | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'async' but does not elaborate on typical async polling behavior: whether the tool is non-blocking, what happens if the job is not ready (error or empty response), or any side effects. It also lacks information about rate limits or read-only status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks critical details. While it is front-loaded with the action, it does not earn its place fully because it omits information that would make the tool usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an async polling tool (2 parameters, no output schema, no annotations), the description is insufficient. It does not describe response structure, polling behavior, error handling, or how to interpret results. The tool's behavior is largely opaque.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds no meaning beyond the parameter names. 'job_id' is implied to be an identifier but not explained; 'as_text' is not described at all (e.g., whether it controls output format). This fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('poll') and the resource ('async transcription job'), and references the creation tool 'transcribe-audio' for context. However, it does not specify what information is returned upon polling (e.g., status, results).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like transcribe_cancel_job. There is no mention of polling frequency, when a job is considered complete, or prerequisites such as obtaining a job_id from transcribe-audio.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append one base64 chunk to an upload session.
| Name | Required | Description | Default |
|---|---|---|---|
| upload_id | Yes | ||
| chunk_index | Yes | ||
| audio_base64 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond the basic action. It does not disclose error handling (e.g., consequences of duplicate chunk_index), idempotency, size limits, or the need for sequential chunk indices. No annotations are present to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which ensures clarity but at the cost of omitting crucial details needed for correct usage. A single sentence is acceptable only if the tool is self-explanatory, which it is not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and parameter descriptions, the tool description is severely incomplete. It fails to explain the upload session lifecycle, how this append step fits, or the expected behavior for errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description adds no meaning to the parameters. The agent cannot infer what 'upload_id' represents, the role of 'chunk_index', or the expected format of 'audio_base64' beyond base64 encoding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append') and the resource ('one base64 chunk to an upload session'). It distinguishes from sibling tools like 'transcribe_upload_start' and 'transcribe_upload_finalize' by specifying the chunk appending operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., that an upload must be started first) or that finalization is required after all chunks are appended. The agent is left to infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize a chunked upload, run compression + Whisper, return structured JSON (or text with as_text).
| Name | Required | Description | Default |
|---|---|---|---|
| upload_id | Yes | ||
| skip_compression | No | ||
| engine | No | ||
| language | No | ||
| as_text | No | ||
| async | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that compression and Whisper are run, and that output can be structured JSON or text if as_text is set. However, it does not mention error behaviors, required permissions, or handling of the async parameter. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and key option. No filler words or repetition. It front-loads the main action and is appropriately sized for a tool with a clear, limited scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 6 parameters (including enums and optional fields) and no output schema, the description is too terse. It does not explain each parameter's role, the return structure in detail, or prerequisites. The agent would need to infer or experiment, which is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only hints at the 'as_text' parameter by mentioning 'or text with as_text'. Other parameters (upload_id, skip_compression, engine, language, async) are not clarified, leaving the agent without additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Finalize' and the resource 'chunked upload', and specifies the processing steps (compression + Whisper) and output format (structured JSON or text). It distinguishes this tool from siblings like transcribe_upload_start and transcribe_upload_append by being the finalization step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finalizing a chunked upload but lacks explicit guidance on when to use versus alternatives, such as not using for single uploads or that it should follow transcribe_upload_append. No exclusions or when-not-to-use are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin a chunked audio upload for large payloads. Returns upload_id and max_chunk_bytes (~60KB).
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Original filename hint | |
| expected_chunks | Yes | Total number of base64 chunks you will upload | |
| language | No | ||
| include_timestamps | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return values and the approximate chunk size (~60KB), which adds modest transparency. However, it omits details like authentication requirements, whether a job is created, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences containing essential information with front-loaded purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema and no annotations, the description is minimal. It fails to explain the chunked upload protocol, how to use the returned upload_id, or the meaning of the parameters beyond their names. For a multi-step process, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only filename and expected_chunks have descriptions). The tool description adds no additional meaning beyond the schema for these parameters. For language and include_timestamps, there is no description in either schema or tool description, leaving agents guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initiates a chunked audio upload for large payloads and names the key return values (upload_id and max_chunk_bytes). It is distinct from sibling tools like transcribe_upload_append and transcribe_upload_finalize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for large payloads that require chunking but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes: download, subtitle generation, transcript retrieval, listing, and transcription. However, generate-subtitles and transcribe-audio both involve speech-to-text, but their outputs (subtitle files vs. plain text/JSON) are different. The descriptions clarify the differences, so ambiguity is minimal.
Tool names use a mix of hyphens (download-video, generate-subtitles) and underscores (transcribe_cancel_job, transcribe_upload_start). The verb-noun pattern is consistent, but the inconsistent separator reduces clarity and predictability.
11 tools cover the core video processing tasks (download, transcribe, subtitle, list) without being excessive. The chunked upload support for large audio files is a reasonable addition, and each tool serves a clear purpose.
The set covers downloading, transcription (with advanced upload handling), subtitle generation, and listing. Missing a tool to delete downloaded files, but the primary workflows are well-supported. The domain is sufficiently covered for typical use.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Multimodal video analysis MCP — transcription, vision, and OCR for any video URL.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/JamesANZ/transcript-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
