tvmaze-mcp-server
Server Details
Search TVmaze shows, next episodes in your timezone, episode guides, daily TV schedules, and cast.
- Status
- Healthy
- Uptime
- 100.0% over 20 days
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- Repository
- cyanheads/tvmaze-mcp-server
- GitHub Stars
- 1
- Server Listing
- tvmaze-mcp-server
TDQS
Scored across 7 tools
Each tool targets a clearly distinct retrieval action: search by title, lookup by external id, fetch by TVmaze id, list episodes, list cast, get next episode, and get schedule. The only mild overlap between get_show returning next-episode info and get_next_episode is clarified by each description's focus.
All tools share a consistent tvmaze_ prefix and follow a verb_noun pattern. The verb varies meaningfully by operation (get, lookup, search), but the shape is uniform and predictable across the whole set.
Seven tools is a well-scoped size for a TV metadata server. Each tool covers a distinct core capability without redundancy or unnecessary bloat.
The tool surface covers the main TVmaze read workflows: finding shows, resolving external ids, fetching show details, exploring episodes, retrieving cast and crew, checking the next episode, and viewing schedules. There are no critical gaps for a read-only TV information API.
Available Tools
7 toolstvmaze_get_castTvmaze Get CastARead-onlyIdempotentInspect
List the credited cast of a show with the characters they play, optionally with crew; or list the guest cast of one episode, optionally with its guest crew such as the director and writers. Results are paged: cast rows come first, then crew rows, and each page splits them back into cast and crew. The source records no recurring-versus-guest distinction on a show’s cast list, so a name’s absence from it does not mean the performer never appeared — check an episode’s guest cast for that.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The page size applied to this call — its limit. |
| cast | No | Cast credits on this page — for scope "show", the main cast; for scope "episode", that episode’s guest cast. Empty on a page past the last cast row. |
| crew | No | Crew credits on this page — for scope "show", the show’s crew; for scope "episode", that episode’s guest crew. Present, possibly empty, whenever include_crew was set; crew rows follow every cast row, so a page that ends inside the cast carries none. |
| error | No | Present when the call failed. Absent on success. |
| scope | No | Which credit list was returned. |
| shown | No | Number of credits returned on this page. |
| notice | No | Guidance when the page was truncated, or when no cast is recorded — every one that applies, joined. Absent otherwise. |
| has_more | No | True when more credits remain beyond this page. |
| truncated | No | True when the page limit was reached. |
| cast_total | No | Cast credits across every page. |
| crew_total | No | Crew credits across every page. Present when include_crew was set. |
| subject_id | No | TVmaze id the credits belong to — a show id or an episode id, matching scope. |
| totalCount | No | Credits across every page, cast plus crew. |
| next_cursor | No | Pass as cursor to fetch the next page. Absent on the last page. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and open-world, and the description adds valuable behavior beyond those: pagination splits cast and crew rows per page, and the source records no recurring-vs-guest distinction so absence from the cast list is not proof of non-appearance. This gives the agent important caveats for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core operation and both scope variants appear in the first sentence, followed by essential paging semantics and a meaningful caveat. Every sentence earns its place, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-branch tool with an output schema and detailed parameter descriptions, the description covers the operation, scope options, result ordering, pagination, crew behavior, and interpretation caveat. Nothing needed to invoke or interpret the tool seems missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents each parameter thoroughly, so the baseline is 3. The description adds useful contextual meaning around paging and result ordering (cast rows first, then crew rows) and clarifies that the open-world caveat applies to the show cast list, which supports correct interpretation of include_crew and scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List the credited cast of a show...', and immediately distinguishes the two supported scopes, show cast and episode guest cast. It also mentions the optional crew dimension, making it clear this tool is about cast/crew credits rather than episode lists or show metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly lays out the two usage modes (show-level cast vs. episode-level guest cast) and notes the optional crew inclusion. It does not explicitly compare against sibling tools or state when not to use it, but the cast-specific purpose and scope guidance provide clear context for an agent to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_get_episodesTvmaze Get EpisodesARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 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. | |
| cursor | No | 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. | |
| season | No | 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. | |
| show_id | Yes | TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule. | |
| air_date | No | 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. | |
| 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; when off, notice reports how many were left out. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The page size applied to this call — its limit. |
| 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 the page was truncated, when nothing was recorded, or when specials were filtered out — every one that applies, joined. Absent otherwise. |
| season | No | Season number listed. Absent when the whole run or one air date was listed. |
| air_date | No | Air date listed, YYYY-MM-DD. Absent unless air_date was given. |
| 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. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses paging behavior for long-running series, that specials are excluded by default, and that the count of omitted specials is reported. These are behavioral details an agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, then organized by parameter mode. No filler or repetition of schema details; every sentence contributes decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven parameters and an output schema, the description covers all invocation modes, pagination, specials behavior, and parameter tradeoffs. The presence of an output schema means return-value details do not need to be restated, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds value by explaining the interaction between season, air_date, and omission of both, plus the semantic consequence of include_specials. Individual parameter formats remain in the schema, but the top-level description enriches the parameter model.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'List a show’s episodes with air times, runtimes, and synopses.' It names the resource and the returned kinds of data clearly, and the three invocation modes distinguish this from sibling tools like tvmaze_get_next_episode or tvmaze_get_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to pass season, when to pass air_date, and when to omit both, including the tradeoffs ('cheaper path', 'direct path to a single night of a daily show', 'paged'). It also explains the default behavior for specials and how to override it, giving an agent concrete decision rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_get_next_episodeTvmaze Get Next EpisodeARead-onlyIdempotentInspect
Report when a show’s next episode airs, converted to a viewer timezone. Accepts a TVmaze id or a show title — a title is resolved with a stricter single-match search than tvmaze_search_shows uses. A show with no scheduled next episode is reported as a miss carrying its most recent episode, which is the normal state for a series between seasons.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| show | No | The show the answer is about. Absent when the show itself could not be resolved. |
| error | No | Present when the call failed. Absent on success. |
| found | No | True when a next episode is scheduled. |
| guidance | No | What to do next when no next episode was returned. Absent on a hit. |
| timezone | No | IANA timezone the air times were rendered in. |
| miss_reason | No | Why no next episode was returned. "show_not_found" means the title or id resolved to nothing; "no_scheduled_episode" means the show exists but has nothing on the schedule. |
| next_episode | No | The next scheduled episode. Absent on a miss. |
| previous_episode | No | The most recently aired episode. Returned on a hit and on a "no_scheduled_episode" miss, so a between-seasons answer still says where the show left off. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds valuable behavior beyond that: timezone conversion, stricter title matching, and the miss state when no next episode is scheduled. Explaining that the miss carries the most recent episode is especially useful for interpreting results between seasons.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tightly written sentences with no filler. The core action is front-loaded, and each subsequent sentence adds distinct value: lookup modes, resolution behavior, and edge-case behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with an output schema present, the description covers all essential operational details: input identification, timezone behavior, and the no-schedule edge case. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are fully documented structurally. The description nonetheless adds semantic meaning by explaining the difference between the id and title branches and clarifying that title lookup uses a stricter match than tvmaze_search_shows, which helps the agent choose correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Report when a show’s next episode airs') and immediately conveys the tool's scope. It also differentiates itself from tvmaze_search_shows by noting the stricter single-match title resolution, so an agent can tell it apart from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly establishes when the tool is appropriate: whenever the next episode and air time are needed, identified by either id or title. It references tvmaze_search_shows as an alternative for title matching, though it does not explicitly contrast with tvmaze_get_episodes or tvmaze_get_schedule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_get_scheduleTvmaze Get ScheduleARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date to list, ISO 8601 (YYYY-MM-DD). Defaults to today in the requested timezone. | |
| limit | No | 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. | |
| scope | No | Which feed to read. "linear" is broadcast and cable networks; "streaming" is streaming services; "all" merges both and costs three upstream requests. | linear |
| cursor | No | 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. | |
| country | No | ISO 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. | |
| timezone | No | IANA 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
| Name | Required | Description |
|---|---|---|
| cap | No | The page size applied to this call — its limit. |
| date | No | Date listed, ISO 8601 (YYYY-MM-DD). |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of entries returned on this page. |
| notice | No | 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. |
| entries | No | Episodes airing on the date, earliest first. |
| has_more | No | True when more entries 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 | Merged entry count before the page limit was applied. |
| next_cursor | No | Pass as cursor to fetch the next page. Absent on the last page. |
| applied_feeds | No | Exactly which upstream feeds the results cover, e.g. ["linear:US"], ["web:global"], ["linear:GB","web:GB","web:global"]. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: the cache lag (up to an hour), the cost of 'all' scope (three upstream requests), and the country fallback behavior. It doesn't detail pagination mechanics, but the schema covers cursor/limit semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose is in the first sentence, followed by scope distinctions and the caching caveat. Every sentence earns its place, and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (100% coverage), output schema, and annotations, the description covers the essential behavioral nuances: scope semantics, country fallback, cache lag, and the cost of 'all'. Nothing critical is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds meaning beyond the schema by explaining the practical implications of 'limit' (a full day runs to ~50 broadcast / 120+ streaming entries) and the country fallback for 'linear'/'all' vs 'streaming'. This helps an agent choose sensible parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('television episodes airing on a given date'), and immediately distinguishes the three scopes. It clearly differentiates from sibling tools like tvmaze_get_episodes (which lists episodes of a show) by focusing on a date-based schedule feed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each scope ('linear' vs 'streaming' vs 'all') and the country behavior for streaming. It also notes the caching behavior, which tells the agent when results may be stale. This is strong guidance for selecting and invoking the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_get_showTvmaze Get ShowARead-onlyIdempotentInspect
Fetch a television show by its TVmaze id: full profile, weekly broadcast slot, season list, and the previous and next episode when the source has them. This is the entry point for an id returned by tvmaze_search_shows or tvmaze_lookup_show. For the episode list itself use tvmaze_get_episodes, and for credits use tvmaze_get_cast.
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule. | |
| timezone | No | IANA timezone name for rendering the previous and next episode air times, e.g. "America/Los_Angeles" or "Europe/London". Defaults to the server-configured timezone. |
Output Schema
| Name | Required | Description |
|---|---|---|
| show | No | Full show profile. |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when a Running show has no scheduled next episode. Absent otherwise. |
| seasons | No | Every season TVmaze records, in order. Pass a season number to tvmaze_get_episodes. |
| timezone | No | IANA timezone the episode times were rendered in. |
| next_episode | No | The next episode scheduled to air. Absent when none is scheduled — a Running show between seasons has no next episode. |
| previous_episode | No | The most recently aired episode. Absent for a show that has not premiered. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds valuable behavioral context beyond annotations: it discloses that previous/next episode are returned only 'when the source has them,' and clarifies that the timezone parameter affects rendering of those air times. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the core action and deliverable, the second establishes entry-point role, and the third redirects to siblings. No fluff, no repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, 1 required), has 100% schema coverage, an output schema, and annotations covering read-only/idempotent behavior. The description completes the picture with scoped return contents and routing guidance. Nothing an agent needs for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already fully documented. The description's mention of timezone for rendering air times adds no new information beyond the schema's own description. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Fetch'), a specific resource ('a television show by its TVmaze id'), and enumerates the returned content (profile, broadcast slot, season list, previous/next episode when available). It explicitly differentiates from siblings by stating that episode lists go to tvmaze_get_episodes and credits go to tvmaze_get_cast, making the tool's role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description anchors the tool as the entry point for IDs produced by tvmaze_search_shows or tvmaze_lookup_show, and explicitly routes agents to sibling tools for episode lists and credits. This gives clear when-to-use and when-not-to-use guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_lookup_showTvmaze Lookup ShowARead-onlyIdempotentInspect
Resolve a television show from its id in another catalog — IMDb, TheTVDB, or TVRage — and return the matching TVmaze profile. Use this to cross a show id from another source into TVmaze. A show absent from TVmaze is reported as a miss with guidance, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| show | No | The resolved show. Absent on a miss. |
| error | No | Present when the call failed. Absent on success. |
| found | No | True when the external id resolved to a TVmaze show. |
| source | No | Catalog the lookup was made against. |
| guidance | No | What to do next when the lookup missed. Absent on a hit. |
| external_id | No | Id that was looked up, as submitted. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable non-obvious behavior: when a show is absent from TVmaze, the tool reports a miss with guidance rather than raising an error. This edge-case disclosure goes beyond what the annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core action and use case come first, and the miss-handling behavior is a distinct, valuable second sentence. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the annotations cover safety and idempotency, the output schema documents the return value, and the description covers the failure mode. No necessary information is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with each source variant and external_id pattern fully documented. The description adds no new parameter-level meaning beyond restating the three catalogs, so the schema carries the semantic weight. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise verb and resource: resolve an external catalog id (IMDb, TheTVDB, TVRage) into a TVmaze profile. It also conveys the distinguishing scope — this is a cross-reference lookup, not a search or a direct TVmaze-id fetch — which separates it from siblings like tvmaze_get_show and tvmaze_search_shows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: 'Use this to cross a show id from another source into TVmaze.' This is clear contextual guidance. It does not explicitly name sibling alternatives or exclusion conditions, but the use case is unambiguous enough that an agent can route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tvmaze_search_showsTvmaze Search ShowsARead-onlyIdempotentInspect
Search television shows by title and return up to 10 matches, each with its network or streaming service, production status, genres, rating, and ids in other catalogs. Matching is fuzzy, so small typos still resolve. The result set is hard-capped at 10 by the source and cannot be paged — narrow the title to reach an eleventh match. To go the other way, from an IMDb or TheTVDB id to a show, use tvmaze_lookup_show.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Show title or title fragment. Matched fuzzily against every show title in the database, so minor misspellings still resolve. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The result ceiling the source applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of shows returned. |
| shows | No | Matching shows, best match first. At most 10. |
| notice | No | Guidance when nothing matched or when the ten-result ceiling was reached. Absent otherwise. |
| truncated | No | True when the source's fixed ten-result ceiling was reached. |
| effectiveQuery | No | The query as submitted upstream. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds valuable behavioral context on top: fuzzy matching behavior, the hard-capped result set, the lack of pagination, and the exact data fields returned. This goes well beyond what annotations alone provide and contradicts nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three purposeful sentences: the first defines the operation and return value, the second covers matching and limits, and the third routes to the correct alternative. No filler, no repetition, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only search tool, this description is fully self-sufficient. It tells the agent what the tool does, what data it returns, its fuzzy behavior, its pagination limitations, and how to choose a sibling tool. The presence of an output schema means return-value details don't need to be restated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds an extra layer of guidance beyond the schema by explaining that narrowing the query is required to reach results beyond the hard cap, which gives the agent a strategy for using the query parameter effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search television shows by title', then enumerates exactly what each match returns. It also distinguishes itself from the sibling tvmaze_lookup_show by explicitly stating it handles the reverse direction, making tool selection unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it tells the agent this is the right tool for title-based fuzzy search and explicitly says to use tvmaze_lookup_show when starting from an IMDb or TheTVDB id. It also documents the practical constraint of the 10-result cap and the strategy of narrowing the title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
- Changed
tvmaze_get_cast13 fields changed- changed
Input schema / oneOfPrevious value: -[ - { - "additionalProperties": false, - "properties": { - "include_crew": { - "default": false, - "description": "Also list crew credits — producers, writers, directors. Off by default; a long-running series carries dozens and they are rarely what a cast question is asking for.", - "type": "boolean" - }, - "scope": { - "const": "show", - "description": "List the show’s main cast.", - "type": "string" - }, - "show_id": { - "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.", - "exclusiveMinimum": 0, - "maximum": 9007199254740991, - "type": "integer" - } - }, - "required": [ - "scope", - "show_id" - ], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "episode_id": { - "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.", - "exclusiveMinimum": 0, - "maximum": 9007199254740991, - "type": "integer" - }, - "scope": { - "const": "episode", - "description": "List one episode’s guest cast.", - "type": "string" - } - }, - "required": [ - "scope", - "episode_id" - ], - "type": "object" - } -]New value: +[ + { + "additionalProperties": false, + "properties": { + "cursor": { + "description": "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.", + "type": "string" + }, + "include_crew": { + "default": false, + "description": "Also list the show’s crew credits — producers, creators, and other series-level roles, with no episode attribution. Off by default; a long-running series carries hundreds and they are rarely what a cast question is asking for.", + "type": "boolean" + }, + "limit": { + "default": 50, + "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.", + "maximum": 250, + "minimum": 1, + "type": "integer" + }, + "scope": { + "const": "show", + "description": "List the show’s main cast.", + "type": "string" + }, + "show_id": { + "description": "TVmaze show id, from tvmaze_search_shows, tvmaze_lookup_show, or tvmaze_get_schedule.", + "exclusiveMinimum": 0, + "maximum": 9007199254740991, + "type": "integer" + } + }, + "required": [ + "scope", + "show_id" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "cursor": { + "description": "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.", + "type": "string" + }, + "episode_id": { + "description": "TVmaze episode id, from tvmaze_get_episodes, tvmaze_get_next_episode, tvmaze_get_schedule, or tvmaze_get_show.", + "exclusiveMinimum": 0, + "maximum": 9007199254740991, + "type": "integer" + }, + "include_crew": { + "default": false, + "description": "Also list the episode’s guest crew — who directed and wrote it, as TVmaze credits them. Off by default.", + "type": "boolean" + }, + "limit": { + "default": 50, + "description": "Maximum credits to return in this call, cast and crew together. Applies to every page, including a call that passes cursor. A long-running series carries over a thousand cast credits.", + "maximum": 250, + "minimum": 1, + "type": "integer" + }, + "scope": { + "const": "episode", + "description": "List one episode’s guest cast.", + "type": "string" + } + }, + "required": [ + "scope", + "episode_id" + ], + "type": "object" + } +] - changed
Output schema / anyOfPrevious value: -[ - { - "not": { - "required": [ - "error" - ] - }, - "required": [ - "cast", - "scope", - "subject_id", - "totalCount" - ] - }, - { - "required": [ - "error" - ] - } -]New value: +[ + { + "not": { + "required": [ + "error" + ] + }, + "required": [ + "cast", + "cast_total", + "scope", + "subject_id", + "has_more", + "totalCount" + ] + }, + { + "required": [ + "error" + ] + } +] - added
Output schema / properties / capAdded value: +{ + "description": "The page size applied to this call — its limit.", + "type": "number" +} - changed
Output schema / properties / cast / descriptionPrevious value: -"Cast credits — for scope \"show\", the main cast; for scope \"episode\", that episode’s guest cast."New value: +"Cast credits on this page — for scope \"show\", the main cast; for scope \"episode\", that episode’s guest cast. Empty on a page past the last cast row." - added
Output schema / properties / cast_totalAdded value: +{ + "description": "Cast credits across every page.", + "type": "number" +} - changed
Output schema / properties / crew / descriptionPrevious value: -"Crew credits. Present only when include_crew was set on a show query."New value: +"Crew credits on this page — for scope \"show\", the show’s crew; for scope \"episode\", that episode’s guest crew. Present, possibly empty, whenever include_crew was set; crew rows follow every cast row, so a page that ends inside the cast carries none." - added
Output schema / properties / crew_totalAdded value: +{ + "description": "Crew credits across every page. Present when include_crew was set.", + "type": "number" +} - added
Output schema / properties / has_moreAdded value: +{ + "description": "True when more credits remain beyond this page.", + "type": "boolean" +} - added
Output schema / properties / next_cursorAdded value: +{ + "description": "Pass as cursor to fetch the next page. Absent on the last page.", + "type": "string" +} - changed
Output schema / properties / notice / descriptionPrevious value: -"Guidance when no credits are recorded. Absent otherwise."New value: +"Guidance when the page was truncated, or when no cast is recorded — every one that applies, joined. Absent otherwise." - added
Output schema / properties / shownAdded value: +{ + "description": "Number of credits returned on this page.", + "type": "number" +} - changed
Output schema / properties / totalCount / descriptionPrevious value: -"Credits returned, cast plus crew."New value: +"Credits across every page, cast plus crew." - added
Output schema / properties / truncatedAdded value: +{ + "description": "True when the page limit was reached.", + "type": "boolean" +}
- Changed
tvmaze_get_episodes13 fields changed- added
Input schema / properties / air_dateAdded 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" +} - changed
Input schema / properties / cursor / descriptionPrevious 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." - changed
Input schema / properties / include_specials / descriptionPrevious 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." - changed
Input schema / properties / limit / descriptionPrevious 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." - changed
Input schema / properties / season / descriptionPrevious 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." - added
Output schema / properties / air_dateAdded value: +{ + "description": "Air date listed, YYYY-MM-DD. Absent unless air_date was given.", + "type": "string" +} - changed
Output schema / properties / cap / descriptionPrevious value: -"The page limit that was applied."New value: +"The page size applied to this call — its limit." - changed
Output schema / properties / episodes / items / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / episodes / items / properties / type / descriptionPrevious 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." - changed
Output schema / properties / error / properties / data / properties / reason / descriptionPrevious 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." - changed
Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[ - "show_not_found", - "season_not_found", - "invalid_timezone" -]New value: +[ + "show_not_found", + "season_not_found", + "invalid_date", + "invalid_timezone" +] - changed
Output schema / properties / notice / descriptionPrevious 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." - changed
Output schema / properties / season / descriptionPrevious 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."
- Changed
tvmaze_get_next_episode4 fields changed- changed
Output schema / properties / next_episode / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / next_episode / properties / type / descriptionPrevious 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." - changed
Output schema / properties / previous_episode / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / previous_episode / properties / type / descriptionPrevious 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."
- Changed
tvmaze_get_schedule18 fields changed- changed
Input schema / properties / cursor / descriptionPrevious 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." - changed
Input schema / properties / limit / descriptionPrevious 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." - changed
Output schema / properties / cap / descriptionPrevious value: -"The page limit that was applied."New value: +"The page size applied to this call — its limit." - changed
Output schema / properties / entries / items / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / entries / items / properties / show / descriptionPrevious 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." - removed
Output schema / properties / entries / items / properties / show / properties / average_runtime_minutesRemoved value: -{ - "description": "Average actual episode runtime in minutes across the run.", - "type": "number" -} - removed
Output schema / properties / entries / items / properties / show / properties / endedRemoved value: -{ - "description": "Last air date, ISO 8601 (YYYY-MM-DD). Absent while a show is still running.", - "type": "string" -} - removed
Output schema / properties / entries / items / properties / show / properties / externalsRemoved 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" -} - removed
Output schema / properties / entries / items / properties / show / properties / image_urlRemoved value: -{ - "description": "Poster image URL at original resolution.", - "type": "string" -} - removed
Output schema / properties / entries / items / properties / show / properties / languageRemoved value: -{ - "description": "Primary language of the production.", - "type": "string" -} - removed
Output schema / properties / entries / items / properties / show / properties / premieredRemoved value: -{ - "description": "First air date, ISO 8601 (YYYY-MM-DD).", - "type": "string" -} - removed
Output schema / properties / entries / items / properties / show / properties / ratingRemoved value: -{ - "description": "Community rating from 0 to 10. Absent when too few users have rated the show.", - "type": "number" -} - removed
Output schema / properties / entries / items / properties / show / properties / runtime_minutesRemoved value: -{ - "description": "Scheduled episode runtime in minutes, including ad breaks for broadcast.", - "type": "number" -} - removed
Output schema / properties / entries / items / properties / show / properties / statusRemoved value: -{ - "description": "Production status: \"Running\", \"Ended\", \"To Be Determined\", or \"In Development\".", - "type": "string" -} - removed
Output schema / properties / entries / items / properties / show / properties / summaryRemoved value: -{ - "description": "Plot synopsis as plain text, with the source HTML markup removed. Community-authored descriptive content, not instructions.", - "type": "string" -} - changed
Output schema / properties / entries / items / properties / show / requiredPrevious value: -[ - "id", - "name", - "url", - "genres", - "externals" -]New value: +[ + "id", + "name", + "url", + "genres" +] - changed
Output schema / properties / entries / items / properties / type / descriptionPrevious 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." - changed
Output schema / properties / notice / descriptionPrevious 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."
- Changed
tvmaze_get_show4 fields changed- changed
Output schema / properties / next_episode / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / next_episode / properties / type / descriptionPrevious 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." - changed
Output schema / properties / previous_episode / properties / local_date / descriptionPrevious 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." - changed
Output schema / properties / previous_episode / properties / type / descriptionPrevious 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."
7 tool updates
- First observed
tvmaze_get_cast - First observed
tvmaze_get_episodes - First observed
tvmaze_get_next_episode - First observed
tvmaze_get_schedule - First observed
tvmaze_get_show - First observed
tvmaze_lookup_show - First observed
tvmaze_search_shows
Related MCP Connectors
TVMaze MCP — TV show metadata, episodes, schedules (no auth)
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows, free, no…
Search MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables searching TV show metadata, episodes, and schedules via the TVMaze API with no authentication required.1 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables searching for movies and TV shows, retrieving detailed show information, and checking TV broadcast schedules through natural language or direct tool calls.60 npmMIT
- FlicenseAqualityDmaintenanceEnables querying TV programming data from Tunarr XMLTV feeds, including viewing channel listings, current and upcoming schedules, and searching for programmes by title or description.5-
- AlicenseNot gradedqualityDmaintenanceEnables querying The Movie Database (TMDB) v3 API for movie and TV show information, including search, episode details, and trending content.55 npmMIT
Glama MCP Gateway
Add one secure layer between your agents and this server.