Skip to main content
Glama

Tvmaze Get Episodes

tvmaze_get_episodes
Read-onlyIdempotent

List a show’s episodes with air times, runtimes, and synopses. Pass a season number to list one season, which is the cheaper path and the usual one; pass air_date to list the episodes dated to one day, the direct path to a single night of a daily show; omit both to walk the whole run, which is paged because a long-running series returns hundreds of episodes. Specials are excluded unless include_specials is set, and the number left out is reported.

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum episodes to return in this call. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size.
cursorNoContinuation token from a previous call’s next_cursor. It carries only the position to resume from; the page size comes from limit. Omit for the first page.
seasonNoSeason number to list, as numbered in the season list from tvmaze_get_show. Omit, together with air_date, to list every episode of the series. Daily shows number seasons by calendar year.
show_idYesTVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.
air_dateNoDate to list, ISO 8601 (YYYY-MM-DD): the episodes the source dates to that day. It matches the source’s airdate, the broadcaster’s own programming day, so on a late-night slot it can differ by a day from the local_date an episode reports. Cannot be combined with season.
timezoneNoIANA timezone name for the air times, e.g. "America/Los_Angeles". Defaults to the server-configured timezone.
include_specialsNoInclude specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many; when off, notice reports how many were left out.

Output Schema

NameRequiredDescriptionDefault
capNoApplied page size, at most 250; present when clamped or more rows remain.
showNoThe show the episodes belong to.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of episodes returned on this page.
noticeNoGuidance when the page was truncated, when nothing was recorded, or when specials were filtered out — every one that applies, joined. Absent otherwise.
seasonNoSeason number listed. Absent when the whole run or one air date was listed.
air_dateNoAir date listed, YYYY-MM-DD. Absent unless air_date was given.
episodesNoEpisodes in airing order.
has_moreNoTrue when more episodes remain beyond this page.
timezoneNoIANA timezone the air times were rendered in.
truncatedNoTrue when more matching episodes remain.
totalCountNoEpisodes matching before the page limit was applied.
next_cursorNoPass as cursor to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum episodes to return in this call. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size."New value: +"Maximum episodes to return in this call. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size."
    • changedInput schema / properties / limit / maximum
      Previous value: -250New value: +9007199254740991
    • changedOutput schema / properties / cap / description
      Previous value: -"The page size applied to this call — its limit."New value: +"Applied page size, at most 250; present when clamped or more rows remain."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the page limit was reached."New value: +"True when more matching episodes remain."
  2. Changed13 schema fields changed
    • addedInput schema / properties / air_date
      Added value: +{
      +  "description": "Date to list, ISO 8601 (YYYY-MM-DD): the episodes the source dates to that day. It matches the source’s airdate, the broadcaster’s own programming day, so on a late-night slot it can differ by a day from the local_date an episode reports. Cannot be combined with season.",
      +  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / cursor / description
      Previous value: -"Continuation token from a previous call’s next_cursor. Omit for the first page."New value: +"Continuation token from a previous call’s next_cursor. It carries only the position to resume from; the page size comes from limit. Omit for the first page."
    • changedInput schema / properties / include_specials / description
      Previous value: -"Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many."New value: +"Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many; when off, notice reports how many were left out."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum episodes to return in one call. Raise it for a short series; the default keeps a long run inside a reasonable response size."New value: +"Maximum episodes to return in this call. Applies to every page, including a call that passes cursor. Raise it for a short series; the default keeps a long run inside a reasonable response size."
    • changedInput schema / properties / season / description
      Previous value: -"Season number to list, as numbered in the season list from tvmaze_get_show. Omit to list every episode of the series. Daily shows number seasons by calendar year."New value: +"Season number to list, as numbered in the season list from tvmaze_get_show. Omit, together with air_date, to list every episode of the series. Daily shows number seasons by calendar year."
    • addedOutput schema / properties / air_date
      Added value: +{
      +  "description": "Air date listed, YYYY-MM-DD. Absent unless air_date was given.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / cap / description
      Previous value: -"The page limit that was applied."New value: +"The page size applied to this call — its limit."
    • changedOutput schema / properties / episodes / items / properties / local_date / description
      Previous value: -"Calendar date the episode airs, in the requested timezone, ISO 8601 (YYYY-MM-DD)."New value: +"Calendar date the episode airs, ISO 8601 (YYYY-MM-DD). When time_known is true, the date in the requested timezone. When time_known is false, the source’s own announced air date, not timezone-converted — the same in every timezone."
    • changedOutput schema / properties / episodes / items / properties / type / description
      Previous value: -"Episode classification: \"regular\", \"significant_special\", or \"insignificant_special\". Anything other than \"regular\" is a special, and specials are excluded from a whole-run listing unless include_specials is set."New value: +"Episode classification: \"regular\", \"significant_special\", or \"insignificant_special\". Anything other than \"regular\" is a special; tvmaze_get_episodes leaves specials out unless include_specials is set."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `show_not_found`: No show exists with the given TVmaze id. `season_not_found`: The show has no season with the requested number. `invalid_timezone`: The timezone is not an IANA zone name the runtime recognizes. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `show_not_found`: No show exists with the given TVmaze id. `season_not_found`: The show has no season with the requested number. `invalid_date`: The air_date is well-formed but not a real calendar date. `invalid_timezone`: The timezone is not an IANA zone name the runtime recognizes. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "show_not_found",
      -  "season_not_found",
      -  "invalid_timezone"
      -]New value: +[
      +  "show_not_found",
      +  "season_not_found",
      +  "invalid_date",
      +  "invalid_timezone"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when nothing was recorded, or when specials were filtered out of a season listing. Absent otherwise."New value: +"Guidance when the page was truncated, when nothing was recorded, or when specials were filtered out — every one that applies, joined. Absent otherwise."
    • changedOutput schema / properties / season / description
      Previous value: -"Season number listed. Absent when the whole run was listed."New value: +"Season number listed. Absent when the whole run or one air date was listed."
  3. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, openWorld), so the description earns credit for adding what they cannot: specials are excluded by default and the number omitted is reported, and unfiltered listing is paged. It stops short of describing page-size interplay or what the response envelope looks like beyond the 'reported' count.

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?

Three dense sentences, front-loaded with the purpose and then the parameter-mode routing; no filler or restated title. The final specials clause is somewhat tacked on but still carries new information.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. With paging, exclusions, and all three filtering modes covered, an agent has everything needed to invoke this correctly.

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 description coverage is 100%, so all seven parameters are already documented, including the season/air_date mutual exclusion and the limit clamp to 250. The description adds only the routing rationale (season is cheaper, air_date is direct), which overlaps heavily with what the schema already states.

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?

Specific verb and resource ('List a show's episodes') with the returned fields stated (air times, runtimes, synopses), so the agent immediately knows what this yields. It does not name or contrast against its closest sibling, tvmaze_get_next_episode, nor explain how it differs from tvmaze_get_schedule, which also surfaces episode data.

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?

It explicitly routes the three modes: season for one season ('the cheaper path and the usual one'), air_date for a single night of a daily show ('the direct path'), and omitting both to walk the full run. It also warns that the full walk is paged and can return hundreds of episodes, which tells the agent when to prefer a narrower call.

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.