Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

Get movie details

get_movie
Read-only

Fetches full details for one movie by TMDB ID, including overview, genres, runtime, budget and revenue, vote average, age certification for your region, and IMDb/Rotten Tomatoes/Metacritic ratings.

Instructions

Get full details for one movie by TMDB id: overview, genres, keywords ({id, name}), runtime, budget/revenue, vote average, the age/content rating (certification) for region (falling back to the US rating, then any available country, when region has none; check certification_region to see which one was used), and links (TMDB + IMDb). By default also includes IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary (see include_ratings), plus OMDb's own age rating (ratings.rated, separate from this tool's certification; the two can differ), from OMDb (set include_ratings=false to skip). If unavailable (no OMDB_API_KEY, no imdb_id, or the OMDb lookup fails), ratings degrades to {found:false, reason} instead of failing the call. For titles like this one, get_movie_recommendations is the first stop; to match its themes instead, pass 2-3 distinctive keyword ids to discover_movies' with_keywords joined with ',' (all must match; checked live: The Matrix's 'man vs machine', 'artificial intelligence', 'dystopia' give the Terminator films); '|' broadens to any one. If you only need the headline info (title/year/genres/vote average), for one id or several, use get_movies: it's trimmed and skips the rest of this payload. Get the id from search_movies.

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": {
      "id": "<id>"
    },
    "name": "get_movie"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesTMDB movie id (from search_movies).
regionNoThe user's country (pass it when known), whose age rating `certification` shows (falling back to the US rating, then any country's).US
languageNoResponse language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name.en-US
include_ratingsNoAdd IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary from OMDb (requires OMDB_API_KEY). The summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates), not a structured count, and covers the whole film/show, not any one person's award. Set false to skip the extra lookup.

Output Schema

