Overview
This topic describes Gracenote Video MCP tools, including behavior, limits, and data that your LLM will work with.
In general, you don't call these tools directly - your LLM does. However, you can call these tools using MCP Inspector for testing purposes and to better understand tool capabilities, limits, and data structures. This can help you optimize system prompts and design your application effectively. See Option 2 in the Quick Start (CLI/Proxy)
Available Tools
The Gracenote MCP Server provides the following tools that work behind the scenes to ground LLM responses with accurate Gracenote metadata. The LLM automatically selects and invokes these tools based on user queries - you don't call them directly. Available tools include:
resolve_entities- Find and disambiguate movies, TV shows, and episodesget_availability- Get streaming availability by countryget_root- Find alternate language versions via RootIDget_tmsid- Get comprehensive metadata for a TMSIDget_images- Retrieve all images for a TMSID
Entity Resolution Tool (resolve_entities)
Purpose
A structured metadata resolver for entertainment entities. Strictly requires specific identifiers (Title, Episode title, or Cast) to function. NOT a semantic search engine. Use this to validate existence and fetch IDs for specific known entities.
Disambiguation is Mandatory: When searching for a title, you MUST include country_code, language of description and at least one extra field (e.g., Year, Cast, or Episode Title when searching for an episode) to prevent incorrect matches.
Note: Disambiguation is enforced by the tool description sent to your LLM, not by input validation. Requests without extra fields will still execute, but may return incorrect matches (e.g., confusing a Hollywood movie with a foreign remake). Always include at least one disambiguating field for reliable results.
Input Limits
- Batch size: Maximum 5 entities per request
- Cast members: Maximum 3 names accepted per entity
- Required parameters: Title, entityType, language, countryCode
- Valid entityType values:
Movie,Show,Episode,Work - Optional parameters: Year, cast, duration, episode title, season/episode numbers
Note: Your LLM automatically extracts these parameters from user queries. Users ask in natural language (e.g., "Find the 1999 sci-fi movie with Keanu Reeves"), and the LLM determines the appropriate parameters (yearOfRelease=1999, cast=["Keanu Reeves"], entityType="Movie").
Output Limits
- Maximum candidates: 5 results returned, ranked by confidence
- Cast members: Top 3 actors only (role=Actor)
- Images: 1 preferred image per candidate
What Data Your LLM Receives
Each candidate returned by resolve_entities includes the following attributes. Your LLM automatically processes this data to generate natural language responses.
All Entity Types (Movie, Show, Episode):
| Attribute | Description |
|---|---|
| TMSID | Unique Gracenote identifier for the record |
| RootID | Root identifier linking all language versions of the same entity |
| Title | Title of the Movie or Show (not the episode title) |
| Type | Entity type: Movie, Show, or Episode |
| Actors | Top 3 leading cast members (role=Actor) |
| Genres | Thematic classifications (e.g., Drama, Comedy, Sci-Fi) |
| Description | Plot description (up to 250 characters) |
| Image URL | 1 preferred image URL and URI |
| Duration | Total runtime in minutes |
| ConfidenceScore | Match reliability score (0–1) |
Additional Attributes for Movies:
| Attribute | Description |
|---|---|
| Release Year | Calendar year of the film's release |
| Directors | Name(s) of the primary director(s) |
Additional Attributes for Shows:
| Attribute | Description |
|---|---|
| Directors | Name(s) of the primary director(s) |
Additional Attributes for Episodes:
| Attribute | Description |
|---|---|
| Episode Title | Title of the specific episode |
| Season Number | Sequential season the episode belongs to |
| Episode Number | Sequence number within the season |
| Original Network | Network where the episode first premiered |
| Release Date | Date the episode first premiered (day, month, year) |
| Director | Primary director for the episode |
Your LLM uses this data to generate responses like: "The Matrix (1999), directed by the Wachowskis, is a science fiction film starring Keanu Reeves, Laurence Fishburne, and Carrie-Anne Moss..."
Error Behavior
- Exceeds cast limit: Returns error "Maximum 3 cast members allowed"
- Missing required parameters: Returns error indicating which parameters needed
- No matches found: Returns empty results (not an error)
Genre Exclusions
The Entity Resolution tool filters out content tagged with the following genres:
- Adults Only
- Erotic
- Community
- Music
- Art
- Shopping
- Consumer
- Agriculture
Content in these genres will not appear in resolve_entities results. This filtering is applied server-side and cannot be overridden. Note that this exclusion applies only to Entity Resolution — content tagged with these genres remains accessible through other tools in the MCP Server (e.g., get_tmsid, get_root).
Streaming Availability Tool (get_availability)
Purpose
Returns current streaming availability for a specific title.
Input Limits
- TMSID: Single TMSID required
- Country: Single country code required
- Deeplink type: Optional (web, ios, android, stb, fire, android_tv)
Output Limits
- Time scope: "Today" only (current availability at time of query)
- No historical data: Past or future availability not included
- Geographic scope: Results limited to specified country only
What Data Your LLM Receives
For each streaming service:
- Service identification: Catalog ID and name (e.g., "Netflix US", "Hulu")
- Availability window: Start and end dates (far-future dates like 2255-01-01 indicate indefinite availability)
- Video quality: Available qualities (SD, HD, 4K)
- Deeplinks: Platform-specific URLs (filtered by type if specified)
Your LLM uses this data to generate responses like: "Friends is available on Netflix and Hulu in HD quality..."
Exclusions
- Entitled catalogs (e.g., Amazon Prime Video with special permissions)
- Linear TV channels
- FAST channels
- Sports streaming catalogs
Root Tool (get_root)
Purpose
Returns all TMSIDs associated with a RootID, enabling discovery of alternate language versions.
Input Limits
- Batch size: 1 RootID per request (passed as a single-element array)
- Language: Optional language filter
Output Limits
- No duplicate TMSIDs: Each TMSID appears once
- Language filtering: When specified, returns only matching language variants
What Data Your LLM Receives
For each TMSID:
- TMSID: Gracenote identifier
- Title language: Language code of the title
- Description language: Language code of the description
- Title subtype: Main, AKA, Promotional, IMAX, 3D
- Title text: Actual title string
Your LLM uses this data to find alternate versions like: "The Brazilian Portuguese version is available as TMSID..."
Language Filtering Behavior
- No language parameter: Returns all TMSIDs for the RootID
- Two-letter code (e.g., "en"): Returns all variants (en, en-US, en-GB, etc.)
- Locale-specific (e.g., "pt-BR"): Returns only exact matches
TMSID Metadata Tool (get_tmsid)
Purpose
Retrieves comprehensive metadata for a specific TMSID.
Input Limits
- Batch size: Maximum 1 TMSID per request
Output Limits
- Cast members: Top 3 actors and character names
- Images: 1 preferred image
- Description: 500 characters (plot type)
Unlike Entity Resolution which returns up to 5 candidates with confidence scores, get_tmsid returns the full metadata record for a single known TMSID.
Content Scope
Unlike Entity Resolution, this tool has no content restrictions. It returns metadata for any valid TMSID, including sports and non-TV/movie content.
Image Tool (get_images)
Purpose
Returns all available images for a specific TMSID.
Input Limits
- Batch size: Maximum 1 TMSID per request
Output Limits
- No image limit: Returns all available images for the title
Typical Image Counts
- Movies: ~20-30 images
- Series: ~15-20 images
- Episodes: ~5-10 images
What Data Your LLM Receives
For each image:
- Asset ID: Unique identifier
- Last modified: Timestamp of last update
- Type: MIME type (image/jpeg, image/png)
- Dimensions: Width and height in pixels
- Category: Image type (Iconic, VOD Art, Banner-L1, Key Art, Poster Art, Box Art, etc.)
- Aspect ratio: Ratio string (16:9, 2:3, 3:4, etc.)
- ImageInfo:
- URI: Relative path
- URL: Full URL with customer subdomain
Your LLM can provide image URLs in responses or select appropriate images based on aspect ratio needs.
MediaCloud Image URLs
Important Production Requirements:
- Do not use image URLs with ‘demo’ subdomain in production.
- Store images in your CDN or object storage and cache them for production use.
- Use URI for consistent references across environments.
URL Format: https://<YourSubdomain>.tmsimg.com/assets/<image_identifier>.<extension>
Customer Subdomain:
- Unique subdomain assigned during onboarding
- Allows usage monitoring and access control
- Required in all image URLs
Language & Country Parameters
Language Codes
Your LLM will use language codes to specify metadata language preferences.
Format: ISO 639-1 (two-letter) or IETF Language Tags (locale-specific)
Examples:
en- English (all variants)en-US- English (United States)pt-BR- Portuguese (Brazil)fr-CA- French (Canada)
Behavior:
- Two-letter codes match all variants (e.g., "en" matches en-US, en-GB, en-CA)
- Locale-specific tags match exactly (e.g., "pt-BR" matches only Brazilian Portuguese)
Country Codes
Your LLM will use country codes for geographic filtering.
Format: ISO 3166-1 alpha-3 (three-letter)
Examples:
USA- United StatesCAN- CanadaGBR- United KingdomDEU- GermanyJPN- JapanBRA- Brazil
Use Root Tool for Alternate Languages
Find alternate language versions via RootID. Same content has different TMSIDs per language/region.
When your LLM needs to find alternate language versions, it will automatically use the get_root tool with the RootID from a previous resolve_entities result. Ensure your system prompt instructs the LLM to check for localized versions when the user's language differs from the original content language.
Design for Multilingual Support
Support multiple languages in your application.
Implementation:
Code
Data Freshness & Updates
Title Metadata
- Update frequency: Metadata is continuously updated as new content is added and existing records are revised
- Coverage: Comprehensive metadata for movies, series, and episodes across supported countries
Availability Data
- Scope: Current availability only ("today")
- Update frequency: Updated throughout the day as streaming catalogs change
- Note: Availability data reflects real-time catalog state at time of query
Image Data
- Update frequency: Images are updated as new assets become available from content providers
- Expiration: Images may expire and be replaced
- Recommendation: Cache locally and refresh periodically
Performance Characteristics
Response Times
- Target average: Less than 50ms per tool call
- Actual performance: Varies by query complexity and data volume
Factors affecting performance:
- Query complexity
- Number of candidates to evaluate
- Network latency
- Data volume returned