Provides tools for accessing TMDB data: searching movies, TV shows and people; fetching details such as runtime, genres, scores, directors, top cast, budget/revenue and trailers; discovering titles by genre, year, score, runtime, language or streaming service; trending titles, 'more like this' recommendations, and where-to-watch/streaming availability by country.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tmdb-mcp find me a 90s thriller on Netflix under 2 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives AI agents access to The Movie Database (TMDB): movies, TV shows, people, trending titles, recommendations and where to watch.
It is designed around how agents actually use tools, not around TMDB's endpoints:
Compact, typed outputs. Every tool returns a trimmed result with a declared output schema (structuredContent). Agents pay for each token a tool returns, so raw TMDB payloads (image paths, popularity floats, duplicate ids) are cut down to the fields that help answer questions.
Names, not ids. discover takes genres and streaming services by name ("sci-fi", "Netflix") and resolves them to TMDB ids itself, so "a 90s thriller on Netflix under 2 hours" is a single call.
One call per question. Detail tools bundle what is usually needed together (credits, trailer, top cast), instead of making the agent chain three requests.
Errors the agent can act on. Unknown genres come back with the list of valid ones; a 404 tells the agent to search for a valid id first.
Production basics. In-memory TTL/LRU cache, retries with Retry-After on 429/5xx, request timeouts, and an HTTP mode with bearer auth and per-client rate limiting.
Characters returned to the agent versus the raw TMDB response for the same request (npm run smoke, 14 Oct 2026):
Tool | Example | Tool output | Raw TMDB | Reduction |
| Inception, with credits and videos | 1,115 | 213,588 | 99.4% |
| Inception, US | 432 | 88,595 | 99.5% |
| Christopher Nolan, with credits | 2,350 | 96,965 | 97.5% |
| "Inception" | 4,184 | 7,063 | 40.7% |
| sci-fi on Netflix, score ≥ 7 | 8,179 | 12,920 | 36.6% |
The large savings come from endpoints that return far more than a question needs: full cast and crew lists, every video, every country's streaming offers. Search and discover results are already lists of summaries, so the saving there comes from dropping image paths and internal fields.
Tool | What it does |
| Find movies by title (optionally by year) |
| Find TV series by name |
| Find actors, directors and crew |
| Runtime, genres, score, directors, writers, top cast, budget, revenue, trailer |
| Status, seasons, episodes, networks, creators, top cast |
| Biography and the 15 best-known credits with roles |
| Where a title streams, rents or sells in a given country |
| Find titles by genres, years, score, runtime, language and streaming service |
| Trending movies, shows or people, today or this week |
| "More like this" for a movie or show |
It also provides a resource, tmdb://genres, with the valid genre names, and a movie_night prompt that picks three movies for a group from the services they subscribe to.
Related MCP server: TMDB MCP Server
Get a free TMDB API Read Access Token at https://www.themoviedb.org/settings/api.
Add the server to your MCP client.
Claude Code
claude mcp add tmdb -e TMDB_READ_ACCESS_TOKEN=your-token -- npx -y @wsqreis/tmdb-mcpClaude Desktop (claude_desktop_config.json) or any client using the same format:
{
"mcpServers": {
"tmdb": {
"command": "npx",
"args": ["-y", "@wsqreis/tmdb-mcp"],
"env": { "TMDB_READ_ACCESS_TOKEN": "your-token" }
}
}
}VS Code (.vscode/mcp.json):
{
"inputs": [{ "id": "tmdb-token", "type": "promptString", "description": "TMDB Read Access Token", "password": true }],
"servers": {
"tmdb": {
"command": "npx",
"args": ["-y", "@wsqreis/tmdb-mcp"],
"env": { "TMDB_READ_ACCESS_TOKEN": "${input:tmdb-token}" }
}
}
}Then ask things like:
"What should I watch tonight? Something like Arrival, available on Netflix in the UK."
"Which movies have Denis Villeneuve and Roger Deakins made together?"
"Best-rated Korean thrillers from the 2010s under two hours."
The same server can run as a remote MCP endpoint over Streamable HTTP:
TMDB_READ_ACCESS_TOKEN=... MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) npx -y @wsqreis/tmdb-mcp --http
# or
docker build -t tmdb-mcp . && docker run -p 3000:3000 --env-file .env tmdb-mcpPOST /mcp requires Authorization: Bearer <MCP_HTTP_AUTH_TOKEN>. The server refuses to start in HTTP mode without a token, so it is never exposed without auth by accident.
Each client IP gets a token bucket of MCP_HTTP_RATE_LIMIT_PER_MINUTE requests (default 60). Over the limit it returns 429 with Retry-After.
It runs stateless: a fresh MCP server per request, so instances scale horizontally without sticky sessions.
GET /healthz is open for load balancers and container health checks.
When deploying behind a reverse proxy, every request will appear to come from the proxy's IP. Enforce per-client limits at the proxy, or extend the limiter to read a trusted X-Forwarded-For.
Variable | Default | |
| – | v4 token (preferred), sent as a bearer header |
| – | v3 key, used only if no read access token is set |
|
| Language of titles and overviews |
|
| Default country for watch providers and |
|
|
|
|
| LRU eviction above this |
|
| Per-request timeout and retries on 429/5xx |
|
| HTTP mode only |
| – | Required in HTTP mode |
|
| Per client IP, |
Requires Node.js 22.18+ (TypeScript runs natively in development; the published package is compiled to JavaScript).
npm install
npm test # unit + MCP protocol + HTTP tests, no network needed
npm run typecheck
npm run inspect # open the MCP Inspector against the local server
cp .env.example .env && npm run smoke # live check against TMDB, with output-size comparisonThe tests drive the server through a real MCP client over an in-memory transport, with a fake fetch standing in for TMDB, so they cover schemas, argument validation and error handling end to end without network access.
src/
├── index.ts # entry point: stdio (default) or --http
├── server.ts # MCP server: tools, resource, prompt, instructions
├── schemas.ts # zod output schemas (compact shapes)
├── tools/ # tool definitions, name→id resolution, error mapping
├── tmdb/ # HTTP client (auth, cache, retries), raw types, formatters
└── http/ # Streamable HTTP app, bearer auth, rate limiterThis product uses the TMDB API but is not endorsed or certified by TMDB. Streaming availability data is provided by JustWatch through TMDB.
Find titles by criteria instead of by name: genres (by name, e.g. "sci-fi", "comedy"), year range, minimum score, max runtime, original language and streaming service (e.g. "Netflix") in a country. Best tool for requests like "a good 90s thriller on Netflix under 2 hours".
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| genres | No | All of these genres must match | |
| region | No | Country for `streamingOn`, ISO 3166-1 (default: server region) | |
| sortBy | No | popularity | |
| yearTo | No | ||
| minVotes | No | Minimum vote count; keeps obscure titles with a handful of votes out of rating sorts | |
| yearFrom | No | ||
| mediaType | No | movie | |
| minRating | No | Minimum TMDB score, 0-10 | |
| streamingOn | No | Streaming services by name; matches titles available on ANY of them in `region` | |
| excludeGenres | No | ||
| originalLanguage | No | ISO 639-1 code of the original language, e.g. "ko" for Korean | |
| maxRuntimeMinutes | No |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| totalPages | Yes | |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety and determinism profile is covered. The description adds no behavior beyond the annotation layer - nothing about pagination limits, default sort semantics, or how streaming availability is resolved per region. With annotations present the bar is lower, so 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler: the first defines the criteria-based mode and the second gives a concrete usage example. Front-loaded with the distinguishing concept rather than burying it.
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 13-parameter tool with an output schema available, the description covers the discovery-facing filters well enough to call it correctly. The gaps are on the control parameters (mediaType default of "movie", sortBy, page, excludeGenres), which matter for a broad-discovery tool but are partially recoverable from schema defaults and enums.
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 only 46%, so the description usefully compensates by enumerating the main filters (genres, year range, minimum score, max runtime, original language, streaming service, region) and giving value examples like "sci-fi" and "Netflix" that the schema lacks. It still leaves page, sortBy, mediaType and excludeGenres entirely unaddressed.
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?
"Find titles by criteria instead of by name" is a specific verb+resource that draws a clean line against the name-based search siblings (search_movies, search_tv_shows), and the enumerated criteria show the shape of the query. It stops short of 5 because it never names a sibling and never explains that this single tool covers both movies and TV while the siblings split them.
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 closing sentence gives an explicit positive trigger ("a good 90s thriller on Netflix under 2 hours") plus the implicit negative case (name-based lookup belongs to the search_* tools). There is no explicit "do not use for person lookups / details" routing despite four detail and people-oriented siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details for one movie in a single call: runtime, genres, score, directors, writers, top cast, budget, revenue and trailer.
| Name | Required | Description | Default |
|---|---|---|---|
| movieId | Yes | TMDB movie id (from search_movies or discover) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| title | Yes | |
| votes | Yes | Number of TMDB votes behind the score |
| genres | Yes | |
| imdbId | Yes | |
| rating | Yes | TMDB user score, 0-10 |
| tagline | Yes | |
| topCast | Yes | |
| writers | Yes | |
| overview | Yes | |
| budgetUsd | Yes | |
| directors | Yes | |
| revenueUsd | Yes | |
| trailerUrl | Yes | |
| releaseDate | Yes | |
| runtimeMinutes | Yes | |
| originalLanguage | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the bar is lower; the description adds useful context by listing the concrete fields returned and noting it is a single-call operation. It does not mention auth needs, rate limits, or trailer availability caveats, so it stops short of a 5.
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?
One front-loaded sentence with no filler, leading with the core purpose before the field list. The field enumeration is slightly list-heavy but each item is informative rather than padding.
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 tool with an output schema and full annotation coverage, the description is essentially sufficient: purpose, scope and returned content are clear. The only gap is the absence of routing guidance relative to sibling tools.
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?
There is one parameter and schema description coverage is 100%: the schema already documents movieId as a TMDB id sourced 'from search_movies or discover'. The description adds no additional parameter meaning, so the baseline 3 applies.
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?
States a specific verb+resource ('Full details for one movie') and enumerates exactly what is returned. The resource type ('movie') cleanly separates it from siblings like get_tv_show_details and get_person_details without needing to name them.
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?
Usage is only implied: 'Full details for one movie in a single call' suggests using it when you already have a movieId and want everything at once. There is no explicit when-to-use, when-not, or alternative routing (e.g., versus calling several smaller endpoints).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Biography and the 15 best-known movies/shows of an actor or crew member, with the role they had in each.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | TMDB person id (from search_people) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| birthday | Yes | |
| deathday | Yes | |
| biography | Yes | |
| department | Yes | |
| placeOfBirth | Yes | |
| notableCredits | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and openWorld behavior, so the safety profile is covered. The description adds a genuinely useful behavioral detail beyond the annotations: the results are capped at the 15 best-known credits, telling the agent to expect a truncated list rather than the full filmography.
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?
A single compact sentence with no filler; the separate 'what it does' and 'what it returns' information is packed into one clause. It is front-loaded and appropriately sized for a one-parameter read tool.
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?
With an output schema present, the description need not explain return structure, and annotations cover the safety profile. For a simple ID-based lookup this is nearly complete; only routing guidance against siblings is absent.
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% and the single personId parameter is fully documented in the schema, including its constraint and provenance from search_people. The description adds no meaning beyond that, so the baseline of 3 applies.
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 exactly what the tool returns for a person resource: biography plus their 15 best-known movies/shows with each role. That clearly separates it from get_movie_details and get_tv_show_details, though it is phrased as content rather than an action verb ('retrieve').
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?
Usage is only implied by the name and the 'get details' pattern shared with siblings. There is no explicit statement of when to call this versus search_people or the movie/TV detail tools, and no mention that a personId from search_people must be obtained first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Titles that people who liked a given movie or show also liked. Use for "something like X" requests; combine with get_watch_providers to check availability.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | TMDB id of the title to base recommendations on | |
| page | No | ||
| mediaType | Yes |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| totalPages | Yes | |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description does add the non-obvious fact that results are collaborative-filtering based rather than keyword-similar, but says nothing about pagination limits (page max 500) or result volume.
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 tight sentences with the core semantics front-loaded and the practical follow-up second. No filler.
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?
With an output schema present, return values need not be described, and annotations cover safety. For a 3-parameter tool this is close to complete; the only real gap is the undocumented page/mediaType parameters.
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 only 33% — id is documented, but page and mediaType carry no descriptions. The description compensates for none of this: it never explains what id refers to (a TMDB id), what mediaType controls, or how paging works.
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?
States a specific resource and its derivation clearly: 'Titles that people who liked a given movie or show also liked.' This distinguishes it from search_movies/search_tv_shows (query-driven) and discover (filter-driven), though it never names a sibling to contrast with.
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?
Gives a concrete trigger ('something like X' requests) and a follow-up action (combine with get_watch_providers), which is real routing guidance. It stops short of stating when NOT to use it, e.g. when the user wants to search by title text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is trending on TMDB today or this week: movies, TV shows, people, or all of them mixed.
| Name | Required | Description | Default |
|---|---|---|---|
| mediaType | No | all | |
| timeWindow | No | week |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no note about data freshness, result limits, or region/language effects, even though 'trending' data is inherently time-sensitive and locale-dependent.
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?
A single front-loaded sentence with no filler; the two selection axes are packed in without redundancy. It is appropriately sized for a two-parameter lookup tool.
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 simple read-only trending lookup, the annotations cover safety, the output schema covers return values, and the description covers both input axes. Nothing critical is missing, though a note on what 'trending' means (ranking window, region) would complete it.
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 0%, so the description must carry the load. It maps both parameters to natural language ('today or this week' for timeWindow; 'movies, TV shows, people, or all of them mixed' for mediaType), and 'all of them mixed' genuinely clarifies what the 'all' enum value does. However it omits the defaults (week, all) and adds little that the enum names don't already convey.
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 clearly identifies the resource (trending content on TMDB) and its scope (media types and time window), which is enough to distinguish it from the search_*, discover, and get_*_details siblings. It is phrased as a question rather than a verb+resource statement, so it stops short of a 5, but the intent is 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?
Usage is only implied: an agent can infer this is the tool for 'what's trending' questions, but the description never says when to prefer it over discover or search_movies/search_tv_shows, nor does it state any exclusions or prerequisites. That is the definition of implied-only guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details for one TV series: status, seasons, episodes, networks, creators, top cast and score.
| Name | Required | Description | Default |
|---|---|---|---|
| tvId | Yes | TMDB TV show id (from search_tv_shows or discover) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| votes | Yes | Number of TMDB votes behind the score |
| genres | Yes | |
| rating | Yes | TMDB user score, 0-10 |
| status | Yes | |
| seasons | Yes | |
| topCast | Yes | |
| creators | Yes | |
| episodes | Yes | |
| networks | Yes | |
| overview | Yes | |
| lastAirDate | Yes | |
| firstAirDate | Yes | |
| episodeRuntimeMinutes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds nothing beyond that — no note on caching, rate limits, or whether missing/unknown IDs error or return empty — so it is adequate but not enriching.
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?
One sentence, front-loaded with the scope ('one TV series') and then the field list; every clause earns its place with no filler.
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 simple one-param, idempotent read tool with an output schema present, the description is essentially sufficient — return values need not be explained and annotations carry safety. It would be marginally stronger with a one-clause pointer to how to obtain a tvId.
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?
With schema description coverage at 100%, the single tvId parameter is fully documented in the schema (TMDB id, sourced from search_tv_shows or discover). The description adds no additional parameter meaning, so the baseline 3 applies.
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?
States a clear verb+resource (fetch full details for one TV series) and enumerates the returned fields, so the agent knows exactly what it gets back. The 'TV' qualifier implicitly separates it from get_movie_details and get_person_details, though it never names those siblings explicitly.
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?
Usage is only implied: 'for one TV series' plus the required tvId signals a single-item lookup after a search. There is no explicit when-to-use/when-not statement or pointer at search_tv_shows/discover (that pointer lives only in the schema param description).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a movie or show can be streamed, rented or bought in a country. Data comes from JustWatch; mention that source when showing it to users.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | TMDB movie or TV show id | |
| region | No | ISO 3166-1 country code, e.g. "US", "GB", "DE". Defaults to the server region. | |
| mediaType | Yes |
| Name | Required | Description |
|---|---|---|
| buy | Yes | |
| free | Yes | |
| link | Yes | TMDB page listing all offers for this title |
| rent | Yes | |
| region | Yes | |
| withAds | Yes | |
| available | Yes | |
| attribution | Yes | |
| subscription | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds two things they cannot: the upstream data provenance (JustWatch) and a compliance requirement to attribute that source to users. It still says nothing about caching, freshness, or rate limits on a third-party data source.
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, no filler, with the core capability front-loaded and the attribution obligation as a short trailing sentence. Every sentence 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?
An output schema exists, so return values need not be explained, and the description covers scope, region granularity and the source. The remaining gap is relational: it never tells the agent how this complements get_movie_details or that a media id must be obtained first.
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 67% and the schema itself documents id (TMDB id), region (ISO 3166-1 with default) and the mediaType enum. The description only echoes the concepts of country and movie/show, adding no syntax or format detail beyond the schema, so baseline 3 is appropriate.
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 concrete resource and outcome: where a movie or show can be streamed, rented or bought in a country. That clearly separates it from search_movies, get_movie_details and the other discovery siblings, though it uses a noun phrase rather than an explicit verb and never names a sibling.
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?
There is no when-to-use guidance, no statement of prerequisites (a TMDB movie/TV id is required), and no differentiation from get_movie_details, which an agent might reasonably assume also carries provider data. The only usage-like instruction concerns displaying the source, not selecting the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find movies by title (fuzzy). Returns ids to use with get_movie_details, get_recommendations and get_watch_providers. Pass year to disambiguate remakes.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Results page (20 per page) | |
| year | No | Release year | |
| query | Yes | Movie title or part of it |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| totalPages | Yes | |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the description only needs to add non-obvious behavior. It does: fuzzy matching semantics and the fact that the payload is ids keyed for downstream tools rather than movie records. Pagination behavior (20 per page, up to page 500) is left entirely to the schema.
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 short sentences with no filler. The core operation and its fuzzy nature are front-loaded, and the downstream-routing and disambiguation hints follow in priority order.
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?
An output schema exists, so return-value detail is not the description's job, and it still usefully summarizes the key return fact (ids). For a simple three-parameter search whose annotations cover safety and idempotency, nothing an agent needs to call 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 baseline is 3. The description exceeds it by explaining *why* `year` exists — to disambiguate remakes — which the schema's bare "Release year" does not convey. `query` and `page` are still only defined by the schema, hence not a 5.
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?
States a specific verb and resource ("Find movies by title") and immediately qualifies the matching mode as fuzzy. It is trivially distinguishable from search_tv_shows and search_people, and the note that it returns ids rather than full records sharpens the scope further.
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 routes the caller downstream ("ids to use with get_movie_details, get_recommendations and get_watch_providers") and gives a concrete condition for the year parameter ("disambiguate remakes"). It stops short of saying when to prefer the `discover` sibling for genre/browse-style queries, so the alternative-selection guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find actors, directors and other crew by name. Returns ids to use with get_person_details.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Results page (20 per page) | |
| query | Yes | Person name |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| totalPages | Yes | |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety and idempotency profile is covered. The description only adds that results are ids intended for chaining into get_person_details, which is useful context but not rich behavioral disclosure.
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 brief sentences, zero filler, and the core purpose is front-loaded before the chaining hint.
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?
With an output schema present and full annotation coverage, the description needn't explain return values; it usefully names the follow-up tool. Complete enough for an agent to call correctly, though paging behavior on this search could be mentioned.
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% and both parameters (query, page) are documented in the schema. The description's 'by name' merely restates the query parameter and adds nothing about paging or matching semantics, so the baseline 3 applies.
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?
States a specific verb ('Find') and resource ('actors, directors and other crew'), scoping it to people rather than titles. This clearly distinguishes it from siblings search_movies and search_tv_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 second sentence gives a concrete downstream workflow ('Returns ids to use with get_person_details'), which tells the agent how this tool fits into a chain. It does not state when to prefer a different search or any exclusions, so it falls short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find TV series by name (fuzzy). Returns ids to use with get_tv_show_details and other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Results page (20 per page) | |
| query | Yes | Show name or part of it | |
| firstAirYear | No | Year the show first aired |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| totalPages | Yes | |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld and idempotent, so safety is covered. The description adds genuinely useful behavior beyond them: matching is fuzzy and the return payload is identifiers intended for chaining into get_tv_show_details. Pagination/result-count behavior is left to the schema.
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 short sentences, zero filler, with the matching behavior and the chaining purpose 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 simple three-parameter search with an output schema and full annotation coverage, the description supplies the two things the structured data can't convey: fuzzy matching and the downstream use of returned ids. Nothing critical 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%, documenting query, page and firstAirYear, so the baseline is 3. The description only restates the 'by name' semantics of the query parameter and adds nothing about page or firstAirYear filtering.
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?
States a specific verb (find/search) plus resource (TV series) and adds the matching semantics ('by name (fuzzy)'). The resource name itself separates it from search_movies/search_people, though no explicit sibling contrast is drawn.
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?
'Returns ids to use with get_tv_show_details and other tools' establishes the workflow context: use this to resolve a name into an id before fetching details. It gives clear positive usage but no explicit when-not or alternative-search guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0discoverget_movie_detailsget_person_detailsget_recommendationsget_trendingget_tv_show_detailsget_watch_providerssearch_moviessearch_peoplesearch_tv_showsScored across 10 tools
Each tool targets a distinct intent: search_* tools find by name for a specific resource type, discover browses by filters, and the get_* tools each retrieve details for a specific resource. discover vs search_movies and get_recommendations vs discover are the closest overlap but descriptions clearly delineate criteria-based browsing from name lookup and 'more like X' requests.
Consistent verb_noun pattern across search_movies, search_tv_shows, search_people, get_movie_details, get_tv_show_details, get_person_details, get_watch_providers, get_trending, and get_recommendations. The lone outlier is the bare-verb 'discover', a minor deviation.
Ten tools is well-scoped for a media discovery domain, with search, details, discovery, trending, recommendations, and availability each earning a distinct slot without redundancy.
The surface covers the core lifecycle: finding titles/people, browsing by filters, fetching details, watching providers, trending, and recommendations. Minor gaps exist around season/episode-level detail and collection/list operations, but agents can work around these.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
Search movies/TV by mood, genre, score, cast, and awards, filtered to what's streaming near you.
Media memory for AI agents and their humans: books, movies, music, shows, anime, podcasts, games.
15 media & data tools for AI agents: search, transcribe, subtitles, voiceover, translate & more.