Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get TV show details

get_tv
Read-only

Fetch full details for one TV show by TMDB ID, including overview, genres, seasons/episodes counts, networks, creators, and optional IMDb/Rotten Tomatoes/Metacritic ratings.

Instructions

Get full details for one TV show by TMDB id: overview, genres, keywords ({id, name}), seasons/episodes counts, networks, created_by (the show's creator(s)), status, the age/content rating (certification) for region (falling back to the US rating, then any available country, when region has none; check certification_region to see which one was used), and links. By default also includes IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary (see include_ratings), plus OMDb's own age rating (ratings.rated, separate from this tool's certification; the two can differ), from OMDb (set include_ratings=false to skip). If unavailable (no OMDB_API_KEY, no imdb_id, or the OMDb lookup fails), ratings degrades to {found:false, reason} instead of failing the call. For shows like this one, get_tv_recommendations is the first stop; to match its themes instead, pass 2-3 distinctive keyword ids to discover_tv's with_keywords. A show's keywords are sparser, so ',' (all) often matches only the show itself and '|' (any) is the usual pick (checked live: Breaking Bad's 'drug dealer'|'outlaw' give The Sopranos, Narcos, Peaky Blinders). Set expand_episodes=true to also pull the seasons' episode lists (up to 250 episodes, 50 per season; see that field) instead of calling get_tv_season per season. If you only need the headline info (name/year/genres/vote average, season/episode counts), for one id or several, use get_tv_shows: it's trimmed and skips the rest of this payload. Get the 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>"
    },
    "name": "get_tv"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesTMDB TV show id (from search_tv).
