Skip to main content
Glama

Discover TV shows

discover_tv
Read-only

Find TV shows using filters like genre, network, air date, rating, status, and streaming availability instead of text search.

Instructions

Find TV shows by filters instead of text: genres, networks, companies, keywords, air dates, ratings, status, streaming availability.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "discover_tv"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoResults page, 1-500. Each page holds up to 20 results.
extraNoAny other TMDB discover query parameter, passed through as-is, e.g. {"with_release_type": "4|5", "certification_country": "US"}
sort_byNoSort order, e.g. popularity.desc (default), vote_average.desc, vote_count.desc, revenue.desc
languageNoResponse language as ISO 639-1 with optional ISO 3166-1 region, e.g. en-US or fr-FR. Defaults to TMDB_LANGUAGE.
with_typeNo0 Documentary, 1 News, 2 Miniseries, 3 Reality, 4 Scripted, 5 Talk Show, 6 Video. Pipe means OR
with_genresNoGenre IDs from get_genres. Comma means AND, pipe means OR, e.g. "28,12" or "28|12"
with_statusNo0 Returning Series, 1 Planned, 2 In Production, 3 Ended, 4 Canceled, 5 Pilot. Pipe means OR
air_date_gteNoHas an episode airing on or after, YYYY-MM-DD
air_date_lteNoHas an episode airing on or before, YYYY-MM-DD
watch_regionNoISO 3166-1 country for watch provider filters, e.g. US
include_adultNo
with_keywordsNoKeyword IDs (search type=keyword). Comma means AND, pipe means OR
with_networksNoNetwork IDs, e.g. 213 for Netflix. Pipe means OR
vote_count_gteNoMinimum number of votes, useful with vote_average sorting
with_companiesNoProduction company IDs. Comma means AND, pipe means OR
without_genresNoGenre IDs to exclude, comma separated
vote_average_gteNoMinimum average rating
vote_average_lteNoMaximum average rating
with_runtime_gteNoMinimum runtime in minutes
with_runtime_lteNoMaximum runtime in minutes
without_keywordsNoKeyword IDs to exclude
first_air_date_gteNoFirst aired on or after, YYYY-MM-DD
first_air_date_lteNoFirst aired on or before, YYYY-MM-DD
first_air_date_yearNoExact first air date year
with_origin_countryNoISO 3166-1 origin country, e.g. US, KR
with_watch_providersNoWatch provider IDs (see get_watch_providers). Pipe means OR. Requires watch_region
with_original_languageNoISO 639-1 original language, e.g. en, ko, ja
with_watch_monetization_typesNoflatrate, free, ads, rent or buy. Pipe means OR

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

B3.4/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-data profile is covered. The description adds nothing behavioral beyond that — no note on pagination defaults, the 20-results-per-page and 500-page ceiling, default sort order, or the fact that all 28 filters are optional and combine with AND semantics. What it does list duplicates the parameter surface rather than disclosing behavior.

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?

A single front-loaded sentence with the primary distinction (filters, not text) stated first, then a compact enumeration of filter dimensions. No filler or redundancy, though the enumeration drifts toward restating schema fields rather than guiding use.

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 28-parameter, zero-required, read-only discovery tool with 96% schema coverage and no output schema, the description plus schema gives an agent enough to call it correctly: the schema carries syntax and defaults, and the description carries the filter-vs-text routing signal. Only marginal extras like default sort are missing, which the schema already supplies.

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 96%, so the schema already explains pipe-vs-comma semantics, ID sources, and date formats in detail. The description only names filter categories at a high level and adds no syntax, default, or interaction rules (e.g., that watch_region gates the provider filters) beyond what the schema provides. Baseline 3 is appropriate.

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?

The description states a specific verb and resource ("Find TV shows") and immediately scopes it to filter-based retrieval rather than text queries, which is the key differentiator from the text-search sibling. It does not name that sibling directly, so the contrast is implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"by filters instead of text" gives implied routing guidance: use this when you have structured criteria rather than a keyword string. However, it never names the text search alternative, gives no exclusions (e.g., when to use get_tv_list or get_recommendations instead), and states no prerequisites such as watch_region being required for provider filters.

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