Skip to main content
Glama

Tvmaze Search Shows

tvmaze_search_shows
Read-onlyIdempotent

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "tvmaze_search_shows"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesShow title or title fragment. Matched fuzzily against every show title in the database, so minor misspellings still resolve.

Output Schema

NameRequiredDescriptionDefault
capNoThe result ceiling the source applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of shows returned.
showsNoMatching shows, best match first. At most 10.
noticeNoGuidance when nothing matched or when the ten-result ceiling was reached. Absent otherwise.
truncatedNoTrue when the source's fixed ten-result ceiling was reached.
effectiveQueryNoThe query as submitted upstream.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / shows / items / properties / network
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Broadcast or cable network, when recorded.",
      +  "properties": {
      +    "country": {
      +      "description": "ISO 3166-1 alpha-2 country of this carrier.",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "Carrier name as TVmaze records it.",
      +      "type": "string"
      +    },
      +    "timezone": {
      +      "description": "IANA timezone recorded for this carrier.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "name"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / shows / items / properties / web_channel
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Streaming service, when recorded.",
      +  "properties": {
      +    "country": {
      +      "description": "ISO 3166-1 alpha-2 country of this carrier.",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "Carrier name as TVmaze records it.",
      +      "type": "string"
      +    },
      +    "timezone": {
      +      "description": "IANA timezone recorded for this carrier.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "name"
      +  ],
      +  "type": "object"
      +}
  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 cover the safety profile (readOnlyHint, openWorldHint, idempotentHint), and the description goes well beyond them by disclosing the hard 10-result cap, the absence of pagination, and the fuzzy matching behavior that tolerates typos. These are non-obvious traits that materially change how an agent should call and re-call the tool, and none of them are derivable from the annotations.

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?

Four sentences, each carrying distinct information: what it does and returns, the fuzzy-matching trait, the cap/pagination constraint with its remedy, and the sibling routing. The most consequential constraints are front-loaded and there is no filler or restatement of the tool name.

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 one-parameter search tool with an output schema and full annotation coverage, everything an agent needs is present: input semantics, result shape and cap, non-pageability, and the alternative for id-based lookup. No behavioral or routing question is left to inference.

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?

With a single parameter and 100% schema description coverage, the schema already documents that 'query' is a title or fragment matched fuzzily. The description restates the fuzzy-matching behavior and adds the practical implication that narrowing the title is the only way past the cap, but supplies no additional syntax, format, or normalization detail beyond the schema.

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?

Opens with a specific verb and resource — 'Search television shows by title' — and immediately enumerates what each of the up to 10 matches contains (network/streamer, status, genres, rating, external ids). It also names the sibling it is not ('tvmaze_lookup_show') and the direction that sibling covers, so an agent can route without opening either schema.

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?

Gives explicit operational guidance: the result set is hard-capped at 10 by the source, cannot be paged, and the workaround is to narrow the title. It also names the inverse case explicitly — 'from an IMDb or TheTVDB id to a show, use tvmaze_lookup_show' — providing both when-to-use and when-to-use-something-else.

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.