regionNoThe user's country (pass it when known), whose age rating `certification` shows (falling back to the US rating, then any country's).US
languageNoResponse language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name.en-US
expand_episodesNoAlso fetch every season's full episode list (name, air date, runtime, and TMDB `vote_average`, TMDB's own 0-10 user score, not this tool's IMDb/RT/Metacritic `ratings`) as `seasons_detail`, in one extra request (more only past 20 seasons). Use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted to keep the response usable; call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' can otherwise run to hundreds of bonus clips), the combined count across every season is capped at 250, and the whole aggregate has a hard size ceiling (it trims further if episode names are unusually long), since a 30+ season show could otherwise still exceed a usable size. `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons fall off. A season entirely beyond the 250-episode budget is skipped rather than fetched and discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list; call get_tv_season for that season's full detail.
include_ratingsNoAdd IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary from OMDb (requires OMDB_API_KEY). The summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates), not a structured count, and covers the whole film/show, not any one person's award. Set false to skip the extra lookup.

Output Schema

NameRequiredDescriptionDefault
idYes
nameNo
typeYes
yearYes
genresYes
statusYes
imdb_idYes
ratingsNo
seasonsYes
taglineYes
homepageYes
imdb_urlYes
keywordsYes
networksYes
overviewYes
tmdb_urlYes
created_byYes
media_typeYes
popularityYes
poster_urlYes
vote_countYes
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.
certificationYes
in_productionYes
last_air_dateYes
original_nameNo
certificationsYes
first_air_dateYes
seasons_detailNo
episode_run_timeYes
number_of_seasonsYes
original_languageYes
number_of_episodesYes
last_episode_to_airYes
next_episode_to_airYes
certification_regionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.15.0
    • addedInput schema / properties / expand_episodes / default
      Added value: +false
    • changedInput schema / properties / expand_episodes / description
      Previous value: -"If true, also fetch every season's full episode list (name, air date, runtime, and TMDB `vote_average` — TMDB's own 0-10 user score, not this tool's IMDb/RT/Metacritic `ratings`) as `seasons_detail`, in one extra request — use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted here to keep that aggregate response usable — call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' in particular can otherwise run to hundreds of bonus clips), and the combined count across every season is capped at 250 total, and the whole aggregate additionally has a hard size ceiling (trims further if episode names are unusually long) since a 30+ season show could otherwise still exceed a usable response size even with the per-season cap alone; `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons are the ones that fall off. A season that falls entirely beyond the 250-episode budget is skipped rather than fetched-then-discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list — call get_tv_season for that season's full detail. Defaults to false."New value: +"Also fetch every season's full episode list (name, air date, runtime, and TMDB `vote_average`, TMDB's own 0-10 user score, not this tool's IMDb/RT/Metacritic `ratings`) as `seasons_detail`, in one extra request (more only past 20 seasons). Use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted to keep the response usable; call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' can otherwise run to hundreds of bonus clips), the combined count across every season is capped at 250, and the whole aggregate has a hard size ceiling (it trims further if episode names are unusually long), since a 30+ season show could otherwise still exceed a usable size. `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons fall off. A season entirely beyond the 250-episode budget is skipped rather than fetched and discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list; call get_tv_season for that season's full detail."
    • changedInput schema / properties / id / description
      Previous value: -"TMDB numeric id."New value: +"TMDB TV show id (from search_tv)."
    • addedInput schema / properties / include_ratings / default
      Added value: +true
    • changedInput schema / properties / include_ratings / description
      Previous value: -"If true (default), enrich the result with IMDb/Rotten Tomatoes/Metacritic ratings plus an awards summary (major-award wins/nominations — Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates; free text, not a structured count, and describes the whole film/show, not any one person's award) from OMDb (requires OMDB_API_KEY). Set false to skip the extra lookup when ratings are not needed."New value: +"Add IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary from OMDb (requires OMDB_API_KEY). The summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates), not a structured count, and covers the whole film/show, not any one person's award. Set false to skip the extra lookup."
    • addedInput schema / properties / language / default
      Added value: +"en-US"
    • changedInput schema / properties / language / description
      Previous value: -"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."New value: +"Response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."
    • addedInput schema / properties / region / default
      Added value: +"US"
    • changedInput schema / properties / region / description
      Previous value: -"ISO-3166-1 country code for region-specific results (default 'US')."New value: +"The user's country (pass it when known), whose age rating `certification` shows (falling back to the US rating, then any country's)."
    • addedOutput schema / properties / keywords
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "id": {
      +        "type": "number"
      +      },
      +      "name": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "name"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "id",
      -  "imdb_id",
      -  "media_type",
      -  "certification",
      -  "certification_region",
      -  "certifications",
      -  "tagline",
      -  "overview",
      -  "type",
      -  "year",
      -  "first_air_date",
      -  "last_air_date",
      -  "status",
      -  "in_production",
      -  "next_episode_to_air",
      -  "last_episode_to_air",
      -  "number_of_seasons",
      -  "number_of_episodes",
      -  "episode_run_time",
      -  "seasons",
      -  "genres",
      -  "vote_average",
      -  "vote_count",
      -  "popularity",
      -  "original_language",
      -  "networks",
      -  "created_by",
      -  "homepage",
      -  "poster_url",
      -  "tmdb_url",
      -  "imdb_url"
      -]New value: +[
      +  "id",
      +  "imdb_id",
      +  "media_type",
      +  "certification",
      +  "certification_region",
      +  "certifications",
      +  "tagline",
      +  "overview",
      +  "type",
      +  "year",
      +  "first_air_date",
      +  "last_air_date",
      +  "status",
      +  "in_production",
      +  "next_episode_to_air",
      +  "last_episode_to_air",
      +  "number_of_seasons",
      +  "number_of_episodes",
      +  "episode_run_time",
      +  "seasons",
      +  "genres",
      +  "keywords",
      +  "vote_average",
      +  "vote_count",
      +  "popularity",
      +  "original_language",
      +  "networks",
      +  "created_by",
      +  "homepage",
      +  "poster_url",
      +  "tmdb_url",
      +  "imdb_url"
      +]
  2. Changed65 schema fields changedv0.14.0
    • changedInput schema / properties / expand_episodes / description
      Previous value: -"If true, also fetch every season's full episode list (name, air date, runtime, rating) as `seasons_detail`, in one extra request — use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted here to keep that aggregate response usable — call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' in particular can otherwise run to hundreds of bonus clips), and the combined count across every season is capped at 250 total, and the whole aggregate additionally has a hard size ceiling (trims further if episode names are unusually long) since a 30+ season show could otherwise still exceed a usable response size even with the per-season cap alone; `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons are the ones that fall off. A season that falls entirely beyond the 250-episode budget is skipped rather than fetched-then-discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list — call get_tv_season for that season's full detail. Defaults to false."New value: +"If true, also fetch every season's full episode list (name, air date, runtime, and TMDB `vote_average` — TMDB's own 0-10 user score, not this tool's IMDb/RT/Metacritic `ratings`) as `seasons_detail`, in one extra request — use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted here to keep that aggregate response usable — call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' in particular can otherwise run to hundreds of bonus clips), and the combined count across every season is capped at 250 total, and the whole aggregate additionally has a hard size ceiling (trims further if episode names are unusually long) since a 30+ season show could otherwise still exceed a usable response size even with the per-season cap alone; `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons are the ones that fall off. A season that falls entirely beyond the 250-episode budget is skipped rather than fetched-then-discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list — call get_tv_season for that season's full detail. Defaults to false."
    • changedInput schema / properties / language / description
      Previous value: -"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE."New value: +"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."
    • removedOutput schema / properties / certification / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / certification / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / homepage / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / homepage / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / imdb_id / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / imdb_id / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / imdb_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / imdb_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / in_production / anyOf
      Removed value: -[
      -  {
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / in_production / type
      Added value: +[
      +  "boolean",
      +  "null"
      +]
    • changedOutput schema / properties / last_episode_to_air / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "air_date": {
      -        "anyOf": [
      -          {
      -            "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"
      -          }
      -        ],
      -        "default": null
      -      },
      -      "episode_number": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "name": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "season_number": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "season_number",
      -      "episode_number",
      -      "name",
      -      "air_date"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "air_date": {
      +        "anyOf": [
      +          {
      +            "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"
      +          }
      +        ],
      +        "default": null
      +      },
      +      "episode_number": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "name": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "season_number": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "season_number",
      +      "episode_number",
      +      "name",
      +      "air_date"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / next_episode_to_air / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "air_date": {
      -        "anyOf": [
      -          {
      -            "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"
      -          }
      -        ],
      -        "default": null
      -      },
      -      "episode_number": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "name": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "season_number": {
      -        "anyOf": [
      -          {
      -            "type": "number"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "season_number",
      -      "episode_number",
      -      "name",
      -      "air_date"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "air_date": {
      +        "anyOf": [
      +          {
      +            "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"
      +          }
      +        ],
      +        "default": null
      +      },
      +      "episode_number": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "name": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "season_number": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "season_number",
      +      "episode_number",
      +      "name",
      +      "air_date"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / number_of_episodes / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / number_of_episodes / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / number_of_seasons / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / number_of_seasons / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / original_language / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / original_language / 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 / popularity / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / popularity / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / poster_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / poster_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedOutput schema / properties / ratings / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "found": {
      -        "const": false,
      -        "type": "boolean"
      -      },
      -      "reason": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "found",
      -      "reason"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "awards": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "found": {
      -        "const": true,
      -        "type": "boolean"
      -      },
      -      "imdb_id": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "imdb_rating": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "imdb_votes": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "metascore": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "rated": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "ratings": {
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "source": {
      -              "type": "string"
      -            },
      -            "value": {
      -              "type": "string"
      -            }
      -          },
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "rotten_tomatoes": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "runtime": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "title": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "year": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "found",
      -      "imdb_id",
      -      "title",
      -      "year",
      -      "rated",
      -      "runtime",
      -      "imdb_rating",
      -      "imdb_votes",
      -      "metascore",
      -      "rotten_tomatoes",
      -      "awards",
      -      "ratings"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "found": {
      +        "const": false,
      +        "type": "boolean"
      +      },
      +      "reason": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "found",
      +      "reason"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "awards": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "found": {
      +        "const": true,
      +        "type": "boolean"
      +      },
      +      "imdb_id": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "imdb_rating": {
      +        "description": "IMDb user score, 0-10, as a string, e.g. '6.5'. Not TMDB's `vote_average`.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "imdb_votes": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "metascore": {
      +        "description": "Metacritic critic score, 0-100 scale, as a string, e.g. '67'.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "rated": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "ratings": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "source": {
      +              "type": "string"
      +            },
      +            "value": {
      +              "type": "string"
      +            }
      +          },
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "rotten_tomatoes": {
      +        "description": "Rotten Tomatoes Tomatometer — the percentage of positive critic reviews, as a string including the sign, e.g. '79%'. Not a 0-10 or 0-100 score.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "runtime": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "title": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "year": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "found",
      +      "imdb_id",
      +      "title",
      +      "year",
      +      "rated",
      +      "runtime",
      +      "imdb_rating",
      +      "imdb_votes",
      +      "metascore",
      +      "rotten_tomatoes",
      +      "awards",
      +      "ratings"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties / seasons / items / properties / episode_count / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons / items / properties / episode_count / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / seasons / items / properties / name / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons / items / properties / name / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons / items / properties / season_number / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons / items / properties / season_number / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / episode_number / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / episode_number / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / name / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / name / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / overview / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / overview / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / runtime_minutes / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / runtime_minutes / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / episodes / items / properties / vote_average / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / episodes / items / 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 / seasons_detail / items / properties / episodes / items / properties / vote_average / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / name / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / name / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / overview / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / overview / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / poster_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / poster_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / seasons_detail / items / properties / season_number / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / seasons_detail / items / properties / season_number / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / status / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / status / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / tagline / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / tagline / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / type / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / type / 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"
      +]
    • removedOutput schema / properties / vote_count / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / vote_count / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • addedOutput schema / properties / year
      Added value: +{
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "id",
      -  "imdb_id",
      -  "media_type",
      -  "certification",
      -  "certification_region",
      -  "certifications",
      -  "tagline",
      -  "overview",
      -  "type",
      -  "first_air_date",
      -  "last_air_date",
      -  "status",
      -  "in_production",
      -  "next_episode_to_air",
      -  "last_episode_to_air",
      -  "number_of_seasons",
      -  "number_of_episodes",
      -  "episode_run_time",
      -  "seasons",
      -  "genres",
      -  "vote_average",
      -  "vote_count",
      -  "popularity",
      -  "original_language",
      -  "networks",
      -  "created_by",
      -  "homepage",
      -  "poster_url",
      -  "tmdb_url",
      -  "imdb_url"
      -]New value: +[
      +  "id",
      +  "imdb_id",
      +  "media_type",
      +  "certification",
      +  "certification_region",
      +  "certifications",
      +  "tagline",
      +  "overview",
      +  "type",
      +  "year",
      +  "first_air_date",
      +  "last_air_date",
      +  "status",
      +  "in_production",
      +  "next_episode_to_air",
      +  "last_episode_to_air",
      +  "number_of_seasons",
      +  "number_of_episodes",
      +  "episode_run_time",
      +  "seasons",
      +  "genres",
      +  "vote_average",
      +  "vote_count",
      +  "popularity",
      +  "original_language",
      +  "networks",
      +  "created_by",
      +  "homepage",
      +  "poster_url",
      +  "tmdb_url",
      +  "imdb_url"
      +]
  3. Changed1 schema field changedv0.11.0
    • changedInput schema / properties / expand_episodes / description
      Previous value: -"If true, also fetch every season's full episode list (name, air date, runtime, rating) as `seasons_detail`, in one extra request — use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted here to keep that aggregate response usable — call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' in particular can otherwise run to hundreds of bonus clips), and the combined count across every season is capped at 250 total, and the whole aggregate additionally has a hard size ceiling (trims further if episode names are unusually long) since a 30+ season show could otherwise still exceed a usable response size even with the per-season cap alone; `episode_count` on each season still reports that season's true total. A season that falls entirely beyond the 250-episode budget is skipped rather than fetched-then-discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list — call get_tv_season for that season's full detail. Defaults to false."New value: +"If true, also fetch every season's full episode list (name, air date, runtime, rating) as `seasons_detail`, in one extra request — use this instead of calling get_tv_season once per season when you need all episodes of a multi-season show. Episode overviews are omitted here to keep that aggregate response usable — call get_tv_season for one season's full detail including overview. Each season's episode list is capped at 50 (season 0 'Specials' in particular can otherwise run to hundreds of bonus clips), and the combined count across every season is capped at 250 total, and the whole aggregate additionally has a hard size ceiling (trims further if episode names are unusually long) since a 30+ season show could otherwise still exceed a usable response size even with the per-season cap alone; `episode_count` on each season still reports that season's true total. The 250 budget is spent in season order starting at season 0, so on a long-running show the specials are served first and the last seasons are the ones that fall off. A season that falls entirely beyond the 250-episode budget is skipped rather than fetched-then-discarded, so its `overview`/`poster_url` come back null too, not just its `episodes` list — call get_tv_season for that season's full detail. Defaults to false."
  4. Addedv0.10.1
  5. Removedv0.8.1
  6. Addedv0.8.1
  7. Removedv0.8.0
  8. First observedv0.3.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the readOnly/openWorld annotations: it discloses the graceful-degradation path when OMDb is unavailable (ratings becomes {found:false, reason} rather than failing), the certification fallback chain and the certification_region indicator, and the episode-aggregate caps including the ordering quirk where the 250 budget is spent from season 0 so late seasons fall off. These are exactly the runtime behaviors an agent cannot infer from structured fields.

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-loaded with the payload enumeration and then the routing alternatives, which is the right order. It is a single dense block, and a few clauses stray into guidance for other tools (the ',' vs '|' keyword matching advice and the 'checked live: Breaking Bad' example) that dilute focus, though they do serve routing.

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?

Given an output schema exists, the description need not document return shapes, and it still covers the two things that matter operationally: what happens when ratings cannot be fetched and what expand_episodes will and will not include. Nothing needed to invoke the tool correctly for a single-show lookup is missing.

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; the description still adds meaning by clarifying that OMDb's ratings.rated is distinct from this tool's certification and that the two can differ, and by warning that '|' (any) is the usual keyword match for shows since ',' (all) often matches only the show itself. Some parameter text is repeated near-verbatim from the schema (region fallback, expand_episodes caps), which limits the added value.

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 ('Get full details for one TV show by TMDB id') and then enumerates the payload fields: overview, genres, keywords, season/episode counts, networks, created_by, status, certification and links. It also distinguishes itself from get_tv_shows ('trimmed and skips the rest of this payload') and get_tv_recommendations, so an agent can pick correctly without opening a 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?

Explicit routing is given for each alternative: get_tv_shows when only headline info is needed (one id or several), get_tv_recommendations as the first stop for similar shows, discover_tv with_keywords to match themes, and get_tv_season instead of expand_episodes when one season's full detail is wanted. It also states where the id comes from ('Get the id from search_tv').

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