tvmaze-mcp-server

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; omit it 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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum episodes to return in one call. Raise it for a short series; the default keeps a long run inside a reasonable response size.
`cursor`	No	Continuation token from a previous call’s next_cursor. Omit for the first page.
`season`	No	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.
`show_id`	Yes	TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.
`timezone`	No	IANA timezone name for the air times, e.g. "America/Los_Angeles". Defaults to the server-configured timezone.
`include_specials`	No	Include specials alongside regular episodes. Off by default because specials roughly double the result count on a series that has many.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The page limit that was applied.
`show`	No	The show the episodes belong to.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of episodes returned on this page.
`notice`	No	Guidance when nothing was recorded, or when specials were filtered out of a season listing. Absent otherwise.
`season`	No	Season number listed. Absent when the whole run was listed.
`episodes`	No	Episodes in airing order.
`has_more`	No	True when more episodes remain beyond this page.
`timezone`	No	IANA timezone the air times were rendered in.
`truncated`	No	True when the page limit was reached.
`totalCount`	No	Episodes matching before the page limit was applied.
`next_cursor`	No	Pass as cursor to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 20, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and open-world behavior. The description adds meaningful non-obvious behavior: specials are excluded by default, the whole-run path is paged, and a season-scoped call is cheaper. This goes beyond the annotations and helps the agent predict response cost and filtering behavior.

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

Conciseness5/5

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

Three sentences, each earning its place: the main purpose, the season-vs-full-run decision with cost/paging context, and the specials default. The most important usage guidance is front-loaded.

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 the rich output schema and well-covered parameters, the description covers the key behavioral decisions an agent needs: season scoping, paging, and specials handling. No critical operational detail 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 description coverage is 100%, so a baseline of 3 is appropriate. The description adds extra value by highlighting the season parameter as the cheaper/usual path, explaining that omitting it triggers a paged walk, and noting the specials-exclusion default tied to include_specials. These nuances are not fully captured in the parameter descriptions.

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 uses a specific verb (List) and resource (a show's episodes) and names the returned content (air times, runtimes, synopses). It clearly distinguishes this from sibling tools like tvmaze_get_next_episode, tvmaze_get_schedule, and tvmaze_get_cast by focusing on episode listing with season/paging behavior.

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?

The description gives clear direction on the common path (pass a season number) and the alternative (omit it to walk the whole run), including the cost tradeoff and paging implication. It does not explicitly name sibling alternatives, but the guidance is sufficiently actionable for an agent to decide how to call the tool.

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

All tvmaze-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.