Provides analytics over IMDb's non-commercial datasets, enabling ranking of actors by credits, filtering by life and career details, comparing filmographies, and finding titles shared between actors.
Click on "Install 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-analytics-mcp Who are the 25 people with the most acting credits?"
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.
Local, personal MCP server that lets an LLM rank, compare and connect actors and titles from IMDb's non-commercial datasets, stored in DuckDB, with Wikidata enrichment.
Status (2026-09-09): M1 ingest, M2 analytics and M3 MCP tools are built. Wikidata enrichment (nationality, gender, awards) is M4 and those filters return an error until then.
Read in this order:
docs/brief.md — the original plan and definition of done.
docs/research.md — prior art survey and answers to the Phase 15 questions.
docs/storage-decision.md — DuckDB, measured against SQLite on the full data.
docs/data-model.md — tables, the configurable credit definition, unsupportable filters.
docs/architecture.md — layers, data flow, tool surface, milestones.
docs/scoring.md — recognition score: first measurement and planned experiments.
Detailed source research and benchmark reports live in docs/research/. Prototype scripts
are in scripts/ (proto_* = raw-table load and DuckDB vs SQLite bench; proto2_* = the
proposed schema bench). Data lives outside the repo under data/ (a symlink; gitignored).
Setup: uv sync, then uv run imdb-mcp update to download the datasets and build
data/imdb.duckdb (about 4.4 GB). uv run imdb-mcp status says how fresh it is,
uv run imdb-mcp doctor checks the environment.
The software is MIT licensed. The IMDb datasets it downloads are not: IMDb permits them
for personal, non-commercial use only, and forbids republishing them as a database of movie
information. This project therefore runs locally, each user fetches the data themselves with
imdb-mcp update, and nothing derived from IMDb data is redistributed. Do not host it as a
shared service. Wikidata enrichment data is CC0.
Related MCP server: IMDB MCP
The server speaks MCP over stdio. Build the database first (uv run imdb-mcp update), then
point a client at imdb-mcp serve.
Claude Desktop — add this to claude_desktop_config.json and restart the app:
{
"mcpServers": {
"imdb-analytics": {
"command": "uv",
"args": ["--directory", "/home/you/dev/imdb-analytics-mcp", "run", "imdb-mcp", "serve"],
"env": { "IMDB_MCP_DATA_DIR": "/home/you/dev/imdb-analytics-mcp/data" }
}
}
}Claude Code — one line:
claude mcp add imdb-analytics -- uv --directory /home/you/dev/imdb-analytics-mcp run imdb-mcp serveimdb-mcp serve --transport http --port 8765 serves the same tools over HTTP, for MCP
Inspector or any other debugging client. The server holds the database open, so after an
imdb-mcp update the client has to reconnect before it sees the new data.
This is the brief's definition-of-done chain, run against the real build on 2026-09-09. The
full output of every step, including each response's method and caveats, is in
docs/summaries/m3-dod-chain-2026-09-09.md.
Who are the 25 people with the most acting credits?
Brahmanandam (1,131), Eric Roberts (725), Jagathy Sreekumar (653), Eddie Garcia (650), Adoor Bhasi (617)… — counting movies, TV movies, TV series, TV specials and direct-to-video titles, with a series counted once regardless of episode count, and self appearances, archive footage and adult titles excluded. 2,380,714 people have at least one credit.
Only the ones still alive.
15 of the 25. IMDb records a death year only when a death is known, so this really means "not known to have died".
Born before 1960, and sort them by how long their careers have run.
10 people. Aruna Irani leads at 68 years, then Jagathy Sreekumar (67), Frank Welker (66), Raza Murad (61), Shakti Kapoor (52), Eric Roberts (51)…
Which five of those have been in the most highly rated films?
Counting titles rated 7.0 or better with at least 1,000 votes: Frank Welker (103), Nassar (73), Tanikella Bharani (54), Brahmanandam (49), Anupam Kher (42).
Compare those five, and tell me which two have worked together most.
Frank Welker has by far the most votes across his filmography (4.9M) and the highest mean rating (6.75); Brahmanandam has the most credits (1,131) and the highest credits per year (28). Tanikella Bharani and Brahmanandam have appeared together 168 times.
What did those two make together?
Ghilli (2004, 8.2), Dookudu (2011, 7.4), Race Gurram (2014, 7.4), Khaleja (2010, 7.6), Bommarillu (2006, 8.2)… — 168 titles in all, most-voted first.
Every one of those turns is a single tool call whose arguments are the previous turn's arguments with one field changed, and each refinement passes the previous result's IMDb ids back in. The server keeps no session state.
Put two to ten named people side by side on the same measures.
Answers questions like: "Compare Eric Roberts, Danny Trejo, James Hong, Samuel L. Jackson and Christopher Walken", "Who between De Niro and Pacino has the higher rated filmography?", "Which of these five has the longest career?", "Have any of these people worked together?".
Every number comes from the same code path a ranking uses, so a value here and the same value in a rank_people row cannot disagree. Returns one compact row per person with credits, career length, credits per year, rating measures, recognition scores and background share, plus, in query_summary.pairs, the shared-title count and the number of common collaborators for every unordered pair. That pairs block is what answers "which two of these have worked together most" without a second call.
Takes IMDb name ids in either form. It is a comparison, not a search: to find the people first, use search_people or rank_people, then pass their ids here. For the titles two of them actually share, follow up with find_collaborations in shared_titles mode.
| Name | Required | Description | Default |
|---|---|---|---|
| person_ids | No | ||
| credit_definition | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description adds meaningful behavioral guarantees: 'Every number comes from the same code path a ranking uses, so a value here and the same value in a rank_people row cannot disagree.' It also discloses the return shape ('one compact row per person... plus, in query_summary.pairs...') and that IDs are accepted 'in either form.' These are non-obvious traits an agent needs.
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 long but every section earns its place: purpose, examples, consistency guarantee, return summary, ID format, and routing to siblings. The examples are illustrative rather than padding. It could be slightly tighter, but it remains well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and two parameters, the description covers the core context: what is compared, how results are shaped, how IDs are passed, and how to follow up for shared titles. Missing details like behavior for null or fewer-than-two person_ids and the single-person get_person alternative are not critical given the schema and sibling context, but they would make it more 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?
The description clarifies person_ids semantics by saying 'Takes IMDb name ids in either form' and implies a two-to-ten count, which the schema does not enforce. However, it does not explain the credit_definition parameter in prose; it only hints at consistency with ranking. With schema description coverage reported as 0%, the description should compensate more, so this is adequate but not strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Put two to ten named people side by side on the same measures.' It also includes illustrative queries and explicitly distinguishes itself from search: 'It is a comparison, not a search.' This makes the tool's purpose unmistakable and distinct from siblings like search_people and rank_people.
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 routing guidance: 'to find the people first, use search_people or rank_people, then pass their ids here' and 'For the titles two of them actually share, follow up with find_collaborations in shared_titles mode.' This clearly states when to use this tool versus the relevant alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who has worked with whom, in five shapes selected by mode.
Answers questions like: "Which actors have worked with Samuel L. Jackson most often?" (collaborators_of, one id), "What films do Jackson and Walken share?" (shared_titles, two ids), "Which two people in this list have appeared together most?" (pairwise, two or more ids), "Who has worked with all five of these people?" (worked_with_all, one or more ids), "How many steps connect these two?" (degrees_of_separation, two ids, at most three hops).
Every mode counts at the unit level, so a series shared across forty episodes counts
once, and every mode honours the credit definition, so "only their films together" is
include_tv_series=false, include_tv_movies=false, include_video=false. limit bounds
the returned collaborators; max_hops bounds the path search.
The hard limit is the data, not the query: IMDb's principal-cast list holds at most 69 people per title, so a shared credit means both people are in that top-billed subset. Its absence is not evidence they never worked together, and a "no path found" result means no path through principal casts within the hop limit. Pass ids, not names; use search_people first.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| limit | No | ||
| max_hops | No | ||
| person_ids | No | ||
| credit_definition | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses counting semantics (series counted once per unit), credit-definition honoring, the principal-cast hard limit of 69 people per title, and the crucial caveat that absence of a shared credit is not evidence against collaboration. This is exceptionally useful behavioral context.
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 long, but every sentence carries useful information for a multi-mode tool. It is front-loaded with the core question, then organizes mode behavior, shared semantics, and data caveats in clear paragraphs. There is no fluff 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?
Given the tool's complexity, the description covers the five distinct modes, the role of key parameters, the data limitations, and the necessary search_people prerequisite. An output schema exists, so the description does not need to explain return values. This is a complete and self-sufficient definition.
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?
Although the top-level schema has little description coverage, the prose explains the mode enum with five worked examples, states that limit bounds returned collaborators, and that max_hops bounds the path search. It also conveys the meaning of credit_definition through the include_tv_series/include_tv_movies/include_video example. It does not formally name the person_ids parameter, but the examples and 'Pass ids, not names' adequately compensate.
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 opens with a clear query intent, 'Who has worked with whom,' and then enumerates all five modes with concrete example questions. It also distinguishes itself from sibling tools by instructing the agent to 'use search_people first' for name resolution, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage context: which mode to pick for which question shape, the meaning of limit and max_hops, and the prerequisite 'Pass ids, not names; use search_people first.' It does not explicitly contrast with siblings like compare_people or rank_people, but the mode examples make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything known about one person, recomputed under whatever credit definition you pass.
Answers questions like: "Tell me about Samuel L. Jackson", "How many movies has Eric Roberts actually been in?", "What are Danny Trejo's best-known films?", "Is Bess Flowers mostly an extra?", "How long has James Hong been working, and in what genres?".
Takes an IMDb name id, either "nm0000168" or its numeric form 168. Returns the person's credit count under the definition you gave, career span, top titles by votes with the billing position and characters, genre and decade breakdowns, frequent collaborators, and the precomputed career, recognition and background-work statistics with their components exposed. This is the one tool that returns full component detail; the ranking tools return compact rows.
The recognition and background-work blocks are always the default-definition values and do not move when you change the credit definition, which the response states. Change the definition to answer follow-ups directly: "restrict to theatrical films" is include_tv_series=false, include_tv_movies=false, include_video=false; "count every episode" is include_tv_episodes=true with count_series_as_one=false.
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | ||
| top_titles | No | ||
| credit_definition | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the readOnly/idempotent annotations: recognition and background-work blocks always use default definitions and do not change with the credit definition, and the voice filter is an approximation via Animation genre. These non-obvious behaviors are exactly what an agent needs to avoid misinterpreting results.
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 dense but every sentence earns its place: core purpose, example queries, summary of return fields, distinction from siblings, and parameter guidance. It is front-loaded with the essential sentence and uses short paragraphs and examples rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and a complex nested credit_definition object, the description fully covers the important semantics, caveats, and usage patterns. With an output schema present, return-value details are not needed. Nothing an agent needs to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is listed at 0%, the description compensates richly: it explains the person_id format (nm string or numeric form), clarifies the credit_definition object with named presets and concrete flag combinations, and reveals behavioral quirks like include_adult skewing lists. It adds practical semantics that the raw schema alone would not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource ('Everything known about one person') and distinguishes itself from siblings by noting it is the only tool returning full component detail while ranking tools return compact rows. The examples of questions ('Tell me about Samuel L. Jackson') make the use case instantly 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?
Description explicitly explains when to use this tool versus ranking tools, gives concrete question types, and shows how to adjust the credit definition for follow-ups with specific flag examples. It even maps natural language requests like 'restrict to theatrical films' to exact parameter settings, leaving little ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank people by any measure, under any filter and any definition of an acting credit.
This is the tool for every superlative question and every refinement of one. Answers questions like: "Who are the 25 most prolific actors?", "Same list, but only people recognizable enough that an audience would know them", "Now only living actors born before 1960", "Who has the longest career?", "Which prolific actors have the most highly rated films?", "Rank these five by career length instead".
Follow-ups are the previous arguments with one field changed, so keep the whole filter object and edit it. The fields that carry the common follow-ups: "women only" is filters.professions_any=["actress"], an approximation of the credit and not of the person, until gender enrichment lands; "living only" is filters.living_only=true; "born after 1950" is filters.birth_year_min=1951; "remove the extras" is filters.max_background_share, around 0.5; "make it recognizable" is filters.min_prominence or sort_by="prominence_score"; "at least ten well-rated films" is filters.min_highly_rated_titles=10 with filters.title_rating_min and title_votes_min setting the bar; "restrict to theatrical films" is credit_definition.include_tv_series=false, include_tv_movies=false, include_video=false.
To re-rank a result you already have rather than re-running the whole filter chain, pass its ids as filters.person_ids and change sort_by. Page with next_cursor, handing it back unchanged with the same sort.
sort_by choices: acting_credits, prominence_score (peak recognition), exposure_score (volume of seen work), career_length, credits_per_year, average_rating, weighted_rating (Bayesian, pulls thinly voted careers toward the mean), total_votes, highly_rated_titles, max_title_votes, collaborator_count.
What it cannot do: filter by nationality, gender or award, which need Wikidata enrichment that lands in M4 and error until then; separate voice roles from on-screen ones, because IMDb's datasets carry no voice flag and the include_voice parameter approximates it with the Animation genre; or filter uncredited roles, which the datasets do not mark at all. collaborator_count is an anchored self-join and is refused for candidate sets over a thousand people.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| filters | No | ||
| sort_by | No | acting_credits | |
| sort_direction | No | desc | |
| credit_definition | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral caveats: Wikidata-dependent filters error until M4, include_voice approximates voice roles via the Animation genre, uncredited roles are not marked in the data, and collaborator_count refuses candidate sets over a thousand people. These go well beyond the structured hints.
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 long but densely packed with useful routing, filtering, limitation, and paging guidance. Every sentence carries operational value, and the structure moves from purpose to follow-ups to re-ranking/paging to sort options to explicit limitations, keeping the most important selection cues front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six top-level parameters, nested schemas, many enum choices, and an output schema, the description covers the full call cycle: when to use it, how to express common follow-ups, how to re-rank, how to page, what sort values mean, and what will fail and why. It is complete enough for an agent to invoke it correctly without external help.
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?
Despite the low reported schema coverage, the description compensates by mapping natural-language follow-ups to exact parameter paths: 'women only' → filters.professions_any, 'living only' → filters.living_only, 'remove the extras' → filters.max_background_share, and theatrical restrictions → credit_definition.include_tv_series. It also explains each sort_by value and the meaning of cursor and person_ids for re-ranking.
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?
Description opens with a specific verb and resource: 'Rank people by any measure, under any filter and any definition of an acting credit.' It immediately clarifies this is the superlative-question tool and gives concrete example questions, distinguishing it from the sibling search and comparison tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'This is the tool for every superlative question,' explains common follow-ups and how to encode them as filter fields, and tells the agent to reuse person_ids for re-ranking an existing result. It also states clear exclusions: what the tool cannot do, such as nationality, gender, award, voice-role, and uncredited-role filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find people by name and pick the right one before spending another call on them.
Answers questions like: "Who is James Hong?", "Is there more than one Michael Caine?", "Find the Danny Trejo who acts", "Which Sarah Douglas has the most credits?", "What is Bess Flowers' IMDb id?".
Returns each match with its imdb_name_id, birth and death years, listed professions,
credit count under the default definition, prominence score and best-known titles,
ordered exact match first, then prefix, then credit count. Use the imdb_name_id it
returns for every later call rather than passing the name again. filters accepts the
same person filter as rank_people, which is how you disambiguate two people with the
same name by birth year or profession.
This is lookup, not ranking: it never scans the whole catalogue, so do not use it to answer "who has the most credits" or any question with a superlative in it. It cannot search by nationality, gender or award, which need enrichment that does not land until M4, and it matches on the primary name only, not alternate spellings or credited-as names.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| filters | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: exact-match-first ordering, the fields returned, the fact that it never scans the whole catalogue, primary-name-only matching, and M4-dependent filter limitations. No statement contradicts 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 dense but every sentence carries information: concrete examples, return semantics, ordering, cross-tool filter reuse, and explicit non-goals are all packed in without filler. The most decision-relevant claim—lookup, not ranking—appears early.
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 output schema exists and the description already covers return fields, ordering, filter semantics, and limitations, an agent has everything needed to select and invoke this tool correctly. The only omitted item, limit behavior, is minor and inferable from the schema default.
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?
Yet 0% top-level schema description coverage, the desc">ription compensates for the required 'name' parametir and 'filters' object, e"plaining that filters mirror rank_people and are used to disambiguate same-name people by birth year or profession. It does not e"plicitly e"plain 'limit', though the schema's default of 20 and the return-ordering sentence make its role inferable, so the compensation is strong but not total.
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 opens with a specific verb and resource—'Find people by name and pick the right one'—and immediately separates the tool from ranking tools by declaring 'This is lookup, not ranking.' Example questions make the intended use unmistakable, and the final sentence names concrete unsupported dimensions (nationality, gender, award) that distinguish it from sibling tools.
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?
It gives explicit when-to-use context ('before spending another call on them'), tells the agent to use the returned imdb_name_id for later calls, and issues clear exclusions: do not use for superlative questions, nationality/gender/award searches, or alternate-name matching. It also points to rank_people for the shared filter vocabulary, giving the agent a route to the sibling tool's semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find and rank titles by text, type, year, genre, rating, votes, or who is in them.
Answers questions like: "What are the highest rated horror films of the 1980s?", "Find the movie called Heat", "Which titles have both Samuel L. Jackson and John Travolta in the principal cast?", "List Danny Trejo's titles with over 100,000 votes", "What TV series started in 1999 and are rated above 8.5?".
Returns compact title rows with imdb_title_id, type, year, runtime, genres, rating and votes. filters.with_person_ids keeps only titles whose principal cast contains every one of the named people, which is the direct way to ask "what did these two make together" when you want the title's own metadata rather than the collaboration count. Page with next_cursor, unchanged, with the same sort.
What it cannot do: only 1.7 of 12.8 million titles carry any rating, so a rating or
vote filter is also a coverage filter and drops everything unrated. There is no
theatrical-release flag: the video title type is direct-to-video, but a movie may
also have gone straight to video, so this is a title-type filter and never a
distribution one. A person filter here uses the default credit definition and matches
the unit title, so a credit on an episode matches its series.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| filters | No | ||
| sort_by | No | votes | |
| sort_direction | No | desc |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent, but the description adds substantial behavioral detail: only 1.7 of 12.8 million titles have ratings, rating/vote filters drop unrated titles, there is no theatrical-release flag, and person filtering uses a default credit definition that can match a series through an episode. These caveats go well beyond the annotations and are essential for correct use.
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 long but well-structured: a one-line purpose, illustrative examples, return-format summary, pagination note, and a clearly labeled limitations section. Each section earns its place, though the number of examples makes it slightly more verbose than strictly necessary.
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 tool with five parameters, a nested filters object, and an output schema, the description covers the key invocation scenarios, pagination, return fields, and critical data-coverage caveats. It is missing only minor explicit guidance on sorting options, which the schema's enum already provides, so the agent can still invoke the tool correctly.
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 reported as 0%, the description compensates by explaining the main filter dimensions (text, type, year, genre, rating, votes, person IDs) and the meaning of with_person_ids. It also clarifies pagination via next_cursor. However, it does not directly explain sort_by, sort_direction, or limit semantics, and the nested schema descriptions carry some of that weight.
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 opens with a specific verb and resource: 'Find and rank titles by text, type, year, genre, rating, votes, or who is in them.' It gives concrete example queries and distinguishes itself from the people-focused sibling tools by emphasizing title metadata and explicitly contrasting with the collaboration-count use case.
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 provides clear usage context through examples and directly explains when with_person_ids is the right approach versus when the user wants a collaboration count instead. It also documents important boundary cases in 'What it cannot do', but it does not explicitly name sibling tools as alternatives, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0compare_peoplefind_collaborationsget_personrank_peoplesearch_peoplesearch_titlesScored across 6 tools
Each tool has a clearly distinct purpose: ranking people, searching for a specific person, retrieving one person's details, comparing a fixed set of people, finding collaborations, and searching titles. The descriptions actively clarify boundaries, e.g. search_people is lookup not ranking, and compare_people is not a search. There is no real risk of selecting the wrong tool.
All tool names follow a consistent snake_case verb_noun pattern: rank_people, search_people, get_person, compare_people, find_collaborations, search_titles. The verbs are clear and the nouns consistently identify the entity being acted on. Minor singular/plural variation does not create confusion.
Six tools is well-scoped for a read-only analytics server. Each tool covers a distinct query shape without redundancy. The count feels intentional rather than padded or thin.
The server covers the main person-analytics workflows well: discover, rank, inspect, compare, collaborate, and filter titles by people. The only notable gap is the absence of a dedicated title-detail tool for full cast/crew or richer title metadata, but search_titles and the collaboration tools provide reasonable workarounds.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A collaborative substrate over your data: vector, knowledge graph, SQL, geospatial, streaming.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Media memory for AI agents and their humans: books, movies, music, shows, anime, podcasts, games.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
