Skip to main content
Glama

SocialDataX YouTube MCP

youtube_search_videos

Read-only

按搜索词搜索 YouTube 公开视频,只返回视频结果。用户需要按搜索词查找视频时使用;已有视频、Shorts 或 youtu.be 链接时使用视频详情或评论工具;已有频道主页链接时使用频道资料或频道发布视频工具;不支持播放列表链接作为搜索输入;支持筛选和 page_token 翻页。

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": {
      "keyword": "<keyword>"
    },
    "name": "youtube_search_videos"
  }
}

Input Schema

NameRequiredDescriptionDefault
keywordYesYouTube 视频搜索词,可传关键词或短语,例如品牌名、话题、人物名或内容需求;不要传 YouTube 视频链接、Shorts 链接、频道链接、播放列表链接、video_id 或 page_token。
sort_typeNo排序方式:general=相关性,time_descending=最新上传,view_count_descending=观看次数最多,rating=评分较高。如无明确排序需求,保持 general。general
page_tokenNoYouTube 搜索分页令牌。首次请求留空。继续翻页时必须将上一页返回的完整 next_page_token 原样作为 page_token 传回;page_token 是不透明分页令牌;不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成,不得用省略号替换中间内容。只能用于同一关键词、排序和筛选链路;更换关键词、排序、视频类型、发布时间或时长筛选时,请清空 page_token 后从第一页重新搜索。
video_typeNo视频类型筛选:all=不限类型,video=普通视频,movie=电影。all 会保留视频类搜索结果,输出项用 video_type 标记可明确识别的类型。可明确识别的 Shorts 会标为 short,其余视频结果标为 video。当前不支持 channel、short 或 playlist 作为筛选项;频道信息只作为视频作者信息返回。movie 是筛选条件,返回项使用同一搜索结果字段,并以 video_type=movie 标记。如无明确类型需求,保持 all。all
duration_rangeNo视频时长筛选:all=不限,under_4_min=4 分钟以内,between_4_and_20_min=4 到 20 分钟,over_20_min=20 分钟以上。只对视频类搜索结果有意义;如无明确时长需求,保持 all。all
publish_time_rangeNo发布时间筛选:all=不限,last_hour=过去 1 小时,today=今天,this_week=本周,this_month=本月,this_year=今年。如无明确发布时间需求,保持 all。all

Output Schema

NameRequiredDescriptionDefault
itemsYes当前页 YouTube 搜索结果列表;当前页可能为空,是否可继续翻页以 next_page_token 是否为空为准。
pointsYes本次成功调用的积分消耗与账户积分余额。
next_page_tokenYes下一页不透明分页令牌;为空表示没有更多结果。继续翻页时必须将返回的完整 next_page_token 原样作为 page_token 传回;只用于当前 YouTube 搜索续页;不得修改、截断、缩写、脱敏、掩码、省略、规范化、重组或自行生成。

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / points / description
      Previous value: -"本次成功调用的积分消耗与调用完成时的账户积分余额。"New value: +"本次成功调用的积分消耗与账户积分余额。"
    • changedOutput schema / properties / points / properties / balance / description
      Previous value: -"本次接口完成时看到的当前积分余额,可为负数。"New value: +"优先返回调用完成时查询到的账户积分余额。查询失败时,回退到本次预扣后的余额快照。余额可为负数。"
  2. Changed2 schema fields changed
    • changedOutput schema / properties / points / properties / balance / description
      Previous value: -"本次接口完成时看到的当前积分余额。"New value: +"本次接口完成时看到的当前积分余额,可为负数。"
    • removedOutput schema / properties / points / properties / balance / minimum
      Removed value: -0
  3. Changed17 schema fields changed
    • addedOutput schema / properties / items / items / properties / author / properties / channel_id / title
      Added value: +"Channel Id"
    • addedOutput schema / properties / items / items / properties / author / properties / name / title
      Added value: +"Name"
    • addedOutput schema / properties / items / items / properties / author / properties / profile_url / title
      Added value: +"Profile Url"
    • addedOutput schema / properties / items / items / properties / author / title
      Added value: +"YoutubeAuthorSummaryData"
    • addedOutput schema / properties / items / items / properties / cover_image_url / title
      Added value: +"Cover Image Url"
    • addedOutput schema / properties / items / items / properties / duration_ms / title
      Added value: +"Duration Ms"
    • addedOutput schema / properties / items / items / properties / publish_time_text / title
      Added value: +"Publish Time Text"
    • addedOutput schema / properties / items / items / properties / share_url / title
      Added value: +"Share Url"
    • addedOutput schema / properties / items / items / properties / summary / title
      Added value: +"Summary"
    • addedOutput schema / properties / items / items / properties / title / title
      Added value: +"Title"
    • addedOutput schema / properties / items / items / properties / video_id / title
      Added value: +"Video Id"
    • addedOutput schema / properties / items / items / properties / video_type / title
      Added value: +"Video Type"
    • addedOutput schema / properties / items / items / properties / view_count / title
      Added value: +"View Count"
    • addedOutput schema / properties / items / items / title
      Added value: +"YoutubeSearchItemData"
    • addedOutput schema / properties / items / title
      Added value: +"Items"
    • addedOutput schema / properties / next_page_token / title
      Added value: +"Next Page Token"
    • addedOutput schema / title
      Added value: +"YoutubeVideoSearchResult"
  4. First observed

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that only public video results are returned, playlist links are unsupported, and pagination via page_token exists, but it does not disclose rate limits, quota cost, or result caps. Useful additions on top of annotations, though not rich.

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-loads the core action and result scope, then uses semicolon-delimited clauses for alternatives and constraints. Slightly dense as a single sentence, but every clause carries routing or constraint information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With four filters, pagination, and a 100%-covered schema plus an output schema, the description covers routing, scope, and pagination adequately. It need not explain return values given the output schema, though it could note whether filters compose or reset pagination (the schema does address the latter).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and all six parameters are documented in-schema, including enum meanings and page_token handling. The description only summarizes 'supports filters and page_token pagination' without adding semantics beyond what the schema already states, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (search YouTube public videos by keyword) and explicitly limits output to video results only. It names the sibling categories it is not (video detail, comments, channel tools), so an agent can distinguish it without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use triggers plus when-not conditions: existing video/Shorts/youtu.be links route to detail or comment tools, channel homepage links route to channel tools. Playlist links are explicitly rejected as input, leaving nothing to infer about routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources