MCP · Tool Reference

SEVENTEEN TOOLS

Every parameter for every tool on the connector. For setup and authentication, start with the connector guide.

Protocol

CALLING A TOOL

Every tool is invoked with a single JSON-RPC tools/call POST. The result arrives as a text content block whose body is the JSON payload documented below. One call is one API request against your daily limit — except get_account_status, which is free.

POST https://hollywoodmetrics.ai/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_films",
    "arguments": { "query": "the godfather", "limit": 2 }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ ...JSON... }" }],
    "isError": false
  }
}

// The text block parses to:
{
  "data": [
    {
      "imdb_id": "tt0068646",
      "title": "The Godfather",
      "year": 1972,
      "genres": ["Crime", "Drama"],
      "director": "Francis Ford Coppola",
      "ratings": { "imdb": 9.2, "imdb_votes": 2205375, "master_score": 96 }
    }
  ],
  "meta": { "count": 2, "next_cursor": "..." }
}

Business denials (quota, tier, scope) come back with isError: true and a coded payload — never an HTTP error — so a host never reads the connector as broken. See the error reference.

Catalog

FILM CATALOG

Search, read, and relate the 74,000+ film catalog (1915 to today). All read scope.

search_filmsSearch films

Free-text query matches title, director, cast, crew, keywords, and synopsis. Combine with structured filters and sort. Returns lean records; use get_film for full detail.

Parameter	Type	Description
`query`opt	string	Free-text search.
`genre`opt	string	Comma-separated, all must match, e.g. 'Drama,Crime'.
`decade`opt	string	e.g. '1990s'.
`year_min`opt	integer	Earliest release year.
`year_max`opt	integer	Latest release year.
`min_rating`opt	number	Minimum IMDb rating (0–10).
`min_score`opt	number	Minimum Hollywood Metrics master score (0–100).
`director`opt	string	Filter by director name.
`actor`opt	string	Filter by cast member.
`language`opt	string	ISO 639-1 code, e.g. 'fr'.
`sort`opt	string	field:asc\|desc — title, year, imdb_rating, rt_score, tmdb_rating, master_score, budget, worldwide_gross, roi, oscar_noms, oscar_wins, runtime.
`limit`opt	integer	1–100. Default 20.
`cursor`opt	string	Opaque pagination cursor from meta.next_cursor.

Example arguments

{ "query": "heist", "genre": "Crime,Thriller", "min_rating": 7, "sort": "worldwide_gross:desc", "limit": 5 }

get_filmGet film detail

Full canonical record for one film: ratings, box office with ROI, awards, cast (top 15), crew by department, keywords, poster, and production companies.

Parameter	Type	Description
`id`req	string	IMDb id, e.g. tt0111161.

Example arguments

{ "id": "tt0111161" }

get_similar_filmsGet similar films

Films similar to a given IMDb id, drawn from curated similarity data.

Parameter	Type	Description
`id`req	string	IMDb id, e.g. tt0111161.
`limit`opt	integer	1–50. Default 10.

Example arguments

{ "id": "tt0068646", "limit": 8 }

get_poster_analysisGet poster analysis

Structured visual read of a theatrical poster: design quality, mood, composition, color, typography, genre signals, and standout elements. Available for ~38,000 films.

Parameter	Type	Description
`id`req	string	IMDb id, e.g. tt0111161.

Example arguments

{ "id": "tt0111161" }

recommend_filmsRecommend films

Content-based recommendations from liked (and optionally disliked) films. Accepts IMDb ids or titles. Returns scored picks with reasons plus the inferred taste profile.

Parameter	Type	Description
`liked`req	string[]	One or more IMDb ids or titles the audience likes.
`disliked`opt	string[]	Titles or ids to steer away from.
`limit`opt	integer	1–50. Default 10.

Example arguments

{ "liked": ["Blade Runner", "Arrival"], "disliked": ["tt0468569"], "limit": 6 }

get_catalog_statsGet catalog statistics

Aggregate statistics computed across the whole catalog: total films, genre and decade distributions, IMDb-rating and master-score distributions, budget tiers, ROI by decade, top directors, top languages, and the top Oscar-winning films.

No parameters.

Example arguments

{}

Screenplay

SCREENPLAY INTELLIGENCE

The 1,571-screenplay research set and the 20-feature tier-prediction model. Read scope; screenplay text is processed in-flight and never stored.

search_scriptsBrowse ranked screenplays

Browse the research set, ranked into tiers S (exceptional) through E. Each record carries the 20 measured screenplay features.

Parameter	Type	Description
`tier`opt	enum	One of S, A, B, C, D, E.
`limit`opt	integer	1–100. Default 20.
`offset`opt	integer	Zero-based pagination offset.

Example arguments

{ "tier": "S", "limit": 10 }

get_scriptGet screenplay record

One ranked screenplay by IMDb id: tier, rank, points, and its full 20-feature measurement vector.

Parameter	Type	Description
`id`req	string	IMDb id, e.g. tt0111161.

Example arguments

{ "id": "tt0111161" }

analyze_screenplayAnalyze screenplay text

Run raw screenplay text through the tier-prediction model. Extracts 20 structural features, predicts a quality tier with class probabilities, and compares each feature to dataset norms (z-scores, percentiles). Deterministic — no LLM.

Parameter	Type	Description
`text`req	string	Screenplay text, minimum 500 characters.

Example arguments

{ "text": "INT. DINER - NIGHT\n\nJULES and VINCENT sit in a booth..." }

predict_project_outcomePredict project outcome

Forecast a film project from its package: estimated worldwide gross, IMDb rating, master score, and ROI, with comparable films, an audience read, and marketing angles. Deterministic comparables model.

Parameter	Type	Description
`title`req	string	Working title.
`genres`opt	string[]	e.g. ['Sci-Fi', 'Thriller'].
`budget`opt	number	Production budget in USD.
`director`opt	string	Attached director.
`cast`opt	string[]	Lead cast names.
`synopsis`opt	string	Short logline or synopsis.

Example arguments

{ "title": "Orbital", "genres": ["Sci-Fi", "Thriller"], "budget": 90000000, "director": "Denis Villeneuve", "cast": ["Rebecca Ferguson"] }

Craft

CRAFT

Style guides for screenwriters (~166), directors (~100), and cinematographers (~160). Read scope.

list_style_guidesList craft style guides

List the style guides available for one discipline. Returns names and slugs; use get_style_guide for the full guide.

Parameter	Type	Description
`discipline`req	enum	One of writers, directors, cinematographers.

Example arguments

{ "discipline": "directors" }

get_style_guideGet craft style guide

Full style guide for one screenwriter, director, or cinematographer: overview, keywords, signature techniques, and reference films.

Parameter	Type	Description
`discipline`req	enum	One of writers, directors, cinematographers.
`name`req	string	Name or slug, e.g. 'Aaron Sorkin' or 'aaron-sorkin'.

Example arguments

{ "discipline": "writers", "name": "aaron-sorkin" }

AI · Studio tier

AI SERVICES

LLM-backed craft tools. Require a Studio-tier key (the ai scope); a sandbox or lower-tier caller gets a SCOPE_NOT_LICENSED tool result. Text is processed in-flight and never stored.

ai_script_coverageAI script coverageRequires Studio tier (ai scope).

Professional-grade coverage of screenplay text — structure, dialogue, pacing, and craft notes — grounded in the platform's 20-feature measurement of the same text.

Parameter	Type	Description
`text`req	string	Screenplay text, minimum 500 characters.
`focus`opt	enum	One of structure, dialogue, all. Default all.

Example arguments

{ "text": "INT. WAREHOUSE - NIGHT\n\n...", "focus": "structure" }

ai_rewrite_sceneAI scene rewriteRequires Studio tier (ai scope).

Rewrite scene or screenplay text in the voice of a named screenwriter, guided by that writer's style guide.

Parameter	Type	Description
`text`req	string	Scene text, minimum 100 characters.
`style`req	string	Writer style slug, e.g. 'aaron-sorkin' — see list_style_guides.

Example arguments

{ "text": "She walks in. He looks up. Neither speaks.", "style": "aaron-sorkin" }

Utility

UTILITY & CONNECTOR CONTRACT

Account introspection plus the standard search / fetch contract that ChatGPT and other research connectors expect.

get_account_statusGet account statusFree and unmetered.

Your connection status: mode (sandbox, signed_in via OAuth, or api_key), tier, scopes, daily request limit, approximate usage today, and reset time. Unmetered — never counts against your quota.

No parameters.

Example arguments

{}

searchSearch (connector contract)

Search films and ranked screenplays by title, people, keywords, or synopsis. Returns result ids (with citation URLs) for use with fetch. This is the standard research-connector search tool.

Parameter	Type	Description
`query`req	string	Search query.

Example arguments

{ "query": "kubrick" }

fetchFetch (connector contract)

Fetch the full document for a search result id, formatted as citable text with a canonical URL. The standard research-connector fetch tool.

Parameter	Type	Description
`id`req	string	Result id from search, e.g. 'film:tt0111161' or 'script:tt0111161'.

Example arguments

{ "id": "film:tt0111161" }

Output shape

SCREENPLAY ANALYSIS

analyze_screenplay returns a predicted tier with class probabilities, the full 20-feature vector, and a per-feature comparison against the 1,571-script research set.

{
  "data": {
    "predicted_class": "Mid",
    "predicted_tier": "B/C",
    "probabilities": { "High": 0.157, "Mid": 0.451, "Low": 0.391 },
    "features": {
      "scene_count": 42, "dialogue_ratio": 0.31, "sentiment_arc_slope": -0.02,
      "vocabulary_richness": 0.19, "action_ratio": 0.68
      /* ...20 features total... */
    },
    "comparisons": {
      "scene_count": { "value": 42, "dataset_mean": 43.1, "z_score": -0.01, "percentile": 49 }
      /* ...per-feature vs the 1,571-script dataset... */
    }
  }
}

Denials

ERROR REFERENCE

Post-authentication problems are returned as tool results with isError: true and a code, so agents can branch on them without treating the connection as down.

Code	Meaning
`QUOTA_EXCEEDED`	Daily request limit reached for your tier. Retry after the reset in get_account_status, or upgrade.
`TIER_NOT_LICENSED`	Your tier cannot use this tool (e.g. an AI tool on a read-only tier).
`SCOPE_NOT_LICENSED`	Your key lacks the required scope (the AI tools need the ai scope, carried by Studio keys).
`NOT_FOUND`	No record matches the id or name you passed.
`INVALID_INPUT`	Arguments failed validation (e.g. screenplay text under the minimum length).
`UPSTREAM_ERROR`	A downstream service failed transiently. Safe to retry.

Connector guideREST API referencePricing

POST https://hollywoodmetrics.ai/mcp Content-Type: application/json Accept: application/json, text/event-stream { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_films", "arguments": { "query": "the godfather", "limit": 2 } } }

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "{ ...JSON... }" }], "isError": false } } // The text block parses to: { "data": [ { "imdb_id": "tt0068646", "title": "The Godfather", "year": 1972, "genres": ["Crime", "Drama"], "director": "Francis Ford Coppola", "ratings": { "imdb": 9.2, "imdb_votes": 2205375, "master_score": 96 } } ], "meta": { "count": 2, "next_cursor": "..." } }

Parameter

Type

Description

queryopt

string

Free-text search.

genreopt

string

Comma-separated, all must match, e.g. 'Drama,Crime'.

decadeopt

string

e.g. '1990s'.

year_minopt

integer

Earliest release year.

year_maxopt

integer

Latest release year.

min_ratingopt

number

Minimum IMDb rating (0–10).

min_scoreopt

number

Minimum Hollywood Metrics master score (0–100).

directoropt

string

Filter by director name.

actoropt

string

Filter by cast member.

languageopt

string

ISO 639-1 code, e.g. 'fr'.

sortopt

string

field:asc|desc — title, year, imdb_rating, rt_score, tmdb_rating, master_score, budget, worldwide_gross, roi, oscar_noms, oscar_wins, runtime.

limitopt

integer

1–100. Default 20.

cursoropt

string

Opaque pagination cursor from meta.next_cursor.

Parameter

Type

Description

idreq

string

IMDb id, e.g. tt0111161.

Parameter

Type

Description

idreq

string

IMDb id, e.g. tt0111161.

limitopt

integer

1–50. Default 10.

Parameter

Type

Description

idreq

string

IMDb id, e.g. tt0111161.

Parameter

Type

Description

likedreq

string[]

One or more IMDb ids or titles the audience likes.

dislikedopt

string[]

Titles or ids to steer away from.

limitopt

integer

1–50. Default 10.

Parameter

Type

Description

tieropt

enum

One of S, A, B, C, D, E.

limitopt

integer

1–100. Default 20.

offsetopt

integer

Zero-based pagination offset.

Parameter

Type

Description

idreq

string

IMDb id, e.g. tt0111161.

Parameter

Type

Description

textreq

string

Screenplay text, minimum 500 characters.

Parameter

Type

Description

titlereq

string

Working title.

genresopt

string[]

e.g. ['Sci-Fi', 'Thriller'].

budgetopt

number

Production budget in USD.

directoropt

string

Attached director.

castopt

string[]

Lead cast names.

synopsisopt

string

Short logline or synopsis.

Parameter

Type

Description

disciplinereq

enum

One of writers, directors, cinematographers.

Parameter

Type

Description

disciplinereq

enum

One of writers, directors, cinematographers.

namereq

string

Name or slug, e.g. 'Aaron Sorkin' or 'aaron-sorkin'.

Parameter

Type

Description

textreq

string

Screenplay text, minimum 500 characters.

focusopt

enum

One of structure, dialogue, all. Default all.

Parameter

Type

Description

textreq

string

Scene text, minimum 100 characters.

stylereq

string

Writer style slug, e.g. 'aaron-sorkin' — see list_style_guides.

Parameter

Type

Description

queryreq

string

Search query.

Parameter

Type

Description

idreq

string

Result id from search, e.g. 'film:tt0111161' or 'script:tt0111161'.

{ "data": { "predicted_class": "Mid", "predicted_tier": "B/C", "probabilities": { "High": 0.157, "Mid": 0.451, "Low": 0.391 }, "features": { "scene_count": 42, "dialogue_ratio": 0.31, "sentiment_arc_slope": -0.02, "vocabulary_richness": 0.19, "action_ratio": 0.68 /* ...20 features total... */ }, "comparisons": { "scene_count": { "value": 42, "dataset_mean": 43.1, "z_score": -0.01, "percentile": 49 } /* ...per-feature vs the 1,571-script dataset... */ } } }

Code

Meaning

QUOTA_EXCEEDED

Daily request limit reached for your tier. Retry after the reset in get_account_status, or upgrade.

TIER_NOT_LICENSED

Your tier cannot use this tool (e.g. an AI tool on a read-only tier).

SCOPE_NOT_LICENSED

Your key lacks the required scope (the AI tools need the ai scope, carried by Studio keys).

NOT_FOUND

No record matches the id or name you passed.

INVALID_INPUT

Arguments failed validation (e.g. screenplay text under the minimum length).

UPSTREAM_ERROR

A downstream service failed transiently. Safe to retry.