Allows interacting with your personal IMDb account, providing tools to search titles, manage ratings, and add or remove titles from your Watchlist.
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., "@imdb-personal-mcp Rate the movie Inception 8 out of 10"
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.
A small Python MCP server for your own IMDb account: search titles, manage ratings, and add or remove titles from your Watchlist.
Works with clients that support local stdio MCP servers. No OpenClaw installation, Node.js runtime, IMDb developer API key, or paid search provider is required.
Experimental and unofficial. This uses IMDb's internal web API, which can change without notice. Browser impersonation does not guarantee access. Use it only with an account you control and respect IMDb's terms and rate limits. Not affiliated with IMDb or Amazon.
MCP client → Python → curl_cffi → IMDb
│
session challenge
↓
import IMDb cookies from
your existing local browser
↓
retry HTTP onceAll account operations run over HTTP using curl_cffi and coherent Chrome-style default headers.
Brave/Chromium supplies cookies only, through its local Chrome DevTools Protocol (CDP) endpoint. The server does not launch a browser, navigate tabs, run page JavaScript, or execute the original operation in a browser.
A challenge triggers at most one cookie import and one HTTP retry. A persistent challenge is returned as an error, not disguised as success.
Watchlist writes are verified by reading the list again. Cookie values are not logged or returned by MCP tools.
Copying an expired cookie does not renew a session. If IMDb needs to refresh its browser/WAF session, open or reload IMDb in your browser, then import cookies again. Safari does not expose the Chromium CDP interface used here.
Related MCP server: @showtime/mcp
Requires Python 3.10+ and uv.
git clone https://github.com/TimurKutsenko/imdb-personal-mcp.git
cd imdb-personal-mcp
uv sync --lockedAlternatively, install from a local checkout with python -m pip install .. This project is published on GitHub, not currently on PyPI.
Start a Chromium-based browser with a CDP port bound to loopback, sign in to IMDb manually, and leave the browser running. For example, on Linux:
brave-browser \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.local/share/imdb-browser"On macOS:
open -na "Brave Browser" --args \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/Library/Application Support/imdb-browser"These examples create a separate browser profile: sign in there once. You may instead use an existing profile already exposing CDP. Adding a flag to an already-running browser does not necessarily enable debugging. Do not expose the CDP port to your network: it grants control over that browser profile.
Import the session:
uv run imdb-auth --cdp-url http://127.0.0.1:9222The helper requests only IMDb cookies from an existing page target; it does not read the browser's on-disk database. It requires authenticated session cookies, not merely an anonymous IMDb session ID.
Open your IMDb profile. Copy the identifier between /user/ and the next /, such as ur12345678 or the newer p.… form. Use your own ID, not the example below.
Add this to your MCP client's configuration, replacing the two example paths and account ID:
{
"mcpServers": {
"imdb-personal": {
"command": "/absolute/path/to/uv",
"args": [
"run", "--locked", "--directory",
"/absolute/path/to/imdb-personal-mcp",
"imdb-personal-mcp"
],
"env": {
"IMDB_USER_ID": "ur12345678"
}
}
}
}Find the executable with command -v uv on macOS/Linux or where uv on Windows. Restart or reload your MCP client after configuration changes.
Ask your assistant to check auth_status, then read list_my_watchlist. Title search works without signing in or configuring a profile. List operations require your profile ID; Watchlist writes also need it for verification. An authentication check alone does not prove HTML list access works.
Tool | Purpose |
| Find exact IMDb title IDs; no login required |
| Check the saved session with a live account request |
| Read your rating for a title |
| Read your ratings from live account data |
| Set a rating from 1 to 10 and verify it |
| Delete a rating; call |
| Read your current Watchlist |
| Add a title and verify membership |
| Remove a title and verify absence |
Writes change the real account. Ask your assistant to resolve the exact title first and confirm that a change is intended. Large lists are limited by max_pages; reaching the limit is reported rather than silently returning an incomplete list.
Variable | Default / meaning |
| No default; your profile identifier |
| Optional explicit |
| Optional explicit |
| OS-specific user data directory, outside the repository |
|
|
| Saved endpoint, otherwise |
|
|
| Unset: use headers matching the impersonation profile; override only for diagnosis |
|
|
Typical state paths are ~/Library/Application Support/imdb-personal-mcp on macOS and ~/.local/share/imdb-personal-mcp on Linux. Windows uses the per-user application data directory supplied by platformdirs. Cookies are written atomically with private file permissions on POSIX. Protect the containing directory with your user account's access controls on Windows.
Use the same IMDB_DATA_DIR / IMDB_COOKIE_FILE in both imdb-auth and the MCP client when overriding defaults. .env files are not loaded automatically. No account ID or cookies ship with the package.
CONFIG_REQUIRED: configure your own profile ID or explicit list URL. Nothing defaults to the author's account.
AUTH_REQUIRED: sign in to IMDb in the selected browser and rerun imdb-auth.
Cookie import unavailable: check that the browser is running, CDP is on the chosen loopback port, and IMDb is signed in. The server never switches to another browser automatically.
ANTI_BOT after import: update the IMDb session in the browser, then import again. The same expired WAF token cannot be refreshed simply by copying it.
RATE_LIMITED: stop and retry later. Do not increase concurrency or retry in a tight loop.
BAD_RESPONSE / page data missing: IMDb may have changed its HTML or GraphQL schema. Share a sanitized description in an issue, not raw authenticated responses or HAR files.
PAGE_LIMIT: increase max_pages for a larger list; the server will not claim a truncated list is complete.
A write timed out or verification failed: read the current account state before retrying. A failed response does not necessarily mean no change occurred.
uv sync --locked
uv run pytest -q
uv run ruff check .
uv buildTests use synthetic cookies and mocked HTTP/CDP responses: they do not sign in, contact IMDb, or change a real account. CI tests supported Python versions on Linux and a macOS runner, and builds the distributable package. Windows is not currently covered by CI.
Contributions are welcome: see CONTRIBUTING.md. Useful areas include schema resilience, pagination, clearer recovery diagnostics, and cross-platform testing. For private vulnerability reports, see SECURITY.md.
Built on curl_cffi, the MCP Python SDK, websockets, and platformdirs.
Existing IMDb community projects helped identify web-protocol conventions: Letterboxd-to-IMDb, kinopoisk-to-imdb, and MovieRatingSync. This repository contains the Python implementation, not copies of their distributions.
MIT.
Add a title to the authenticated user's IMDb Watchlist and verify it.
| Name | Required | Description | Default |
|---|---|---|---|
| title_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the non-read-only, idempotent, non-destructive profile. The description adds 'verify it', hinting at a confirmation behavior, but does not explain what happens on duplicate adds, auth failures, or the exact verification semantics.
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 sentence that leads with the action and states the target list and a verification step. No filler or repetition.
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 one-parameter tool with annotations covering safety/idempotency, the description is nearly sufficient. It could mention how to obtain title_id (e.g., via search_titles) or clarify what 'verify' means, but these are minor omissions.
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% and the description does not describe title_id's format, source, or meaning. The property name and title are self-explanatory, so this is not as severe as a fully opaque parameter, but the description adds no parameter-level value.
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 uses a specific verb ('Add'), a clear resource ('a title to the authenticated user's IMDb Watchlist'), and a verification step. This clearly distinguishes it from siblings like remove_from_watchlist and list_my_watchlist.
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 intended use is implied by the action itself, but there is no explicit when-to-use guidance or comparison with alternatives. An agent must infer that this is the counterpart to remove_from_watchlist and distinct from list_my_watchlist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the authenticated IMDb session with a live account read.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds 'live account read', signaling that this is a real network check rather than a cached or local validation. This is useful context beyond the structured annotations.
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?
The description is a single sentence that front-loads the action and target. It uses no redundant words and conveys the essential purpose plus the live-read behavior in a compact form.
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 zero-parameter status check, the description is minimal but adequate. However, it does not specify what the tool returns (status details, user info, session expiry) or when it should be used relative to other tools. Without an output schema, these gaps make the description slightly incomplete.
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?
The tool has zero parameters and an empty input schema, so there are no parameter semantics to document. A baseline of 4 is appropriate for a parameterless tool.
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 names a specific verb ('Check') and resource ('authenticated IMDb session'), so the purpose is clear. It doesn't explicitly contrast with sibling tools, but the focus on session/auth status is distinct from title search, ratings, and watchlist tools, so selection ambiguity is low.
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?
No guidance is given about when to call this tool versus alternatives. It does not mention that it could serve as a precondition for other account-related tools, nor does it say when not to use it. The phrase 'live account read' hints at behavior but provides no usage policy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the authenticated user's IMDb rating.
| Name | Required | Description | Default |
|---|---|---|---|
| title_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' is consistent with those. The word 'authenticated user's' adds the ownership/scoping context, but the description stops short of explaining response behavior or the no-op case.
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. Every word contributes to identifying the action and target.
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 one-parameter mutation with strong annotations covering destructiveness and idempotence, the description plus schema is sufficient to invoke the tool. The main missing piece is return/response behavior, which is partly covered by the absence of an output schema and the idempotence hint.
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 0%, the description carries the full burden for explaining title_id, but it only indirectly implies that the parameter identifies the title whose rating is deleted. It does not describe the required format or how to obtain a valid title_id.
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 phrase 'Delete the authenticated user's IMDb rating' uses a specific action verb and names the exact resource, making the tool's purpose unmistakable. It also differentiates itself from sibling tools such as set_my_rating, get_my_rating, and list_my_ratings.
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 description makes clear the target is restricted to the authenticated user's own rating, which implies the tool is for removing one of the current user's ratings. It does not explicitly state when to prefer this over set_my_rating or provide alternatives/exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the authenticated user's live IMDb rating for one title.
| Name | Required | Description | Default |
|---|---|---|---|
| title_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by metadata. The description adds the 'live' freshness trait and authenticated-user scoping, which are useful beyond the annotations. No contradictions, but no deeper behavior (e.g., behavior when no rating exists) is disclosed.
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 sentence with no filler; the key facts (read, authenticated user, live, one title) are front-loaded and directly useful. It earns its length.
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?
Given the one-parameter surface and rich read-only annotations, the description is nearly sufficient for a simple read-by-ID tool. The gaps are the undocumented title_id format and the absence of explicit handling for 'no rating exists', but these are minor against the tool's simplicity.
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 0%: the schema only gives type and required flag for title_id, and the description does not explain what format/source the ID should have or how to obtain it (e.g., via search_titles). The parameter name gives a moderate clue, but the description does not compensate for the missing schema documentation. This could lead an agent to pass a title name rather than an IMDb title ID.
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?
Uses a specific verb ('Read') and identifies the exact resource: the authenticated user's own rating, scoped to a single title. This distinguishes it from list_my_ratings (plural) and the set/delete mutators, even without naming them. No ambiguity in what the tool does.
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?
Describes clear usage context: reading only the authenticated user's rating, not public ratings or aggregate data. It does not explicitly name alternatives such as list_my_ratings for fetching all of the user's ratings, so the when/not guidance is left partly to inference from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the authenticated user's current IMDb ratings.
| Name | Required | Description | Default |
|---|---|---|---|
| max_pages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the 'authenticated user's current' scope but provides no additional behavioral details such as pagination behavior, rate limits, or side effects. This is a mild addition beyond the annotations, not a contradiction.
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?
The description is a single, front-loaded sentence that states the operation and resource without any filler. Every word contributes to understanding the tool's purpose.
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?
Given the tool's simplicity, the read-only annotations, the presence of an output schema, and only one optional parameter, the short description is largely sufficient for correct selection and invocation. The main minor gaps are the unelaborated max_pages parameter and lack of explicit sibling routing. Overall it is nearly complete for its complexity.
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?
The input schema has one optional parameter, max_pages, but schema description coverage is 0% and the tool description does not explain pagination semantics or what 'pages' means in this context. The parameter name and default of 10 provide some self-evident meaning, but the description does not compensate for the missing schema documentation. This leaves a noticeable gap for an agent deciding how to set the parameter.
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 uses the specific verb 'Read' and identifies the exact resource: the authenticated user's current IMDb ratings. It clearly distinguishes from sibling mutation tools like set_my_rating and delete_my_rating, and the plural 'ratings' separates it from the singular get_my_rating. The purpose is immediately recognizable.
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 description implies that this tool is for retrieving the authenticated user's ratings, but it does not explicitly state when to prefer it over get_my_rating or how it relates to search_titles or list_my_watchlist. No when/when-not guidance or alternatives are provided, leaving the agent to infer usage from sibling names. This is implied usage rather than explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the authenticated user's current IMDb Watchlist.
| Name | Required | Description | Default |
|---|---|---|---|
| max_pages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the annotations by specifying that the data is scoped to the authenticated user and is the 'current' watchlist, which complements the readOnlyHint and openWorldHint. It doesn't describe pagination behavior, but the annotations and output schema already cover the safety profile.
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. Every word adds meaning, and the most important information (read, watchlist, scope) comes first.
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?
The definition is adequate for a safe read-only operation with an output schema and annotations, but it leaves the single input parameter undocumented and does not explicitly mention authentication prerequisites or pagination semantics. For this low-complexity tool, these gaps keep it at minimum viable rather than complete.
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%, and the description does not explain the only parameter, max_pages. An agent can infer that it limits pagination from the name, but there is no explicit statement of page size or behavior, so the description fails to compensate for the schema gap.
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 uses a specific verb ('Read') and a precise resource ('authenticated user's current IMDb Watchlist'), making the tool's function unmistakable. It also separates this tool from sibling read tools like list_my_ratings by naming the watchlist rather than ratings.
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 description implies the usage context: call this when you need the authenticated user's current watchlist. However, it gives no explicit when-not-to-use guidance or pointers to alternatives such as add_to_watchlist, remove_from_watchlist, or list_my_ratings, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a title from the authenticated user's IMDb Watchlist and verify it.
| Name | Required | Description | Default |
|---|---|---|---|
| title_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide key behavioral hints (destructive, idempotent, read-only is false). The description adds value by clarifying the operation is scoped to the authenticated user and explicitly notes that removal is verified, which is not present in the annotations.
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?
The description is a single tightly written sentence with no filler. The core action is front-loaded, and 'and verify it' adds meaningful post-condition information without unnecessary verbosity.
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-parameter destructive mutation, the description and annotations cover the essential operation. However, it leaves title_id semantics undocumented, does not explain what verification entails, and provides no output or error context despite there being no output schema.
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 compensate, but it never explains title_id, its format, how to obtain it, or its relationship to the 'title' being removed. The only hint is the parameter name itself, which is not enough.
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 uses a specific verb ('Remove') with a clear resource ('a title from the authenticated user's IMDb Watchlist') and adds a verification post-condition. This clearly distinguishes it from sibling tools like add_to_watchlist and list_my_watchlist.
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 description does not state when to use this tool versus alternatives such as add_to_watchlist or list_my_watchlist, and it provides no prerequisites or exclusions. The intended use is implied by the name, but there is no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search IMDb titles. Use this first for a title without a tt ID.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the description does not need to restate it. The description adds no behavioral detail beyond that, such as matching behavior or result characteristics, but it does not contradict the annotations either.
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 primary action is front-loaded and the usage condition is stated immediately, making the definition easy to parse and act on.
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 search tool with a robust annotation set and an output schema, the description is nearly complete. It covers what the tool does and when to use it; minor omissions like exact-match behavior or response ordering are not critical given the output schema exists.
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?
The schema has no descriptions for query or limit, and the description only partially compensates by implying the query is a title string rather than a tt ID. The parameter names and default are largely self-explanatory, but no extra semantic detail is provided about matching rules, limit bounds, or query formatting.
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 uses a specific verb and resource ('Search IMDb titles') and adds a clear scoping condition ('Use this first for a title without a tt ID'). This unambiguously distinguishes the tool from the sibling rating/watchlist/auth tools, none of which perform title search.
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 description gives explicit situational guidance: use this tool first when there is no tt ID already available. It does not name an alternative tool for the tt ID case, but the guidance is clear enough for an agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or replace the authenticated user's IMDb rating.
| Name | Required | Description | Default |
|---|---|---|---|
| rating | Yes | ||
| title_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal extra behavioral context beyond scope ('authenticated user's') and the replace semantics, but does not disclose additional side effects, valid rating ranges, or authentication requirements.
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?
The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the action and the resource.
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 two-parameter tool with annotations covering idempotence and non-destructiveness, the description is nearly complete: it states the action, the scope, and the resource. It lacks explicit parameter details, but those are minimal enough that an agent can likely infer them from the schema.
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%, and the description does not explain either parameter. The names rating and title_id are somewhat self-evident, and 'IMDb rating' gives context, but the agent receives no guidance on allowed rating values, title_id format, or constraints beyond the schema's types.
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 uses a specific verb ('Set or replace') and a clear resource ('the authenticated user's IMDb rating'). It also includes the scope 'authenticated user's', which distinguishes it from sibling tools like get_my_rating and delete_my_rating without ambiguity.
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 description clearly implies when to use the tool: when the user wants to create or update their rating for a title. However, it does not explicitly mention alternatives or exclusions, such as when to use delete_my_rating instead, leaving some guidance implied rather than stated.
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.4.0add_to_watchlistauth_statusdelete_my_ratingget_my_ratinglist_my_ratingslist_my_watchlistremove_from_watchlistsearch_titlesset_my_ratingScored across 9 tools
Each tool targets a distinct resource-action pair: search for discovery, ratings (get/list/set/delete), watchlist (list/add/remove), and authentication status. There is no overlap in purpose, and singular vs. plural rating operations are clearly differentiated.
Tool names follow a consistent snake_case verb_noun pattern (search_titles, set_my_rating, remove_from_watchlist). Prepositional forms for add/remove are stylistically consistent with the rest, and the verb clearly indicates the operation.
Nine tools is well-scoped for a personal IMDb account manager: search, rating CRUD, watchlist CRUD (minus update), and auth status. Each tool serves a necessary function without redundancy or bloat.
The domain of personal IMDb management is fully covered: ratings have get/list/set/delete, watchlist has list/add/remove, and search enables finding titles. There are no dead ends or missing operations for core workflows.
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
Trakt MCP — TV/movie metadata + watch tracking signals
IMDB MCP — title metadata, ratings, episodes, and crew from IMDB's
Movie Planner MCP: watchlists, showtimes, tracked cinema ticket links.