Skip to main content
Glama

tvmaze-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Tvmaze Get Cast

tvmaze_get_cast
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe page size applied to this call — its limit.
castNoCast 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.
crewNoCrew 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.
errorNoPresent when the call failed. Absent on success.
scopeNoWhich credit list was returned.
shownNoNumber of credits returned on this page.
noticeNoGuidance when the page was truncated, or when no cast is recorded — every one that applies, joined. Absent otherwise.
has_moreNoTrue when more credits remain beyond this page.
truncatedNoTrue when the page limit was reached.
cast_totalNoCast credits across every page.
crew_totalNoCrew credits across every page. Present when include_crew was set.
subject_idNoTVmaze id the credits belong to — a show id or an episode id, matching scope.
totalCountNoCredits across every page, cast plus crew.
next_cursorNoPass as cursor to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • changedInput schema / oneOf
      Previous 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"
+  }
+]
    • changedOutput schema / anyOf
      Previous 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"
+    ]
+  }
+]
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The page size applied to this call — its limit.",
+  "type": "number"
+}
    • changedOutput schema / properties / cast / description
      Previous 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."
    • addedOutput schema / properties / cast_total
      Added value: +{
+  "description": "Cast credits across every page.",
+  "type": "number"
+}
    • changedOutput schema / properties / crew / description
      Previous 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."
    • addedOutput schema / properties / crew_total
      Added value: +{
+  "description": "Crew credits across every page. Present when include_crew was set.",
+  "type": "number"
+}
    • addedOutput schema / properties / has_more
      Added value: +{
+  "description": "True when more credits remain beyond this page.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / next_cursor
      Added value: +{
+  "description": "Pass as cursor to fetch the next page. Absent on the last page.",
+  "type": "string"
+}
    • changedOutput schema / properties / notice / description
      Previous 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."
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Number of credits returned on this page.",
+  "type": "number"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Credits returned, cast plus crew."New value: +"Credits across every page, cast plus crew."
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the page limit was reached.",
+  "type": "boolean"
+}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

All tvmaze-mcp-server toolsInspect
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.

Resources