Un servidor alojado de Model Context Protocol que permite a un agente de IA leer vídeos de YouTube — y citar el segundo exacto del que obtuvo la respuesta.
Un modelo de lenguaje no puede ver un vídeo. Apúntalo a este endpoint y obtiene nueve herramientas para buscar transcripciones, leer los fotogramas de un vídeo — diapositivas, gráficos, demos, texto en pantalla — y responder preguntas con citas que se verifican antes de que las veas.
Sin código de integración. Sin scraping. Sin grupo de proxies.
POST https://vidwords.com/mcp
Authorization: Basic <your-api-token>Solo remoto y alojado: no hay nada que instalar ni autoalojar. Este repositorio es el manifiesto público, la referencia de configuración y el rastreador de incidencias para ese endpoint.
Obtén un token gratuito: crea una cuenta en vidwords.com/register, verifica tu correo electrónico y luego copia el token de tu perfil. El plan gratuito incluye créditos mensuales y 10 minutos de Watch, así que puedes configurarlo y usarlo antes de pagar nada.
claude mcp add --transport http vidwords https://vidwords.com/mcp \
--header "Authorization: Basic YOUR_API_TOKEN"claude_desktop_config.json{
"mcpServers": {
"vidwords": {
"type": "http",
"url": "https://vidwords.com/mcp",
"headers": { "Authorization": "Basic YOUR_API_TOKEN" }
}
}
}.cursor/mcp.json{
"mcpServers": {
"vidwords": {
"url": "https://vidwords.com/mcp",
"headers": { "Authorization": "Basic YOUR_API_TOKEN" }
}
}
}~/.codex/config.toml[mcp_servers.vidwords]
url = "https://vidwords.com/mcp"
env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"No uses
bearer_token_env_var. Es el campo que parece obvio, pero envíaAuthorization: Bearer <valor>y este servidor autentica con Basic.
Añade https://vidwords.com/mcp como conector personalizado. El host se registra solo, te envía a
VidWords para iniciar sesión y muestra una pantalla de consentimiento que nombra exactamente lo que pide.
El registro por sí solo no concede nada: el acceso comienza solo cuando una persona con sesión iniciada hace clic en Aprobar,
y las conexiones activas se pueden revocar desde tu página de API con efecto inmediato.
Este repositorio también incluye un pequeño proxy stdio (src/index.js) que habla MCP por
stdin/stdout y reenvía las llamadas de herramientas al endpoint alojado. Úsalo cuando tu cliente no pueda
enviar una cabecera HTTP personalizada, o cuando quieras el servidor en un contenedor:
{
"mcpServers": {
"vidwords": {
"command": "npx",
"args": ["-y", "github:haljishi/vidwords-mcp"],
"env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" }
}
}
}Ejecuta directamente desde este repositorio: el proxy no está publicado en npm, así que un simple
npx @vidwords/mcpno se resolverá.
docker build -t vidwords-mcp .
docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcpLos esquemas de las herramientas se declaran en línea en el proxy, por lo que initialize y tools/list
responden sin credenciales y no se contacta con el upstream hasta que se llama realmente a una herramienta.
Una llamada sin VIDWORDS_API_TOKEN devuelve un error legible en lugar de fallar el
handshake. VIDWORDS_MCP_URL anula el endpoint si apuntas a una instancia que no es de producción.
El puente genérico mcp-remote también funciona:
{
"mcpServers": {
"vidwords": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
"--header", "Authorization:Basic YOUR_API_TOKEN"]
}
}
}Los archivos de configuración listos están en examples/.
Related MCP server: vidtheque
Herramienta | Qué hace | Costo |
| Encuentra dónde un vídeo discute algo. Devuelve los momentos coincidentes con marcas de tiempo, contexto citado y enlaces profundos | 1 crédito |
| Texto completo de la transcripción para hasta 25 vídeos en una sola llamada. | 1 crédito por vídeo |
| Resuelve un identificador de canal, URL o id | Gratis · Starter y superior |
| Las listas de seguimiento Radar de la cuenta y cuánto ha registrado cada una. | Gratis |
| Subidas más recientes que Radar ha registrado para una lista de seguimiento. | Gratis |
| Plan y créditos restantes, para que el agente pueda calcular el costo de un trabajo antes de ejecutarlo. | Gratis |
| Inicia un análisis a nivel de fotograma: diapositivas, gráficos, demos y texto en pantalla, no solo subtítulos. Devuelve un | Minutos de Watch |
| Lee un análisis terminado: capítulos, puntos clave, evidencia con marca de tiempo. | Gratis |
| Haz una pregunta sobre un análisis terminado. Las citas se verifican contra la evidencia almacenada o se descartan. | 1 pregunta de Watch |
search_transcript sobre get_transcriptAmbos cuestan un crédito por vídeo, así que no hay razón de facturación para elegir. La razón es el contexto.
Pregunta "¿qué dijo esta entrevista de dos horas sobre precios?" y get_transcript devuelve aproximadamente
20,000 palabras, de las cuales quizás 300 son sobre precios — esas 300 ahora compiten por atención con
19,700 que no lo son, y la respuesta empeora, se vuelve más lenta y más cara de generar.
search_transcript devuelve solo los tramos coincidentes, cada uno con un enlace profundo. Recurre a
get_transcript cuando realmente quieras el texto completo: una exportación, un diff, un corpus.
analyze_video examina diapositivas, gráficos, ejemplos de código y texto en pantalla que nunca se dice
en voz alta. ask_video luego responde basándose en ese análisis almacenado, y cada cita se verifica
antes de que la veas: una afirmación visual tiene que coincidir con un fotograma que realmente se grabó,
una afirmación hablada tiene que aterrizar en un segmento real de transcripción. Cualquier cosa que falle se descarta, y cuando nada
sobrevive, la respuesta dice que la evidencia es insuficiente en lugar de producir una suposición segura.
Eso es ocasionalmente molesto — una negativa es una demostración peor que una respuesta fluida — y es la única versión de esta función que es segura de poner frente a un agente, porque un agente repite lo que se le dice sin el escepticismo que aplica un lector humano.
Basic, no Bearer. El token se envía tal cual; no codificas en base64 un par usuario:contraseña.
Verifica tu correo primero. Hasta que hagas clic en el enlace de verificación, cada llamada devuelve 403
con {"error":"email_unverified"} — el fallo más común en la primera llamada de una cuenta nueva.
Los créditos son un solo grupo compartido con la API REST y el sitio web. Un crédito es una transcripción. El análisis de fotogramas consume minutos de Watch en su lugar, y una ejecución rechazada antes de comenzar no cuesta nada.
Límite de velocidad: 30 solicitudes / 10s — deliberadamente más flexible que el 5 de la API REST, porque el servidor
es sin estado y un cliente vuelve a ejecutar initialize antes de cada llamada. analyze_video tiene su propio
límite de 10 inicios por minuto, compartido con la ruta REST.
Los tokens de RapidAPI se rechazan aquí. Esa identidad se mide por llamada y no tiene cuenta detrás, y ninguna de las dos cosas sobrevive a una sesión de llamada de herramientas. Usa un token de API de VidWords.
Sin estado por diseño. Sin flujos SSE reanudables, sin sesión que eliminar; cada herramienta responde en
una sola vez. GET y DELETE devuelven un error JSON-RPC en lugar de un 404 HTML.
Los subtítulos tienen que existir. Para un vídeo sin pista de subtítulos, una cuenta con sesión iniciada puede transcribir desde el audio en su lugar — con precio por duración, cotizado antes de que gastes.
Números completos: precios.
Abre una incidencia aquí para cualquier cosa sobre la superficie MCP: una herramienta que se comporta mal, un cliente cuya configuración no hemos documentado, un esquema que podría ser más claro. Las preguntas de cuenta y facturación van a soporte.
El contenido de este repositorio (documentación y ejemplos de configuración) tiene licencia MIT. El servicio alojado en sí es propietario y se rige por los términos de VidWords.
Producto independiente; no afiliado con YouTube o Google.
The plan and credit balance for the calling token. Free. Check this before a large batch so you can tell the user what a job will cost instead of failing partway through it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces this by stating it is 'Free' and focused on credit balance. It additionally explains the practical benefit (avoiding failures), which goes beyond the annotations.
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 brief, using two sentences to convey purpose and usage. No redundant or irrelevant information is present.
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, the description sufficiently explains what the tool returns (plan and credit balance) and provides actionable context about when to invoke it. It is complete for its simplicity.
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 tool has no parameters, so schema coverage is 100%. The description adds no parameter-specific details, but there is nothing to explain. Baseline 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 tool's function: retrieving the plan and credit balance for the calling token. It distinguishes from sibling tools (search, transcripts, videos, etc.) by focusing on account information.
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 explicitly advises checking the account before a large batch to avoid unexpected costs, giving a clear when-to-use directive. Although it doesn't mention alternatives, the tool's unique purpose makes this unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a deep visual analysis of a YouTube video: chapters, key moments, on-screen text and evidence tied to exact timestamps. Reads the picture, not just the captions, so it can answer questions about a slide, chart or demo the transcript never mentions. Spends Watch minutes from the plan. Returns immediately with an analysisId — analysis takes minutes, so poll get_analysis rather than waiting. If the video was analyzed before, it comes back ready at once.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Detail level. "auto" picks one from the video’s length and visual pace. "deep" needs a Pro or Advanced plan. | smart |
| video | Yes | YouTube video URL or 11-character video id | |
| partial | No | If the video is longer than the plan allows, analyze only the first allowed minutes and charge for those instead of refusing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that this operation spends Watch minutes, returns immediately with an analysisId, completes asynchronously, and reuses prior results if the video was analyzed before. These are essential behavioral details that the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense: it covers purpose, visual evidence value, cost, asynchronous polling, and caching in roughly five sentences. Every sentence adds meaningful guidance, and there is no redundant restatement of annotations or schema names.
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 no output schema, the description still tells the agent what the analysis will contain and how to coordinate with get_analysis for the final result. The async handoff, cost, and cached-result behavior make the full workflow clear and actionable.
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 already documents all three parameters completely, including mode values, defaults, and the meaning of partial and video. The description does not add new parameter-specific details, though it gives helpful high-level context about the analysis result and cost behavior.
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 opens with a specific verb and resource: "Start a deep visual analysis of a YouTube video" and lists concrete outputs such as chapters, key moments, on-screen text, and timestamped evidence. It distinguishes itself from sibling tools like search_transcript and get_transcript by stressing that it reads the picture, not just captions.
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 clearly states when to use this tool: when the transcript misses visual content like slides, charts, or demos. It also explicitly tells the agent to poll get_analysis rather than waiting, and notes that previously analyzed videos return ready immediately. It does not mention at all the exact alternative transcript tools other than implicating them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask a question against a finished analysis and get an answer whose citations are verified against the stored evidence: a visual claim must match a real recorded frame and a spoken one a real transcript segment, or it is dropped. When nothing survives, the answer says the evidence is insufficient rather than guessing. Spends one Watch question from the plan.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| analysisId | Yes | The analysisId returned by analyze_video |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral details beyond annotations: citations are verified, and if nothing survives it 'says the evidence is insufficient rather than guessing', plus it consumes a quota. The annotations only indicate non-read-only and non-idempotent, so the description adds critical information about evidence verification and fallback behavior.
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 dense sentences that front-load the core purpose and verification logic, then add the cost. Every clause earns its place; no fluff.
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 covers purpose, prerequisites, cost, and fallback behavior, which is quite complete for a query tool. However, it doesn't detail return format or what happens on invalid input, though the lack of an output schema makes some of this less critical.
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 analysisId with a description, but question has no description. The tool description does not elaborate on the question parameter beyond being a question. With 50% schema coverage, the description adds minimal value for parameters, though it implies the question is a natural language query.
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's function: 'Ask a question against a finished analysis' and explains the unique behavior of verifying citations against stored evidence. This distinguishes it from siblings like get_analysis or search_transcript.
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?
It specifies that the analysis must be 'finished', implying a prerequisite, and mentions the cost ('Spends one Watch question from the plan'). However, it doesn't explicitly contrast with alternatives like get_analysis or search_transcript, though the context makes it clear this is for post-analysis Q&A.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the analysis started by analyze_video. Free. While status is "queued" or "processing" the analysis field is absent — poll again. When "ready" it contains the summary, chapters, key points and timestamped evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| analysisId | Yes | The analysisId returned by analyze_video |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description earns full credit for adding the async state machine: statuses 'queued,' 'processing,' and 'ready' control whether the analysis field is absent or present, plus the payload contents when ready. No contradiction with annotations; the title and description are consistent.
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?
Three short, information-dense sentences: purpose, async status behavior, and payload contents. Every clause earns its place without filler or 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?
For an async fetch operation with a single param, the description fully covers the lifecycle including the 'Free' cost qualifier, the polling conditions, and the result shape (summary, chapters, key points, timestamped evidence). With no output schema present, the description adequately completes the return contract.
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% and single-param, so the baseline 3 applies without any downside. The description reiterates the analyze_video relationship but adds no format, range, or default guidance beyond what the schema's own note 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?
Uses a specific verb ('Fetch') + resource ('analysis') and anchors it to 'started by analyze_video,' which clearly distinguishes it from sibling analyze_video/ask_video. The title 'Read a finished video analysis' further disambiguates its read-only role without restating the tool name.
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 the polling workflow ('poll again... when ready'), establishing when this tool is appropriate in the analysis lifecycle relative to the create operation. It does not explicitly name alternatives with when-not-to-use exclusions, though 'started by analyze_video' hints at the create/read pairing with its sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the complete transcript text for one or more YouTube videos. Costs 1 credit per video. Prefer search_transcript when you only need the parts about a specific topic — full transcripts of long videos are large and mostly irrelevant to the question.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Preferred caption language code, e.g. "en", "es". | en |
| videos | Yes | YouTube video URLs or ids (max 25 per call) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and idempotentHint=false, suggesting side effects (credit consumption), but the description adds explicit cost per video and warns about large payload sizes. It does not contradict annotations, and adds context beyond them, though it could mention that the full transcript is returned in one response or potential truncation. Still, the added cost and size warnings give useful behavioral insight.
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 two sentences, front-loaded with the primary purpose, followed by cost and a usage guideline. No unnecessary words or repetition; every sentence earns its place. It achieves high information density in minimal space.
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 tool's simplicity (2 params, no output schema), the description covers the essential aspects: purpose, cost, and when to use an alternative. It does not describe error conditions or return formatting, but with no output schema and clear schema descriptions, this is acceptable. Sibling tool context is referenced. A slightly higher score would require mention of response format or edge cases, but the existing content is sufficient for most scenarios.
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 already provides full descriptions for both parameters ('lang' and 'videos'), covering their types, defaults, and constraints (max 25 items). Since schema coverage is 100%, the description adds marginal value—it only restates that one or more videos are accepted and notes 'complete transcript' as output, but does not explain parameter formats beyond the schema. Baseline of 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?
The description clearly states the tool fetches complete transcript text for one or more YouTube videos, using the specific verb 'Fetch' and resource 'transcript text'. It distinguishes itself from the sibling tool search_transcript by explicitly mentioning when to prefer that alternative, so the purpose is unambiguous and well-scoped.
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 provides explicit usage guidance: it names the alternative tool (search_transcript) and explains when NOT to use this tool (when only topic-specific parts are needed), including a rationale (full transcripts are large and mostly irrelevant). It also notes the cost (1 credit per video), helping the agent decide based on resource trade-offs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a YouTube channel handle, URL or id to its recent uploads. Free — no credits are spent. Requires the Starter plan or higher.
| Name | Required | Description | Default |
|---|---|---|---|
| channel | Yes | Channel @handle, URL, or UC… id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral context: the operation is free, does not spend credits, requires a Starter plan, and only returns recent uploads. This helps an agent understand cost and entitlement implications without repeating annotation data.
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 concise, front-loaded sentences state the core action, accepted input forms, cost behavior, and plan requirement. Every sentence carries useful information with no redundancy or filler.
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 one-parameter, read-only tool with good annotations and a clear description, the content fully covers purpose, input, cost, and access restrictions. No output schema exists, but for a list operation this is acceptable; the description is complete for tool selection and invocation.
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 schema fully documents the single parameter ('Channel @handle, URL, or UC… id'), and the description repeats that same input guidance. Since schema coverage is 100%, the description adds no significant additional semantic value 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 uses a specific verb ('Resolve') with a clear resource ('a YouTube channel handle, URL or id') and result ('recent uploads'). It clearly distinguishes this from sibling tools that handle transcripts, watchlists, or analysis.
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?
It clearly states when to use the tool: to resolve a channel handle/URL/id to recent uploads, and adds access context ('Requires the Starter plan or higher'). It does not explicitly name alternatives or when-not-to-use it, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account’s Radar watchlists — the YouTube channels it monitors for new uploads — with how many new videos each has recorded. Free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by specifying the output (watchlists and new-video counts) and the 'Free' qualification, which goes beyond the schema. No contradiction with annotations.
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 using an em-dash to add detail, with the key resource front-loaded. Every word contributes meaning, making it highly concise and well-structured.
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 read-only list tool with no parameters and no output schema, the description adequately explains the output (watchlists and new-video counts) and scope (account's Radar watchlists). The 'Free' note is slightly ambiguous but does not detract from overall 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?
The input schema has zero parameters, so there is no parameter semantics to explain. The baseline for no-parameter tools is 4, and the description appropriately avoids adding unnecessary parameter details.
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 identifies the resource (Radar watchlists) and the return metric (new video counts), making it distinct from sibling tools like list_channel_videos. It uses a specific noun phrase that effectively conveys the tool's function.
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 provides context about what the tool does but does not explicitly state when to use it over alternatives. It implies its role by describing the watchlists, but lacks explicit guidance on choosing it versus sibling tools like watchlist_activity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search one YouTube video for a phrase or topic and return the matching moments with timestamps and deep links you can cite. Costs 1 credit per video (the transcript is fetched to search it). Use this instead of get_transcript when the user asks what a video says about something.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Words to find. All terms must appear near each other; not a strict phrase match. | |
| video | Yes | YouTube video URL or 11-character video id | |
| contextSegments | No | How many caption segments of surrounding context to include with each match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=false and idempotentHint=false, but the description adds critical context: the tool costs 1 credit per video and that the transcript is fetched server-side to perform the search. Disclosing that this is a paid call addresses a primacy-of-information concern (cost before running). Could go higher with rate limits or error behavior, but the credit disclosure is meaningful and not derivable from annotations.
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?
Three focused sentences. The first states the action and output, the second discloses cost and mechanism, the third provides a routing rule. Every sentence earns its place with no redundancy or fluff.
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 tool with 100% schema documentation and meaningful annotations (readOnly=false, openWorld=true), the description is nearly complete. It covers the what, the cost, the routing, and hints at the output structure ('matching moments with timestamps and deep links'). Missing details like pagination or error handling are minor; the credit disclosure addresses the most operationally important non-obvious behavior. Returns are probably JSON, but the description's mention of 'cite' implies a usable structure.
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% and all parameters are documented in the JSON schema itself, so the description isn't required to repeat them. The description adds value by implying how 'query' relates to matching ('All terms must appear near each other') which is already in the schema, but the description's mention of 'phrase or topic' clarifies the semantic matching. The contextSegments parameter has a default and type in schema, so the 4 is justified because the schema carries the load and the description adds the credit-scope nuance.
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 uses a specific verb ('Search') with a clear resource ('one YouTube video') and outcome ('return the matching moments with timestamps and deep links you can cite'). It distinguishes itself from the sibling get_transcript by stating 'Use this instead of get_transcript when the user asks what a video says about something.'
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 states when to use this tool ('when the user asks what a video says about something') and names the alternative ('use instead of get_transcript'). It also provides a usage caveat about credits, which helps an agent decide when the cost is justified, going beyond a mere alternative mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The most recent videos Radar has recorded for one watchlist, newest first. Free. Pair with search_transcript to answer questions about what those videos said.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| watchlistId | Yes | Watchlist id from list_watchlists |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=true, and the description does not contradict that. It mentions ordering (newest first) and cost (Free), but does not detail side effects or output behavior. However, the read-only nature is adequately covered by annotations.
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 and well-structured, conveying the core functionality in two short sentences. It avoids unnecessary detail while remaining informative.
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 provides enough context for a straightforward retrieval tool, including the pairing advice for question-answering. It does not describe output schema, but that is not required given the simplicity and the lack of output schema definition.
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 watchlistId parameter has a clear description referencing list_watchlists, which is helpful. The limit parameter lacks a description but is self-explanatory as a numeric limit, so semantics are sufficiently clear.
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's function: retrieving the most recent videos recorded for a specific watchlist, ordered newest first. It also distinguishes itself from siblings by specifying 'one watchlist' and including the pairing hint with search_transcript.
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 provides a usage hint by suggesting pairing with search_transcript, but does not explicitly state when to use this tool versus alternatives like list_channel_videos or get_transcript. It implies usage but lacks direct guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.2accountanalyze_videoask_videoget_analysisget_transcriptlist_channel_videoslist_watchlistssearch_transcriptwatchlist_activityScored across 9 tools
Each tool has a unique and clear purpose. There is no overlap that would confuse an agent; get_transcript vs search_transcript, analyze_video vs get_analysis, and ask_video are distinctly separate operations.
Most tools follow a verb_noun pattern (search_transcript, get_transcript, list_channel_videos, analyze_video, ask_video), but 'watchlist_activity' and 'account' break the pattern, making the naming slightly inconsistent.
With 9 tools, the set is well-scoped for a video transcription and analysis service. It covers account management, transcript search/retrieval, channel listing, watchlist management, and analysis lifecycle without being excessive.
The tool surface covers all necessary operations: checking credits, retrieving and searching transcripts, listing channels and watchlists, and managing deep visual analysis (start, retrieve, query). No obvious gaps in the core domain are apparent.
Search and query the transcripts of YouTube expert channels you follow, with cited answers.
Search and cite timestamped YouTube and podcast transcripts; transcribe any video or episode.
YouTube search, whole channels, video stats, comments and full transcripts with timestamps.
YouTube frames at exact timestamps and the moments that answer a query, for AI agents.