Skip to main content
Glama

Discover movies

discover_movies
Read-only

Filter movies by genre, cast, crew, companies, keywords, release dates, ratings, runtime, or streaming availability to find titles matching specific criteria without text search.

Instructions

Find movies by filters instead of text: genres, people, companies, keywords, release dates, ratings, runtime, streaming availability. Use get_genres for genre IDs and search for person, company or keyword IDs.

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_movies"
  }
}

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"}
regionNoISO 3166-1 country for release date filters
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_castNoPerson IDs in the cast. Comma means AND, pipe means OR
with_crewNoPerson IDs in the crew. Comma means AND, pipe means OR
with_genresNoGenre IDs from get_genres. Comma means AND, pipe means OR, e.g. "28,12" or "28|12"
with_peopleNoPerson IDs in cast or crew. Comma means AND, pipe means OR
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
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
with_origin_countryNoISO 3166-1 origin country, e.g. US, KR
primary_release_yearNoExact primary release year
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
primary_release_date_gteNoReleased on or after, YYYY-MM-DD
primary_release_date_lteNoReleased on or before, YYYY-MM-DD
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

A4.2/5.0
Behavior3/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 structurally. The description adds no behavioral context beyond that: it says nothing about pagination limits, default sort, how many results a page returns, or what happens when a filter combination matches nothing. With annotations carrying the safety burden, 3 is appropriate.

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?

Two sentences, zero filler, and the routing rationale is front-loaded before the ID-lookup dependency. Every clause earns its place and nothing is repeated from the annotation title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 27-parameter, zero-required, no-output-schema discovery tool, the description covers purpose, filter vocabulary, and ID provenance, which is the core of correct invocation. It leaves the pagination ceiling, page-size behavior, and default sort to the schema, which is reasonable but means an agent must open the schema to avoid surprising result windows.

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 96%, so the baseline is 3, but the description adds real value by grouping the 27 parameters into filter families and by naming the cross-tool lookup needed for ID-valued filters (genres, people, keywords) — an agent reading only the schema would not know these IDs come from other tools. It stops short of explaining the AND/OR comma/pipe convention, which is left to 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?

States a specific verb and resource ('Find movies') and immediately distinguishes the mechanism: 'by filters instead of text,' which separates it from the text-search sibling. The enumeration of filter families (genres, people, companies, keywords, release dates, ratings, runtime, streaming) maps directly onto what the tool does, so an agent can route to it without opening the schema.

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?

Gives a clear selection rule — use this when you have structured constraints rather than a query string — and adds a dependency workflow by pointing to get_genres for genre IDs and search for person/company/keyword IDs. It does not state exclusions versus get_trending or get_recommendations, which are also browsing-style siblings, so it falls short of full when/when-not coverage.

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