Skip to main content
Glama

framefetch_extract

Read-only

Extract data from ONE public social-video URL (YouTube incl. Shorts, TikTok, Instagram Reels): metadata/insights/transcript/frames/digest/comments/etc — see fields. When NOT to use: non-video pages, private/login-walled content, or bulk crawling (one URL per call). Returns one JSON object with only the requested fields + a cost block (micro-USD); shapes: https://framefetch.net/docs. Cost scales with what you request (frames/transcript cost more than metadata). No key? POST /v1/keys {email} -> instant key (~100 free calls); or x402 (USDC), no account. Example: {"url":"https://www.youtube.com/watch?v=...","fields":["metadata","transcript"]}.

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": {
      "url": "<url>"
    },
    "name": "framefetch_extract"
  }
}

Input Schema

NameRequiredDescriptionDefault
askNoQuestion about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`. No transcript available: falls back to frames, `based_on`:["frames"].
urlYesPublic video URL from a supported platform.
cacheNofalse forces a fresh, billed extract.
voiceNoVoice for "audio_digest": OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) + Groq "Fritz-PlayAI"; default "alloy".
fieldsNoWhich data to return; default ["metadata"]. Pulls: digest→transcript; audio_digest→digest→transcript; structured→transcript; comment_sentiment→comments. digest/audio_digest/structured/comment_sentiment: degrade to a warning, never charged, on failure. digest: gist+topics via LLM. audio_digest: mp3 of digest (signed URL, 24h); voice via `voice`; +`translate` for other-language audio. structured: chapters/entities/products_shown/claims/key_moments via vision LLM. comments: up to comments_cap; YouTube only (else warning; see GET /v1/platforms). comment_sentiment: aggregated audience sentiment (positive_pct/neutral_pct/negative_pct/summary/top_themes); needs >=5 comments; same YouTube-only limit. text_overlay: OCR per frame; requires "frames"; skipped above 200 frames. delta: velocity vs the previous fetch; first call seeds the baseline. Docs: https://framefetch.net/docs.
framesNoFrame-sampling spec; required when "frames" or "text_overlay" is requested.
translateNoISO-639-1 target language (e.g. "es"); adds `transcript_translated` (timings kept). Requires "transcript" (or "digest"). Billed per audio-minute.
comments_capNoMax top-level comments (1-200, default 30); only used with "comments".
subtitle_formatNoRenders transcript as subtitles in `subtitles` (srt/vtt). Requires "transcript" (or "digest"); uses translated cues if "translate" set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / ask / description
      Previous value: -"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`. No transcript (e.g. Pinterest): falls back to frames, `based_on`:[\"frames\"]."New value: +"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`. No transcript available: falls back to frames, `based_on`:[\"frames\"]."
  2. Changed1 schema field changed
    • changedInput schema / properties / comments_cap / description
      Previous value: -"Max top-level comments (1-200, default 100); only used with \"comments\"."New value: +"Max top-level comments (1-200, default 30); only used with \"comments\"."
  3. Changed1 schema field changed
    • removedInput schema / properties / verbosity
      Removed value: -{
      -  "enum": [
      -    "concise",
      -    "detailed"
      -  ],
      -  "type": "string"
      -}
  4. Changed1 schema field changed
    • addedInput schema / properties / cache
      Added value: +{
      +  "description": "false forces a fresh, billed extract.",
      +  "type": "boolean"
      +}
  5. Changed1 schema field changed
    • changedInput schema / properties / ask / description
      Previous value: -"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`."New value: +"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`. No transcript (e.g. Pinterest): falls back to frames, `based_on`:[\"frames\"]."
  6. Changed2 schema fields changed
    • changedInput schema / properties / ask / description
      Previous value: -"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable."New value: +"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable. Long videos: answer draws on a relevance-selected/sampled subset, not just the head — see response `ask.coverage`."
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return; default [\"metadata\"]. Pulls: digest→transcript; audio_digest→digest→transcript; structured→transcript; comment_sentiment→comments. digest/audio_digest/structured/comment_sentiment: degrade to a warning, never charged, on failure. digest: gist+topics via LLM. audio_digest: mp3 of digest (signed URL, 24h); voice via `voice`; +`translate` for other-language audio. structured: chapters/entities/products_shown/claims/key_moments via vision LLM. comments: up to comments_cap; YouTube+Reddit only (else warning; see GET /v1/platforms). comment_sentiment: aggregated audience sentiment (positive_pct/neutral_pct/negative_pct/summary/top_themes); needs >=5 comments; same YouTube+Reddit limit. text_overlay: OCR per frame; requires \"frames\"; skipped above 200 frames. delta: velocity vs the previous fetch; first call seeds the baseline. Docs: https://framefetch.net/docs."New value: +"Which data to return; default [\"metadata\"]. Pulls: digest→transcript; audio_digest→digest→transcript; structured→transcript; comment_sentiment→comments. digest/audio_digest/structured/comment_sentiment: degrade to a warning, never charged, on failure. digest: gist+topics via LLM. audio_digest: mp3 of digest (signed URL, 24h); voice via `voice`; +`translate` for other-language audio. structured: chapters/entities/products_shown/claims/key_moments via vision LLM. comments: up to comments_cap; YouTube only (else warning; see GET /v1/platforms). comment_sentiment: aggregated audience sentiment (positive_pct/neutral_pct/negative_pct/summary/top_themes); needs >=5 comments; same YouTube-only limit. text_overlay: OCR per frame; requires \"frames\"; skipped above 200 frames. delta: velocity vs the previous fetch; first call seeds the baseline. Docs: https://framefetch.net/docs."
  7. Changed6 schema fields changed
    • changedInput schema / properties / ask / description
      Previous value: -"A question about the video (3-500 chars); returns a <=500-token answer grounded in the transcript with timestamped supporting quotes ({ answer, quotes: [{ t_sec, text }], confidence, based_on }) instead of a full transcript dump, auto-including \"transcript\" as its input, never served from the cache (a fresh answer every call, even when the underlying extraction is otherwise cached), and degrading gracefully (omitted, never charged) if no transcript is available or the model fails."New value: +"Question about the video (3-500 chars); <=500-token answer w/ timestamped quotes, grounded in the transcript (auto-pulled). Never cached; degrades (never charged) if unavailable."
    • changedInput schema / properties / comments_cap / description
      Previous value: -"Max number of top-level comments the \"comments\" field returns (1–200, default 100). Inert unless \"comments\" is requested."New value: +"Max top-level comments (1-200, default 100); only used with \"comments\"."
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"comments\" returns up to comments_cap top-level comments per video ({ items: [{ text, author?, like_count?, reply_count? }], total_fetched, cap_applied, sort:\"top\" }); it is INDEPENDENT of the transcript (no download) and available on YouTube and Reddit only — TikTok/Instagram/Pinterest return it as a warning, never a charge (check GET /v1/platforms). Author is a display handle only (no user ids/urls). \"comment_sentiment\" is aggregated audience sentiment: percentages, themes, summary — ONE LLM pass over the comments returns { positive_pct, neutral_pct, negative_pct (they sum to 100), summary (2-3 English sentences), top_themes (up to 5), representative { positive?, negative? } }. It automatically pulls in \"comments\" (its input; same YouTube/Reddit-only availability) and needs at least 5 comments — fewer, or a model failure, omits it with a warning and is never charged. No competitor offers this rollup. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return; default [\"metadata\"]. Pulls: digest→transcript; audio_digest→digest→transcript; structured→transcript; comment_sentiment→comments. digest/audio_digest/structured/comment_sentiment: degrade to a warning, never charged, on failure. digest: gist+topics via LLM. audio_digest: mp3 of digest (signed URL, 24h); voice via `voice`; +`translate` for other-language audio. structured: chapters/entities/products_shown/claims/key_moments via vision LLM. comments: up to comments_cap; YouTube+Reddit only (else warning; see GET /v1/platforms). comment_sentiment: aggregated audience sentiment (positive_pct/neutral_pct/negative_pct/summary/top_themes); needs >=5 comments; same YouTube+Reddit limit. text_overlay: OCR per frame; requires \"frames\"; skipped above 200 frames. delta: velocity vs the previous fetch; first call seeds the baseline. Docs: https://framefetch.net/docs."
    • changedInput schema / properties / subtitle_format / description
      Previous value: -"If set, also render the transcript as a subtitle file and add it as a top-level \"subtitles\" string (\"srt\" = SubRip, \"vtt\" = WebVTT). Requires \"transcript\" in fields (or \"digest\", which pulls it in); uses the translated cues when \"translate\" is set. Does not change any other field or the cost."New value: +"Renders transcript as subtitles in `subtitles` (srt/vtt). Requires \"transcript\" (or \"digest\"); uses translated cues if \"translate\" set."
    • changedInput schema / properties / translate / description
      Previous value: -"ISO-639-1 target language (e.g. \"es\", \"de\", \"ja\"); adds transcript_translated (the transcript translated into that language, with timings preserved). Requires \"transcript\" in fields (or \"digest\", which pulls transcript in). Billed per audio-minute like transcription, even for caption-sourced transcripts."New value: +"ISO-639-1 target language (e.g. \"es\"); adds `transcript_translated` (timings kept). Requires \"transcript\" (or \"digest\"). Billed per audio-minute."
    • changedInput schema / properties / voice / description
      Previous value: -"Spoken voice for the \"audio_digest\" field. The six OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) plus Groq/PlayAI's \"Fritz-PlayAI\". Defaults to \"alloy\". Inert unless \"audio_digest\" is requested."New value: +"Voice for \"audio_digest\": OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) + Groq \"Fritz-PlayAI\"; default \"alloy\"."
  8. Changed1 schema field changed
    • addedInput schema / properties / ask
      Added value: +{
      +  "description": "A question about the video (3-500 chars); returns a <=500-token answer grounded in the transcript with timestamped supporting quotes ({ answer, quotes: [{ t_sec, text }], confidence, based_on }) instead of a full transcript dump, auto-including \"transcript\" as its input, never served from the cache (a fresh answer every call, even when the underlying extraction is otherwise cached), and degrading gracefully (omitted, never charged) if no transcript is available or the model fails.",
      +  "maxLength": 500,
      +  "minLength": 3,
      +  "type": "string"
      +}
  9. Changed3 schema fields changed
    • addedInput schema / properties / comments_cap
      Added value: +{
      +  "description": "Max number of top-level comments the \"comments\" field returns (1–200, default 100). Inert unless \"comments\" is requested.",
      +  "maximum": 200,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"comments\" returns up to comments_cap top-level comments per video ({ items: [{ text, author?, like_count?, reply_count? }], total_fetched, cap_applied, sort:\"top\" }); it is INDEPENDENT of the transcript (no download) and available on YouTube and Reddit only — TikTok/Instagram/Pinterest return it as a warning, never a charge (check GET /v1/platforms). Author is a display handle only (no user ids/urls). \"comment_sentiment\" is aggregated audience sentiment: percentages, themes, summary — ONE LLM pass over the comments returns { positive_pct, neutral_pct, negative_pct (they sum to 100), summary (2-3 English sentences), top_themes (up to 5), representative { positive?, negative? } }. It automatically pulls in \"comments\" (its input; same YouTube/Reddit-only availability) and needs at least 5 comments — fewer, or a model failure, omits it with a warning and is never charged. No competitor offers this rollup. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "metadata",
      -  "insights",
      -  "transcript",
      -  "frames",
      -  "text_overlay",
      -  "digest",
      -  "audio_digest",
      -  "structured",
      -  "delta"
      -]New value: +[
      +  "metadata",
      +  "insights",
      +  "transcript",
      +  "frames",
      +  "text_overlay",
      +  "digest",
      +  "audio_digest",
      +  "structured",
      +  "comments",
      +  "comment_sentiment",
      +  "delta"
      +]
  10. Changed2 schema fields changed
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"structured\" is the video, understood: a vision LLM reads the transcript AND sampled keyframes and returns typed JSON — chapters ({ start_sec, end_sec, title, summary }), entities ({ name, type }), products shown ({ name, evidence: visual|spoken|both }), claims ({ text, timestamp_sec? }), and key moments ({ timestamp_sec, description }). It automatically pulls in \"transcript\" (one of its inputs) and also downloads the video for its own keyframe pass, so it works even on caption-less sources. Deterministic and cacheable; a flat per-video price. It degrades gracefully (omitted with a warning, never charged) if the model/parse fails. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "metadata",
      -  "insights",
      -  "transcript",
      -  "frames",
      -  "text_overlay",
      -  "digest",
      -  "audio_digest",
      -  "delta"
      -]New value: +[
      +  "metadata",
      +  "insights",
      +  "transcript",
      +  "frames",
      +  "text_overlay",
      +  "digest",
      +  "audio_digest",
      +  "structured",
      +  "delta"
      +]
  11. Changed3 schema fields changed
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"audio_digest\" is a spoken audio briefing of the video: it speaks the digest gist as an mp3 and returns { url, seconds, voice, provider, lang? } (mp3, signed URL, 24h TTL); it automatically pulls in \"digest\" (and thus \"transcript\"), and when \"translate\" is also set the digest is generated directly in that target language so the audio speaks it — combine \"audio_digest\" with \"translate\" for foreign-language audio, and pick the voice with the \"voice\" param. It degrades gracefully (omitted with a warning, never charged) if no digest is available or TTS fails. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "metadata",
      -  "insights",
      -  "transcript",
      -  "frames",
      -  "text_overlay",
      -  "digest",
      -  "delta"
      -]New value: +[
      +  "metadata",
      +  "insights",
      +  "transcript",
      +  "frames",
      +  "text_overlay",
      +  "digest",
      +  "audio_digest",
      +  "delta"
      +]
    • addedInput schema / properties / voice
      Added value: +{
      +  "description": "Spoken voice for the \"audio_digest\" field. The six OpenAI voices (alloy/echo/fable/onyx/nova/shimmer) plus Groq/PlayAI's \"Fritz-PlayAI\". Defaults to \"alloy\". Inert unless \"audio_digest\" is requested.",
      +  "enum": [
      +    "alloy",
      +    "echo",
      +    "fable",
      +    "onyx",
      +    "nova",
      +    "shimmer",
      +    "Fritz-PlayAI"
      +  ],
      +  "type": "string"
      +}
  12. Changed2 schema fields changed
    • addedInput schema / properties / subtitle_format
      Added value: +{
      +  "description": "If set, also render the transcript as a subtitle file and add it as a top-level \"subtitles\" string (\"srt\" = SubRip, \"vtt\" = WebVTT). Requires \"transcript\" in fields (or \"digest\", which pulls it in); uses the translated cues when \"translate\" is set. Does not change any other field or the cost.",
      +  "enum": [
      +    "srt",
      +    "vtt"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / translate
      Added value: +{
      +  "description": "ISO-639-1 target language (e.g. \"es\", \"de\", \"ja\"); adds transcript_translated (the transcript translated into that language, with timings preserved). Requires \"transcript\" in fields (or \"digest\", which pulls transcript in). Billed per audio-minute like transcription, even for caption-sourced transcripts.",
      +  "type": "string"
      +}
  13. Changed2 schema fields changed
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"digest\" is an LLM summary ({ gist, topics, state? }) of the transcript and automatically pulls in \"transcript\" (its input) — it degrades gracefully (omitted with a warning) if no transcript is available. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it. \"delta\" tracks a video over time: it compares this fetch against the previous one of the SAME url and returns { hasPrior, sinceTs, viewsPerHr, likesPerHr, commentsPerHr, titleChanged, thumbnailChanged } — the first fetch of a url just seeds the baseline (hasPrior:false); call again later to get the per-hour velocity and creator-edit flags."
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "metadata",
      -  "insights",
      -  "transcript",
      -  "frames",
      -  "text_overlay"
      -]New value: +[
      +  "metadata",
      +  "insights",
      +  "transcript",
      +  "frames",
      +  "text_overlay",
      +  "digest",
      +  "delta"
      +]
  14. Changed3 schema fields changed
    • changedInput schema / properties / fields / description
      Previous value: -"Which data to return. Default [\"metadata\"]. Request the minimum you need."New value: +"Which data to return. Default [\"metadata\"]. Request the minimum you need. \"text_overlay\" (on-screen text via OCR) requires \"frames\" to also be requested, and is auto-skipped (with a warning, not an error) above 200 estimated frames — OCR runs a subprocess per frame, so keep the frames spec narrow (fps/range) when you want it."
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "metadata",
      -  "insights",
      -  "transcript",
      -  "frames"
      -]New value: +[
      +  "metadata",
      +  "insights",
      +  "transcript",
      +  "frames",
      +  "text_overlay"
      +]
    • changedInput schema / properties / frames / description
      Previous value: -"Frame-sampling spec; required when \"frames\" is requested."New value: +"Frame-sampling spec; required when \"frames\" or \"text_overlay\" is requested."
  15. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the readOnlyHint/openWorldHint annotations: it discloses the return shape (only requested fields plus a micro-USD `cost` block), that cost scales with fields requested, that digest/audio_digest/structured/comment_sentiment degrade to warnings and are never charged on failure, the 24h signed-URL lifetime for audio, YouTube-only limits on comments, and two auth paths (instant key or x402). That is exactly the billing, auth, and partial-failure context the annotations cannot carry.

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-loaded with purpose, then exclusions, return shape, cost, auth, and an example — dense but each sentence carries information. The credential-acquisition and docs-URL tail is slightly off-topic for a tool description and adds length without aiding invocation.

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 9-parameter tool with a nested object and no output schema, the description covers return shape, cost model, failure/degradation semantics, caching, and auth, and defers only the detailed response field shapes to the docs URL. Nothing an agent needs before calling is missing.

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 the baseline is 3; the description adds real meaning on top by explaining the field dependency chain (digest→transcript, audio_digest→digest→transcript), relative cost of frames/transcript vs metadata, and a concrete call example. It leaves the nested `frames` spec and `ask` entirely to the schema, which is acceptable at full coverage.

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?

"Extract data from ONE public social-video URL" gives a specific verb, resource, and cardinality, then enumerates supported platforms (YouTube/Shorts, TikTok, Instagram Reels) and the field classes available. An agent can immediately tell this is the single-URL extraction tool rather than an account or search tool.

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?

Explicit exclusions are given: "non-video pages, private/login-walled content, or bulk crawling (one URL per call)," plus "cache: false forces a fresh, billed extract" and per-field prerequisites. It stops short of naming the alternatives — it points at REST endpoints (POST /v1/keys, GET /v1/platforms) instead of the sibling tools framefetch_account and framefetch_platform_capabilities, so routing still needs inference.

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.