Skip to main content
Glama

List videos

list_videos
Read-onlyIdempotent

Videos, newest first, with status and thumbnails A page at a time (limit, default 50): next_cursor is null on the last page, otherwise pass it as cursor for the next one with the same filters. counts says how many videos match song_id, artist_id, quote_id and q: all, and by type (lyric_video, canvas, music_video). Each video's outputs carry aspect_ratio, poster_url, poster_seconds and web_url (for thumbnails and previews); get_video has the download links. A video that is waiting has queue: why (plan_limit or render_capacity), its place in line or about how long.

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": "list_videos"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSearch the song title, artist name, Look name or video id
typeNo
limitNo
cursorNonext_cursor from the previous page
song_idNoOnly this song’s videos
quote_idNoOnly the videos this quote made (none until it is used)
artist_idNoOnly videos of this artist’s songs

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / quote_id
      Added value: +{
      +  "description": "Only the videos this quote made (none until it is used)",
      +  "format": "uuid",
      +  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +  "type": "string"
      +}
  2. Changed4 schema fields changed
    • addedInput schema / properties / artist_id
      Added value: +{
      +  "description": "Only videos of this artist’s songs",
      +  "maxLength": 120,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "next_cursor from the previous page",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / q
      Added value: +{
      +  "description": "Search the song title, artist name, Look name or video id",
      +  "maxLength": 100,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / type / enum
      Previous value: -[
      -  "lyric-video",
      -  "canvas"
      -]New value: +[
      +  "lyric-video",
      +  "canvas",
      +  "music-video"
      +]
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuine value beyond that: next_cursor is null on the last page, the counts object is broken down by type, outputs carry aspect_ratio/poster_url/poster_seconds/web_url, and queued videos expose a queue reason (plan_limit or render_capacity) with position or ETA. It does not enumerate status values or say how empty results look.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is dense and front-loads paging, which is good, but the prose is fragmentary and run-on — the first sentence lacks punctuation between "thumbnails" and "A page at a time", and several clauses drop their verbs. Density is achieved at the cost of parseability.

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?

There is no output schema, so the description has to describe return shape and it largely does: status, thumbnails, counts, per-video outputs, and the queue sub-object for pending videos. Only the set of possible status values and the empty-result behavior are unaddressed.

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?

With 71% schema coverage, the description fills real gaps: it supplies the limit default of 50 and its paging role, and explains that counts aggregate across song_id, artist_id, quote_id and q. However, it names the type values as "lyric_video, canvas, music_video" while the schema enum uses hyphens ("lyric-video", "music-video"), an inconsistency that could cause malformed calls.

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?

"Videos, newest first, with status and thumbnails, a page at a time" identifies the resource, the sort order and the pagination model. It also distinguishes itself from get_video for download links. The opening is a verbless fragment, so the reader must infer "list" from the tool name rather than the text.

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

Usage Guidelines4/5

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

It routes one concrete need to a sibling ("get_video has the download links") and explains exactly how to continue paging with the same filters. It does not state when to prefer this over wait_for_video, show_video or the list_music_video_* siblings, so the higher-level selection guidance is incomplete.

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