NameRequiredDescriptionDefault
idYes
yearYes
titleNo
genresYes
statusYes
imdb_idYes
ratingsNo
taglineYes
homepageYes
imdb_urlYes
keywordsYes
overviewYes
tmdb_urlYes
budget_usdYes
collectionYes
media_typeYes
popularityYes
poster_urlYes
vote_countYes
revenue_usdYes
release_dateYes
vote_averageYesTMDB's own 0-10 user score. A different audience and scale from the IMDb/RT/Metacritic scores get_movie/get_tv return as `ratings` — don't compare, average or substitute across the two.
certificationYes
certificationsYes
origin_countryYes
original_titleNo
runtime_minutesYes
spoken_languagesYes
original_languageYes
certification_regionYes
production_companiesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.15.0
    • changedInput schema / properties / id / description
      Previous value: -"TMDB numeric id."New value: +"TMDB movie id (from search_movies)."
    • addedInput schema / properties / include_ratings / default
      Added value: +true
    • changedInput schema / properties / include_ratings / description
      Previous value: -"If true (default), enrich the result with IMDb/Rotten Tomatoes/Metacritic ratings plus an awards summary (major-award wins/nominations — Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates; free text, not a structured count, and describes the whole film/show, not any one person's award) from OMDb (requires OMDB_API_KEY). Set false to skip the extra lookup when ratings are not needed."New value: +"Add IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary from OMDb (requires OMDB_API_KEY). The summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates), not a structured count, and covers the whole film/show, not any one person's award. Set false to skip the extra lookup."
    • addedInput schema / properties / language / default
      Added value: +"en-US"
    • changedInput schema / properties / language / description
      Previous value: -"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."New value: +"Response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'; pass the user's language when it isn't the default. Localizes titles/overviews/genre names. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."
    • addedInput schema / properties / region / default
      Added value: +"US"
    • changedInput schema / properties / region / description
      Previous value: -"ISO-3166-1 country code for region-specific results (default 'US')."New value: +"The user's country (pass it when known), whose age rating `certification` shows (falling back to the US rating, then any country's)."
    • addedOutput schema / properties / keywords
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "id": {
      +        "type": "number"
      +      },
      +      "name": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "name"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "id",
      -  "imdb_id",
      -  "media_type",
      -  "certification",
      -  "certification_region",
      -  "certifications",
      -  "tagline",
      -  "overview",
      -  "year",
      -  "release_date",
      -  "runtime_minutes",
      -  "status",
      -  "genres",
      -  "vote_average",
      -  "vote_count",
      -  "popularity",
      -  "original_language",
      -  "spoken_languages",
      -  "production_companies",
      -  "origin_country",
      -  "collection",
      -  "budget_usd",
      -  "revenue_usd",
      -  "homepage",
      -  "poster_url",
      -  "tmdb_url",
      -  "imdb_url"
      -]New value: +[
      +  "id",
      +  "imdb_id",
      +  "media_type",
      +  "certification",
      +  "certification_region",
      +  "certifications",
      +  "tagline",
      +  "overview",
      +  "year",
      +  "release_date",
      +  "runtime_minutes",
      +  "status",
      +  "genres",
      +  "keywords",
      +  "vote_average",
      +  "vote_count",
      +  "popularity",
      +  "original_language",
      +  "spoken_languages",
      +  "production_companies",
      +  "origin_country",
      +  "collection",
      +  "budget_usd",
      +  "revenue_usd",
      +  "homepage",
      +  "poster_url",
      +  "tmdb_url",
      +  "imdb_url"
      +]
  2. Changed36 schema fields changedv0.14.0
    • changedInput schema / properties / language / description
      Previous value: -"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE."New value: +"Override the response language (ISO-639-1, optionally with a region), e.g. 'ru-RU' or 'en-US'. Localizes titles/overviews/genre names. Defaults to the server's TMDB_LANGUAGE. A well-formed code TMDB has no translation for (e.g. 'xx') is not an error: overviews come back null, movies/shows keep their original-language title, and episodes get a generic 'Episode N' name."
    • removedOutput schema / properties / budget_usd / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / budget_usd / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / certification / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / certification / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedOutput schema / properties / collection / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "id": {
      -        "type": "number"
      -      },
      -      "name": {
      -        "type": "string"
      -      },
      -      "poster_url": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "poster_url"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "id": {
      +        "type": "number"
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "poster_url": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "poster_url"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / homepage / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / homepage / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / imdb_id / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / imdb_id / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / imdb_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / imdb_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / original_language / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / original_language / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / overview / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / overview / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / popularity / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / popularity / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / poster_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / poster_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedOutput schema / properties / ratings / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "found": {
      -        "const": false,
      -        "type": "boolean"
      -      },
      -      "reason": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "found",
      -      "reason"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "awards": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "found": {
      -        "const": true,
      -        "type": "boolean"
      -      },
      -      "imdb_id": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "imdb_rating": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "imdb_votes": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "metascore": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "rated": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "ratings": {
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "source": {
      -              "type": "string"
      -            },
      -            "value": {
      -              "type": "string"
      -            }
      -          },
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "rotten_tomatoes": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "runtime": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "title": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "year": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "found",
      -      "imdb_id",
      -      "title",
      -      "year",
      -      "rated",
      -      "runtime",
      -      "imdb_rating",
      -      "imdb_votes",
      -      "metascore",
      -      "rotten_tomatoes",
      -      "awards",
      -      "ratings"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "found": {
      +        "const": false,
      +        "type": "boolean"
      +      },
      +      "reason": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "found",
      +      "reason"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "awards": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "found": {
      +        "const": true,
      +        "type": "boolean"
      +      },
      +      "imdb_id": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "imdb_rating": {
      +        "description": "IMDb user score, 0-10, as a string, e.g. '6.5'. Not TMDB's `vote_average`.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "imdb_votes": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "metascore": {
      +        "description": "Metacritic critic score, 0-100 scale, as a string, e.g. '67'.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "rated": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "ratings": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "source": {
      +              "type": "string"
      +            },
      +            "value": {
      +              "type": "string"
      +            }
      +          },
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "rotten_tomatoes": {
      +        "description": "Rotten Tomatoes Tomatometer — the percentage of positive critic reviews, as a string including the sign, e.g. '79%'. Not a 0-10 or 0-100 score.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "runtime": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "title": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "year": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "found",
      +      "imdb_id",
      +      "title",
      +      "year",
      +      "rated",
      +      "runtime",
      +      "imdb_rating",
      +      "imdb_votes",
      +      "metascore",
      +      "rotten_tomatoes",
      +      "awards",
      +      "ratings"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties / revenue_usd / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / revenue_usd / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / runtime_minutes / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / runtime_minutes / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / status / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / status / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / tagline / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / tagline / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / vote_average / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / vote_average / description
      Added value: +"TMDB's own 0-10 user score. A different audience and scale from the IMDb/RT/Metacritic scores get_movie/get_tv return as `ratings` — don't compare, average or substitute across the two."
    • addedOutput schema / properties / vote_average / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / vote_count / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / vote_count / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / year / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / year / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  3. Changed2 schema fields changedv0.10.1
    • changedOutput schema / properties / release_date / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "date",
      +    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / release_date / default
      Added value: +null
  4. Addedv0.8.1
  5. Removedv0.8.1
  6. Changed4 schema fields changedv0.8.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / include_ratings / description
      Previous value: -"If true (default), enrich the result with IMDb/Rotten Tomatoes/Metacritic ratings from OMDb (requires OMDB_API_KEY). Set false to skip the extra lookup when ratings are not needed."New value: +"If true (default), enrich the result with IMDb/Rotten Tomatoes/Metacritic ratings plus an awards summary (major-award wins/nominations — Oscars, Emmys, Golden Globes, etc., whatever OMDb aggregates; free text, not a structured count, and describes the whole film/show, not any one person's award) from OMDb (requires OMDB_API_KEY). Set false to skip the extra lookup when ratings are not needed."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "budget_usd": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "certification": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "certification_region": {
      +      "type": "string"
      +    },
      +    "certifications": {
      +      "additionalProperties": {
      +        "type": "string"
      +      },
      +      "propertyNames": {
      +        "type": "string"
      +      },
      +      "type": "object"
      +    },
      +    "collection": {
      +      "anyOf": [
      +        {
      +          "additionalProperties": false,
      +          "properties": {
      +            "id": {
      +              "type": "number"
      +            },
      +            "name": {
      +              "type": "string"
      +            },
      +            "poster_url": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            }
      +          },
      +          "required": [
      +            "poster_url"
      +          ],
      +          "type": "object"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "genres": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "homepage": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "id": {
      +      "type": "number"
      +    },
      +    "imdb_id": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "imdb_url": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "media_type": {
      +      "const": "movie",
      +      "type": "string"
      +    },
      +    "origin_country": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "original_language": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "original_title": {
      +      "type": "string"
      +    },
      +    "overview": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "popularity": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "poster_url": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "production_companies": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "ratings": {
      +      "oneOf": [
      +        {
      +          "additionalProperties": false,
      +          "properties": {
      +            "found": {
      +              "const": false,
      +              "type": "boolean"
      +            },
      +            "reason": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "found",
      +            "reason"
      +          ],
      +          "type": "object"
      +        },
      +        {
      +          "additionalProperties": false,
      +          "properties": {
      +            "awards": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "found": {
      +              "const": true,
      +              "type": "boolean"
      +            },
      +            "imdb_id": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "imdb_rating": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "imdb_votes": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "metascore": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "rated": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "ratings": {
      +              "items": {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "source": {
      +                    "type": "string"
      +                  },
      +                  "value": {
      +                    "type": "string"
      +                  }
      +                },
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "rotten_tomatoes": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "runtime": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "title": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            },
      +            "year": {
      +              "anyOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ]
      +            }
      +          },
      +          "required": [
      +            "found",
      +            "imdb_id",
      +            "title",
      +            "year",
      +            "rated",
      +            "runtime",
      +            "imdb_rating",
      +            "imdb_votes",
      +            "metascore",
      +            "rotten_tomatoes",
      +            "awards",
      +            "ratings"
      +          ],
      +          "type": "object"
      +        }
      +      ]
      +    },
      +    "release_date": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "revenue_usd": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "runtime_minutes": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "spoken_languages": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "status": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "tagline": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "title": {
      +      "type": "string"
      +    },
      +    "tmdb_url": {
      +      "type": "string"
      +    },
      +    "vote_average": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "vote_count": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    },
      +    "year": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ]
      +    }
      +  },
      +  "required": [
      +    "id",
      +    "imdb_id",
      +    "media_type",
      +    "certification",
      +    "certification_region",
      +    "certifications",
      +    "tagline",
      +    "overview",
      +    "year",
      +    "release_date",
      +    "runtime_minutes",
      +    "status",
      +    "genres",
      +    "vote_average",
      +    "vote_count",
      +    "popularity",
      +    "original_language",
      +    "spoken_languages",
      +    "production_companies",
      +    "origin_country",
      +    "collection",
      +    "budget_usd",
      +    "revenue_usd",
      +    "homepage",
      +    "poster_url",
      +    "tmdb_url",
      +    "imdb_url"
      +  ],
      +  "type": "object"
      +}
  7. First observedv0.3.0

