Skip to main content
Glama
Crawlora-org

Crawlora MCP

Official
by Crawlora-org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

youtube_search

Search YouTube for videos, shorts, channels, playlists, or movies by query. Filter by upload date, duration, type, and features, then paginate results with a continuation token.

Instructions

Search YouTube. Returns normalized YouTube search results using YouTube's InnerTube search API. Pass continuation_token from a previous response to retrieve the next page. Use q as the primary query parameter; search_query is accepted as an alias. hl and gl localize ranking and result context; they default to en and US. Named filters cover the public web search filters. Account-only chips such as Watched and Unwatched are not exposed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoSearch query
glNoTwo-letter YouTube region code
hlNoYouTube interface language
typeNoFilter by type
paramsNoRaw protobuf-encoded search filter (base64)
sort_byNoSort results
durationNoFilter by duration; short, medium, and long preserve their previous upstream encodings
featuresNoComma-separated feature filters. Allowed values: live, 4k, hd, subtitles, cc, creative_commons, 360, vr180, 3d, hdr, location, purchased
upload_dateNoFilter by upload date
search_queryNoAlias for q
continuation_tokenNoPagination token returned by a previous request

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.17.5
    • changedInput schema / properties / duration / description
      Previous value: -"Filter by duration"New value: +"Filter by duration; short, medium, and long preserve their previous upstream encodings"
    • addedInput schema / properties / duration / enum
      Added value: +[
+  "under_3_minutes",
+  "three_to_20_minutes",
+  "over_20_minutes",
+  "under_3",
+  "three_to_20",
+  "over_20",
+  "short",
+  "medium",
+  "long"
+]
    • changedInput schema / properties / features / description
      Previous value: -"Comma-separated feature filters"New value: +"Comma-separated feature filters. Allowed values: live, 4k, hd, subtitles, cc, creative_commons, 360, vr180, 3d, hdr, location, purchased"
    • addedInput schema / properties / gl
      Added value: +{
+  "description": "Two-letter YouTube region code",
+  "type": "string"
+}
    • addedInput schema / properties / hl
      Added value: +{
+  "description": "YouTube interface language",
+  "type": "string"
+}
    • addedInput schema / properties / sort_by / enum
      Added value: +[
+  "relevance",
+  "upload_date",
+  "view_count",
+  "popularity",
+  "rating"
+]
    • addedInput schema / properties / type / enum
      Added value: +[
+  "video",
+  "shorts",
+  "channel",
+  "playlist",
+  "movie"
+]
    • addedInput schema / properties / upload_date / enum
      Added value: +[
+  "last_hour",
+  "today",
+  "this_week",
+  "this_month",
+  "this_year"
+]
  2. First observedv1.0.0

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations, the description carries the full disclosure burden and delivers several important behaviors: it names the underlying InnerTube API, explains pagination via continuation_token, documents localization defaults, and scopes filters to public web search only. It omits rate limits, auth requirements, and error behavior, which keeps it short of a 5.

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?

Five sentences, each earning its place, with the purpose front-loaded in the first sentence. It is slightly longer than strictly necessary, but for an 11-parameter surface the density is appropriate and there is no fluff.

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

Completeness3/5

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

For a tool with 11 optional params, no annotations, and no output schema, the description covers the essentials — pagination, defaults, and filter scope — but leaves clear gaps: no guidance on parameter interactions (e.g., params vs named filters), no rate-limit/auth context, and no differentiation from youtube_channel_search in the sibling list.

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, but the description adds genuine value beyond the schema: it establishes q as primary with search_query as an alias, documents hl/gl defaults, and explains continuation_token's pagination role. These parameter relationships and defaults are not inferable from the schema alone.

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

Purpose4/5

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

'Search YouTube. Returns normalized YouTube search results' states a specific verb and resource, and the InnerTube API mention adds specificity about the mechanism. However, it never explicitly names or distinguishes sibling tools like youtube_channel_search or youtube_video, so an agent must infer how this platform-wide search differs from channel-scoped search.

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

Usage Guidelines3/5

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

The description gives useful parameter-level guidance (q is primary, search_query is an alias; hl/gl default to en/US) and notes the account-only filter limitation, which implies a boundary on what the tool can do. But it never tells an agent when to choose this tool over youtube_channel_search or any other youtube_* sibling, so the when-to-use-vs-alternatives question is left to inference.

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

Deploy Server

Other Tools