一个托管的 Model Context Protocol 服务器，让 AI 代理能够阅读 YouTube 视频——并引用它获得答案的确切秒数。
语言模型无法观看视频。将其指向此端点，它就能获得九个工具，用于搜索转录文本、读取视频的帧——幻灯片、图表、演示、屏幕上的文字——并在你看到之前验证引用后回答问题。
无需集成代码。无需抓取。无需代理池。
POST https://vidwords.com/mcp
Authorization: Basic <your-api-token>仅远程且托管——无需安装或自托管。此仓库是该端点的公开清单、配置参考和问题跟踪器。
获取免费令牌：在 vidwords.com/register 创建账户，验证你的电子邮件，然后从你的个人资料中复制令牌。免费计划包含每月积分和 10 个观看分钟，因此你可以在付费之前就完成配置并使用。
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"不要使用
bearer_token_env_var。它看起来是明显的字段，但它会发送Authorization: Bearer <value>，而此服务器使用 Basic 进行身份验证。
将 https://vidwords.com/mcp 添加为自定义连接器。主机自行注册，将你发送到 VidWords 登录，并显示一个同意屏幕，明确说明它请求的内容。仅注册不会授予任何权限——只有已登录的用户点击 批准 后访问才会开始，并且可以从你的 API 页面立即撤销实时连接。
此仓库还附带一个小的 stdio 代理（src/index.js），它在 stdin/stdout 上使用 MCP 协议，并将工具调用转发到托管端点。当你的客户端无法发送自定义 HTTP 标头，或者你希望将服务器放在容器中时，请使用它：
{
"mcpServers": {
"vidwords": {
"command": "npx",
"args": ["-y", "github:haljishi/vidwords-mcp"],
"env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" }
}
}
}直接从本仓库运行——该代理未发布到 npm，因此裸
npx @vidwords/mcp将无法解析。
docker build -t vidwords-mcp .
docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcp工具模式在代理中内联声明，因此 initialize 和 tools/list 无需任何凭据即可响应，并且在实际调用工具之前不会联系上游。没有 VIDWORDS_API_TOKEN 的调用会返回可读的错误，而不是使握手失败。VIDWORDS_MCP_URL 可覆盖端点，如果你指向非生产实例。
通用的 mcp-remote 桥接器也可以工作：
{
"mcpServers": {
"vidwords": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
"--header", "Authorization:Basic YOUR_API_TOKEN"]
}
}
}现成的配置文件位于 examples/。
Related MCP server: vidtheque
工具 | 功能 | 费用 |
| 查找一个视频讨论某内容的位置。返回带有时间戳的匹配时刻、引用的上下文，以及 | 1 积分 |
| 一次调用获取最多 25 个视频的完整转录文本。 | 每个视频 1 积分 |
| 将频道句柄、URL 或 | 免费 · 入门版及以上 |
| 账户的 Radar 监视列表以及每个列表已记录的内容。 | 免费 |
| Radar 为一个监视列表记录的最新视频。 | 免费 |
| 计划和剩余积分，以便代理在运行前评估任务成本。 | 免费 |
| 开始帧级分析——幻灯片、图表、演示和屏幕上的文字，而不仅仅是字幕。立即返回 | 观看分钟 |
| 读取已完成的分析：章节、关键点、带时间戳的证据。 | 免费 |
| 针对已完成的分析提问。引用会对照存储的证据进行验证，否则丢弃。 | 1 个观看问题 |
search_transcript 而不是 get_transcript两者每个视频都花费 1 积分，因此没有计费上的理由来选择。原因是上下文。问“这个两小时的采访关于定价说了什么？”get_transcript 会返回大约 20,000 个单词，其中可能只有 300 个是关于定价的——这 300 个现在要与 19,700 个无关的单词竞争注意力，答案会变得更差、更慢、生成成本更高。
search_transcript 只返回匹配的片段，每个片段都带有深度链接。当你确实想要整个文本时——导出、差异、语料库——才使用 get_transcript。
analyze_video 会查看幻灯片、图表、代码示例和从未被说出的屏幕文字。ask_video 然后根据存储的分析进行回答，并且每个引用在你看之前都会被检查：视觉声明必须匹配实际记录的帧，口头声明必须落在真实的转录片段上。任何失败的都会被丢弃，当没有内容幸存时，答案会说明证据不足，而不是产生自信的猜测。
这有时会令人恼火——拒绝比流畅的回答更糟糕的演示——但这是该功能唯一可以安全地放在代理面前的版本，因为代理会重复被告知的内容，而没有人类读者会有的怀疑态度。
Basic，而不是 Bearer。 令牌按原样发送；你不需要对 user:pass 对进行 base64 编码。
首先验证你的电子邮件。 在你点击验证链接之前，每次调用都会返回 403，并带有 {"error":"email_unverified"}——这是新账户最常见的首次调用失败。
积分是一个池，与 REST API 和网站共享。一个积分对应一个转录。帧分析改为消耗观看分钟，而在开始前被拒绝的运行不花费任何费用。
速率限制：30 个请求 / 10 秒——故意比 REST API 的 5 个更宽松，因为服务器是无状态的，客户端在每次调用前都会重新运行 initialize。analyze_video 有自己的上限，每分钟 10 次启动，与 REST 路由共享。
此处拒绝 RapidAPI 令牌。 该身份按调用计费，并且背后没有账户，这两者都无法在工具调用会话中存活。请使用 VidWords API 令牌。
设计上无状态。 没有可恢复的 SSE 流，没有要删除的会话；每个工具一次性回答。GET 和 DELETE 返回 JSON-RPC 错误，而不是 HTML 404。
字幕必须存在。 对于没有字幕轨道的视频，已登录账户可以改为从音频转录——按长度定价，在你花费之前报价。
完整数字：定价。
在此处针对 MCP 表面的任何问题打开 issue——行为异常的工具、我们未记录配置的客户端、可以更清晰的模式。账户和计费问题请前往 支持。
本仓库的内容（文档和配置示例）采用 MIT 许可证。托管服务本身是专有的，并受 VidWords 条款 约束。
独立产品；与 YouTube 或 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.