Skip to main content
Glama
YouTube MCP Server

YouTube MCP Server

Get audience insights (OAuth)

get_audience_insights
Read-onlyIdempotent

Retrieve YouTube audience insights by country, city, device, playback location, traffic source, subscriber status, content type, sharing, and cards; narrow results to a date range or specific video.

Instructions

Who watches and how: countries, cities, devices, playback locations (incl. embeds on websites), traffic sources, subscribers vs not, Shorts vs long-form, sharing, cards.

Each breakdown lists rows sorted by views with their share of the total. Requires OAuth.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_audience_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNoWhen no dates are given: the last N days ending today.
limitNoRows per breakdown, 1-250 (embedding/external sites stop at 25).
end_dateNoEnd date YYYY-MM-DD, inclusive.
video_idNoNarrow every breakdown to one video on your channel.
breakdownsNoSubset of: countries (Views by viewer country (ISO code).), cities (Views by viewer city.), devices (Mobile, desktop, tablet, TV, ...), operating_systems (Android, iOS, Windows, ...), playback_locations (Where the video was played: YouTube watch page, Shorts feed, embedded, ...), embedding_sites (Websites that play the videos in an embedded player.), traffic_sources (How viewers found the videos: search, suggested, external, Shorts, ...), external_sites (Websites and apps that link viewers to the videos.), subscribed_status (Subscribers vs non-subscribers.), content_types (Shorts vs long-form vs live.), sharing_services (Where viewers share the videos: WhatsApp, copy link, ...), cards (Info card impressions, clicks and click rates.). Omit for: countries, devices, playback_locations, traffic_sources, subscribed_status, content_types.
start_dateNoStart date YYYY-MM-DD, inclusive. Omit both dates to use `days`.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful facts beyond them: that each breakdown returns rows sorted by views with their share of the total, and that OAuth is required. It stops short of noting pagination, truncation, or the 25-row cap on embedding/external sites, which lives only in the schema.

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?

A short lead fragment front-loads the scope, followed by one sentence on row format and one on the auth requirement. Every sentence earns its place, though the opening list is dense enough to be parsed as a run-on.

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

Completeness5/5

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

Six optional parameters, full schema coverage, an output schema and rich annotations mean the description need not restate parameter or return details. It supplies the scope, the result ordering and the auth prerequisite, which is what an agent needs to select and call it correctly.

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 description coverage is 100%, so the baseline is 3 and the schema already explains days, limit, dates, video_id and the full breakdown enum set. The description reinforces the breakdown vocabulary and adds the sorting/share semantics that the schema does not express, which is a modest value-add.

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?

The headline 'Who watches and how' plus an explicit enumeration of breakdowns (countries, cities, devices, playback locations, traffic sources, subscribers, content types, sharing, cards) makes the resource and its dimensions unambiguous. It never names a sibling such as get_video_analytics or get_channel_analytics, so the boundary between this tool and those is left unstated.

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?

Usage is implied by the enumerated breakdowns and by 'Requires OAuth', which flags a prerequisite. But there is no explicit when-to-use statement and no routing guidance against the many sibling analytics tools, so an agent must infer that this is the audience/demographics view rather than the performance or revenue view.

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