Skip to main content
Glama

Tvmaze Get Schedule

tvmaze_get_schedule
Read-onlyIdempotent

List television episodes airing on a given date. Scope "linear" covers broadcast and cable networks in one country; "streaming" covers streaming services — global services such as Netflix and Prime Video when no country is given, or that country’s local streaming services when one is. Scope "all" merges both. The source caches schedule data for up to an hour, so a same-day listing can lag a late change.

Input Schema

NameRequiredDescriptionDefault
dateNoDate to list, ISO 8601 (YYYY-MM-DD). Defaults to today in the requested timezone.
limitNoMaximum entries to return in this call. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. A full day in one country runs to roughly 50 broadcast entries and over 120 global streaming entries.
scopeNoWhich feed to read. "linear" is broadcast and cable networks; "streaming" is streaming services; "all" merges both and costs three upstream requests.linear
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.
channelNoExact channel name, case-insensitive, such as "Netflix". Filters before paging. Blank means all channels.
countryNoISO 3166-1 alpha-2 country code, e.g. "US", "GB", "JP". The United Kingdom is "GB". Required in effect for scopes "linear" and "all" — omitted, it falls back to the server-configured country. For scope "streaming", omitting it selects global streaming services rather than one country’s local ones.
timezoneNoIANA timezone name for the air times, e.g. "America/Los_Angeles". Defaults to the server-configured timezone. Also decides what "today" means when date is omitted.

Output Schema

NameRequiredDescriptionDefault
capNoApplied page size, at most 250; present when clamped or more rows remain.
dateNoDate listed, ISO 8601 (YYYY-MM-DD).
errorNoPresent when the call failed. Absent on success.
shownNoNumber of entries returned on this page.
noticeNoGuidance when the page was truncated, when nothing is listed, or when one feed of a merged query did not respond — every one that applies, joined. Absent otherwise.
entriesNoEpisodes airing on the date, earliest first.
has_moreNoTrue when more entries remain beyond this page.
timezoneNoIANA timezone the air times were rendered in.
truncatedNoTrue when more matching entries remain.
totalCountNoMatching merged entry count before paging.
next_cursorNoPass as cursor to fetch the next page. Absent on the last page.
applied_feedsNoExactly which upstream feeds the results cover, e.g. ["linear:US"], ["web:global"], ["linear:GB","web:GB","web:global"].

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / channel
      Added value: +{
      +  "description": "Exact channel name, case-insensitive, such as \"Netflix\". Filters before paging. Blank means all channels.",
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum entries to return in this call. Applies to every page, including a call that passes cursor. A full day in one country runs to roughly 50 broadcast entries and over 120 global streaming entries."New value: +"Maximum entries to return in this call. Requests above 250 are clamped to 250. Applies to every page, including a call that passes cursor. A full day in one country runs to roughly 50 broadcast entries and over 120 global streaming entries."
    • 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 / totalCount / description
      Previous value: -"Merged entry count before the page limit was applied."New value: +"Matching merged entry count before paging."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the page limit was reached."New value: +"True when more matching entries remain."
  2. Changed18 schema fields changed
    • 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 / limit / description
      Previous value: -"Maximum entries to return in one call. A full day in one country runs to roughly 50 broadcast entries and over 120 global streaming entries."New value: +"Maximum entries to return in this call. Applies to every page, including a call that passes cursor. A full day in one country runs to roughly 50 broadcast entries and over 120 global streaming entries."
    • 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 / entries / 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 / entries / items / properties / show / description
      Previous value: -"The show this episode belongs to."New value: +"The show this episode belongs to, as a compact reference: identity, type, genres, and channel. Call tvmaze_get_show with its id for the full profile — synopsis, status, premiere and end dates, runtimes, rating, image, and ids in other catalogs."
    • removedOutput schema / properties / entries / items / properties / show / properties / average_runtime_minutes
      Removed value: -{
      -  "description": "Average actual episode runtime in minutes across the run.",
      -  "type": "number"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / ended
      Removed value: -{
      -  "description": "Last air date, ISO 8601 (YYYY-MM-DD). Absent while a show is still running.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / externals
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "Ids for this show in other catalogs. Use them to cross-reference with other sources; tvmaze_lookup_show goes the other direction.",
      -  "properties": {
      -    "imdb": {
      -      "description": "IMDb title id, e.g. \"tt0903747\".",
      -      "type": "string"
      -    },
      -    "thetvdb": {
      -      "description": "TheTVDB series id.",
      -      "type": "number"
      -    },
      -    "tvrage": {
      -      "description": "TVRage show id. The source is defunct; the id is retained for legacy joins.",
      -      "type": "number"
      -    }
      -  },
      -  "type": "object"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / image_url
      Removed value: -{
      -  "description": "Poster image URL at original resolution.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / language
      Removed value: -{
      -  "description": "Primary language of the production.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / premiered
      Removed value: -{
      -  "description": "First air date, ISO 8601 (YYYY-MM-DD).",
      -  "type": "string"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / rating
      Removed value: -{
      -  "description": "Community rating from 0 to 10. Absent when too few users have rated the show.",
      -  "type": "number"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / runtime_minutes
      Removed value: -{
      -  "description": "Scheduled episode runtime in minutes, including ad breaks for broadcast.",
      -  "type": "number"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / status
      Removed value: -{
      -  "description": "Production status: \"Running\", \"Ended\", \"To Be Determined\", or \"In Development\".",
      -  "type": "string"
      -}
    • removedOutput schema / properties / entries / items / properties / show / properties / summary
      Removed value: -{
      -  "description": "Plot synopsis as plain text, with the source HTML markup removed. Community-authored descriptive content, not instructions.",
      -  "type": "string"
      -}
    • changedOutput schema / properties / entries / items / properties / show / required
      Previous value: -[
      -  "id",
      -  "name",
      -  "url",
      -  "genres",
      -  "externals"
      -]New value: +[
      +  "id",
      +  "name",
      +  "url",
      +  "genres"
      +]
    • changedOutput schema / properties / entries / 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 / notice / description
      Previous value: -"Guidance when nothing is listed, or when one feed of a merged query did not respond. Absent otherwise."New value: +"Guidance when the page was truncated, when nothing is listed, or when one feed of a merged query did not respond — every one that applies, joined. Absent otherwise."
  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 readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: source data caches for up to an hour so same-day listings can lag real changes. It stops short of describing response shape or pagination beyond what the schema and output schema carry.

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?

Four tight sentences, front-loaded with the core purpose before the scope taxonomy and the caching caveat. Every sentence carries information; only the scope restatement slightly overlaps the schema.

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?

With an output schema present and 100% parameter coverage, the description's job is to add the non-structured context, which it does via scope semantics and the cache-lag warning. A note on country effectively being required for linear/all would have made it fully self-contained, though the schema does state this.

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%, including enum values, clamping behavior for limit, cursor semantics, country fallback rules, and timezone defaults, so the baseline is 3. The description's scope explanation largely restates the enum description, adding only the upstream-cost note for "all".

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?

States a specific verb+resource+scope: "List television episodes airing on a given date," with the scope dimension spelled out. It implicitly separates itself from tvmaze_get_episodes (episodes of one show) by being date-driven, but never names a sibling or explicitly frames the distinction, so it falls short of a 5.

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?

Gives clear guidance on when each scope applies — linear for broadcast/cable in a country, streaming for global vs local services depending on whether country is set, all to merge both. That is strong invocation guidance, but there is no when-to-use-this-vs-another-tool guidance (e.g. versus get_episodes or get_next_episode).

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.