TDQS

A4.5/5.0
Behavior4/5

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

Well beyond the readOnly/openWorld annotations: it discloses graceful degradation for OMDb ('ratings' becomes {found:false, reason} rather than failing), the three-step certification fallback (region → US → any country) with certification_region as the audit field, and the OMDB_API_KEY dependency. It stops short of detailing pagination/response shape, but the output schema is declared so that burden is not on the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly with the payload, then alternatives, with zero filler sentences. However, the keyword digression (The Matrix / Terminator films example, ',' vs '|' semantics) belongs to discover_movies and inflates a single-id detail tool's description, making it a dense wall of text rather than a scannable definition.

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 read-only detail fetch with a declared output schema, nothing an agent needs is missing: id provenance, language/region defaults, optional extras, and the exact failure mode when OMDb is unavailable. Complexity is handled by naming the sibling for each reduced or expanded need.

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 coverage is 100%, so baseline is 3; the description still adds meaning the schema does not carry cleanly, notably that ratings.rated and certification are two distinct ratings that 'can differ', and that the OMDb ratings/awards block is an extra lookup skippable via include_ratings=false. The region fallback chain is also restated as behavior rather than just a field definition.

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+resource ('Get full details for one movie by TMDB id') and enumerates the payload: overview, genres, keywords, runtime, budget/revenue, vote average, certification, links. It explicitly distinguishes itself from get_movies ('trimmed and skips the rest of this payload') and positions get_movie_recommendations as the thematic alternative, so an agent can pick it without opening any 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 routing rules: use get_movies for headline info on one or several ids, get_movie_recommendations as the 'first stop' for a title like this, and discover_movies with 2-3 keyword ids when matching themes. It also states the prerequisite for the id ('Get the id from search_movies'), closing the chaining gap.

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