Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get TV episode

get_tv_episode
Read-only

Retrieve details for a specific TV episode using show ID, season, and episode number, including overview, air date, runtime, guest stars, credits, and IMDb ID.

Instructions

Get one episode of a TV show by show id + season number + episode number: overview, air date, runtime, TMDB vote average (vote_average, TMDB's own 0-10 user score, not an IMDb/RT/Metacritic score; get_movie/get_tv's ratings are whole-show only and this tool makes no OMDb call), guest stars (up to 15) and director/writer. Also returns the episode's own imdb_id/imdb_url; pass that id to get_ratings for this episode's IMDb rating, the only way to get a per-episode IMDb score here. Get the show id from search_tv.

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": {
      "id": "<id>",
      "season_number": "<season_number>",
      "episode_number": "<episode_number>"
    },
    "name": "get_tv_episode"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesTMDB TV show id (from search_tv).
season_numberYesSeason number (0 = specials).
episode_numberYesEpisode number within the season.

Output Schema

NameRequiredDescriptionDefault
crewYes
nameYes
imdb_idYesThis episode's own IMDb id (not the show's) — pass it to get_ratings for the episode's IMDb rating, which no TMDB field carries. Null when TMDB has no IMDb id for it.
air_dateYes
imdb_urlYes
overviewYes
still_urlYes
guest_starsYes
vote_averageYesTMDB's own 0-10 user score. A different audience and scale from the IMDb/RT/Metacritic scores get_movie/get_tv return as `ratings` — don't compare, average or substitute across the two.
season_numberYes
episode_numberYes
runtime_minutesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.15.0
    • changedInput schema / properties / id / description
      Previous value: -"TMDB numeric id."New value: +"TMDB TV show id (from search_tv)."
  2. Changed20 schema fields changedv0.14.0
    • removedOutput schema / properties / episode_number / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / episode_number / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / guest_stars / items / properties / character / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / guest_stars / items / properties / character / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • addedOutput schema / properties / imdb_id
      Added value: +{
      +  "description": "This episode's own IMDb id (not the show's) — pass it to get_ratings for the episode's IMDb rating, which no TMDB field carries. Null when TMDB has no IMDb id for it.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / imdb_url
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • removedOutput schema / properties / name / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / name / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / overview / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / overview / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / runtime_minutes / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / runtime_minutes / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / season_number / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / season_number / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / still_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / still_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / vote_average / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / vote_average / description
      Added value: +"TMDB's own 0-10 user score. A different audience and scale from the IMDb/RT/Metacritic scores get_movie/get_tv return as `ratings` — don't compare, average or substitute across the two."
    • addedOutput schema / properties / vote_average / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / required
      Previous value: -[
      -  "season_number",
      -  "episode_number",
      -  "name",
      -  "air_date",
      -  "runtime_minutes",
      -  "vote_average",
      -  "overview",
      -  "still_url",
      -  "guest_stars",
      -  "crew"
      -]New value: +[
      +  "season_number",
      +  "episode_number",
      +  "imdb_id",
      +  "imdb_url",
      +  "name",
      +  "air_date",
      +  "runtime_minutes",
      +  "vote_average",
      +  "overview",
      +  "still_url",
      +  "guest_stars",
      +  "crew"
      +]
  3. Changed2 schema fields changedv0.10.1
    • changedOutput schema / properties / air_date / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "date",
      +    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / air_date / default
      Added value: +null
  4. Addedv0.8.1
  5. Removedv0.8.0
  6. First observedv0.3.0

TDQS

A4.2/5.0
Behavior4/5

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

With readOnlyHint=true and openWorldHint=true already covering the safety profile, the description still adds substantive behavior: this tool makes no OMDb call, so no per-episode IMDb rating is available without a follow-up to get_ratings, and guest stars are capped at 15. Those are non-obvious constraints. It omits error behavior for a nonexistent episode, keeping it from 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?

The core purpose is front-loaded in the first clause, and no sentence is filler. However, it is a dense two-sentence run-on with stacked parentheticals about voting scales and OMDb, which costs some readability even though the content is justified.

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?

For a simple three-required-parameter read tool with an output schema and annotations, this covers everything an agent needs: how to obtain the id, what scope the tool covers, what it does not return, and the exact follow-up call for a per-episode rating.

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 coverage is 100%, and all three parameters are documented there, including 'season 0 = specials' and the episode minimum. The description's only parameter guidance ('Get the show id from search_tv') restates the id field's own schema description, so it adds no meaning beyond the structured data. 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?

The description opens with a specific verb+resource ('Get one episode of a TV show') and names the exact three-part key (show id + season + episode). It also enumerates what comes back (overview, air date, runtime, guest stars, director/writer, imdb_id), which clearly distinguishes it from get_tv_season (whole season) and get_tv (whole show).

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 gives real routing: 'Get the show id from search_tv' as the prerequisite, and 'pass that id to get_ratings for this episode's IMDb rating, the only way to get a per-episode IMDb score here.' It also pre-empts a wrong turn by noting get_movie/get_tv's `ratings` are whole-show only. It stops short of explicitly excluding get_tv_season, but the alternatives and conditions are clear.

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