IMDb MCP server

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety bar is met structurally. The description adds genuinely useful behavior: keyset pagination via next_cursor, per-page limit, sort field vocabulary, and the AND semantics of keywords ('all required'). No auth or rate-limit notes, but nothing expected is missing for a read-only search.

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?

Purpose and a concrete example are front-loaded in two sentences, followed by an Args block that is justified by the 0% schema coverage. Each line is one clause with no marketing padding; the only mild redundancy is that some lines restate the parameter name.

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 13-parameter all-optional search with an output schema covering return shape, the description is close to sufficient: filters, sorting, and pagination are all addressed. The one meaningful hole is the absence of any statement about whether at least one filter is required or how filters combine (AND vs OR) when several are supplied.

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 carries the full burden and largely delivers: every one of the 13 parameters gets a line, with allowed values for title_types, sort and order, and a range (1–10) for min_rating. Gaps remain — the genre list is only illustrative ('as IMDb spells them') and there is no hint of defaults or of combining multiple genres.

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?

States a specific verb (search) and resource (titles) plus the dimensions it can filter on, and the IMDb 'advanced search' framing distinguishes it in spirit from the plain search_titles sibling. However, it never names search_titles or get_result_page, so the boundary between 'advanced' and simple search is left implicit.

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 worked example ('best rated horror films of the 1970s with over 10,000 votes is one call') makes the intended compound-filter use case clear. But there is no explicit routing guidance — nothing says when to prefer search_titles or get_result_page, or whether zero filters is a legal call.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile needs no restating. The description's genuine addition is that filters are AND-combined rather than OR'd, plus the 1-10 rating bound and date format. It does not say what limit=100 means for completeness, whether results are truncated, or how totals are reported, which matters for a 14-filter search over a whole history.

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?

Front-loaded with a single purpose sentence, then compactly enumerated arguments in the same order an agent will fill them. No filler prose; the length is justified by 14 undocumented parameters. The example phrases cost a little space but earn it by demonstrating filter composition.

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 14-parameter, zero-schema-coverage search tool, the description covers purpose, filter composition, and per-parameter meaning, and the output schema handles return shape. What's missing is the relationship to the sibling my_ratings/my_rating_for and any statement about result pagination or caps.

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 carries the full burden — and it discharges most of it, glossing all 14 parameters with useful specifics (rating 1-10, revised YYYY-MM-DD date format, sort keys enumerated, title_type examples). Gaps remain: the query matching semantics (substring vs fuzzy), whether genre is exact-match, and how year coexists with year_from/year_to are unstated.

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?

States a specific verb and resource with scope: "Search the configured user's whole ratings history." The agent knows exactly whose data and what domain. It stops short of naming the near-identical sibling my_ratings or my_rating_for, so differentiation must be inferred from the name alone.

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 line "Every filter is optional and they combine" plus three natural-language examples conveys how filters compose, which is real usage guidance. However, nothing says when to prefer this over my_ratings, my_rating_stats, or advanced_title_search, and no exclusions are stated.

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

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 covered. The description contributes useful detail about what data is returned (budget, opening weekend, lifetime grosses, broken out by area), but says nothing about missing-data behavior, partial results, or coverage across regions.

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 one-sentence purpose statement is front-loaded and waste-free, and the Args block is brief. The 'Args:' docstring style is slightly boilerplate but costs little.

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?

An output schema exists, so return values need not be spelled out, and the description still enumerates the main data categories. With a single required parameter and read-only annotations, the definition covers everything needed to invoke the tool correctly, apart from id format.

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 carries the burden; it does clarify that 'id' means a Title id rather than a name id, which matters given siblings like get_name and search_names. However it gives no format hint (e.g. tt-prefixed vs numeric), leaving the agent to guess the expected identifier shape.

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 the specific resource (budget, opening weekend, lifetime grosses, by area) scoped to a title, which is clearly distinct from siblings like get_title_credits or get_title_reviews. It stops short of explicitly contrasting itself with get_title, but the resource is 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?

There is no guidance on when to use this tool versus alternatives such as get_title or get_title_reviews, and no prerequisites or exclusions are stated. The agent must infer usage purely from the resource phrase.

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

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

Annotations already declare the read-only, idempotent, non-destructive, open-world profile, so the safety burden is covered. The description adds real behavioral context beyond that: results are paginated, limit is per page, and cursor must be the next_cursor from the prior page, which is the key operational detail for a paginated endpoint.

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?

Front-loaded purpose sentence followed by a compact Args block; every line earns its place. Slight redundancy between the opening list of chart themes and the repeated enumeration in Args.

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?

With an output schema present, the description need not explain return values, and it covers all three params plus pagination mechanics. Complete enough to invoke correctly; only defaults and explicit sibling routing are absent.

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 there are no enums, so the description must carry the load — and it does, fully enumerating the six valid chart strings, which the schema does not. It also explains limit as entries per page and cursor as the prior page's next_cursor. It stops short of stating defaults (top_rated_movies, 25), which the schema does carry.

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?

Opens with a specific verb-resource framing ('IMDb's charts') and enumerates the concrete chart types, so an agent knows this returns ranked chart listings. It implicitly distinguishes itself from get_box_office by naming chart categories rather than box-office data, though it never says so outright.

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?

Enumerating the chart values implies when each is appropriate (Top 250 vs lowest rated vs most popular), which is useful. However, there is no explicit guidance on when to prefer this over siblings like get_box_office or advanced_title_search, and no stated prerequisites.

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

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

Annotations already declare read-only, idempotent, open-world behavior, so the description's job is to add operational context — and it does, stating the sort order ('soonest first'), the from_date default of today, and that cursor comes from a previous page. It doesn't discuss rate limits, page-size ceilings, or total-count behavior, so a 4 rather than 5.

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 single-sentence purpose statement is front-loaded and the Args block is terse, one line per parameter. The Args list partially restates schema field names, but each line still contributes semantics (allowed values, format, defaults) rather than pure 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?

With an output schema present, the description needn't explain return shape, and it correctly focuses on ordering, date defaults, and pagination chaining. What's missing is only marginal: whether results are limited to a window (e.g., theatrical only), and confirmation of default kind/limit values.

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%, so the description carries the full burden and largely meets it: it supplies the allowed values for kind ('movie or tv'), the YYYY-MM-DD format for from_date along with its today default, what limit counts (per page), and the chaining rule for cursor. Remaining gaps are minor — the default values for kind (movie) and limit (25) are only in the schema, not restated.

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 opening line 'Upcoming releases, soonest first' names a specific resource and its ordering, which is clearly distinct from query-oriented siblings like search_titles or advanced_title_search. It stops short of naming an alternative sibling explicitly, so it lands just below the top band.

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?

Usage is implied by 'upcoming releases' and the from_date default of today, so an agent can infer this is the discovery tool for future titles. There is no explicit when-not guidance, no mention of how it differs from search_titles for a date-ranged query, and no prerequisites stated.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the useful constraint that only public lists are reachable and that results are paginated via cursor, but says nothing about error behavior for private/invalid ids or how pagination terminates.

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?

Three lines total, front-loaded with the resource and followed by a clean Args block; nothing is padded. The opening sentence is slightly ungrammatical but the information density is high.

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?

With an output schema present, return values need not be described, and all three parameters are explained, which covers what an agent needs to make a valid call. It falls short of complete only on failure modes (private list, bad id) and how to detect the end of pagination.

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 carries the full burden and mostly succeeds: it gives a concrete id format (ls055592025) plus the alternative of a URL, explains limit as page size, and explains cursor as the next_cursor from the prior page. Only limit's interaction with defaults/paging limits is left implicit.

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+resource ('get ... IMDb list') and constrains it to public lists by ls id, which is enough to tell it apart from get_title, search_titles, and get_chart. The trailing 'titles or people' is ambiguous (it is unclear whether it describes the id format or list contents), which keeps it short of a 5.

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?

There is no statement of when to use this versus the many siblings (get_chart, search_titles, advanced_title_search, get_result_page), and no exclusions or prerequisites. The only guidance is the implied constraint that the list must be public.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is fully covered. The description adds only a listing of returned content, and adds nothing about unknown-id behavior, rate limits, or lookup failures.

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?

One sentence plus a single parameter line; the purpose is front-loaded and the parameter note is attached directly to the arg. Nothing is padded or repeated.

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?

With rich annotations, an output schema, and exactly one required parameter that the description documents in both accepted formats, the definition covers what an agent needs to invoke it. Only minor gaps remain (failure/not-found behavior).

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%, so the description carries the full burden and does meaningful work: it specifies the IMDb name-id format (nm0000244) and that a full IMDb URL containing an id is also accepted. That is real added meaning beyond the bare "Id" string property.

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?

States a specific verb and resource ("Get one person") and enumerates the payload (biography, dates, professions, known-for titles), which is more informative than the bare name. It does not explicitly differentiate itself from search_names or get_name_credits, so it stops short of a 5.

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?

Usage is only implied: a reader infers this is the detail lookup once an id is known, while get_name_credits or search_names handle other needs. No explicit when-to-use, exclusions, or alternative routing is stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: result ordering ('newest first') and the cursor-based pagination contract ('next_cursor from the previous page').

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?

One-line summary plus an Args block; every line conveys something usable and nothing is padded. The docstring formatting is slightly mechanical but front-loads the purpose correctly.

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?

Output schema exists, so return shape needn't be described; ordering and pagination are covered, all parameters are explained, and the category filter is fully enumerated. An agent has everything needed to call this correctly on the first attempt.

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 carries the full burden and mostly does: it documents all four parameters, enumerates the eight allowed category values (information not present in the schema at all), and explains the cursor's provenance. It omits the limit default of 50 and doesn't say where the required id comes from (e.g., search_names, get_name).

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?

States a specific resource and scope: a person's filmography, with an explicit ordering (newest first). It implicitly separates itself from get_title_credits by being name-centric rather than title-centric, but never names the sibling to make the distinction explicit.

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?

Usage is only implied by the purpose statement; there is no explicit when-to-use or when-not-to-use guidance, and no mention of when to prefer get_title_credits or get_name. The category-omission note ('Omit for everything') is the only real usage instruction.

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

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

The annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: nothing is re-fetched or re-executed, the stored result is paged/filtered/narrowed in place, which reassures the agent this is a cheap, safe re-read.

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?

Purpose is front-loaded in the first sentence, then the usage mechanism, then a per-argument block. Every line carries information (syntax, defaults, examples) with no 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?

With six parameters, zero schema description coverage, and an output schema that already documents return shape, the description supplies everything the agent needs: provenance of result_id, semantics of each optional filter, and the no-refetch behavior. Nothing material 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?

Schema description coverage is 0%, so the description carries the full burden and does so thoroughly: it explains result_id provenance, offset meaning (usually the prior next_offset), limit behavior (may return fewer), fields with dotted-path syntax and an example, match with case-insensitivity and an example, and path defaulting to the largest list. This is exactly the compensation required.

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?

States a specific verb and resource — reading another page of a previously returned oversized result — and explains the mechanism concisely in the first sentence. No sibling tool in this API surface does anything similar, so distinctiveness is inherent.

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 when to call it: when an earlier answer was too large and returned a `paging` block, pass that block's `result_id`. There is no meaningful alternative to route between and no when-not guidance, which keeps this just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description's one contribution is that the list is what IMDb itself lists (i.e., ordering is external/curated, not computed by the tool) — useful, but nothing is said about ordering guarantees, whether limit is silently capped, or behavior when the id is unknown.

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 purpose sentence is front-loaded and waste-free. The trailing "Args:" block is largely redundant with the input schema, but it is short and does not obscure the core statement.

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?

An output schema exists, so return-value explanation is not required, and annotations cover the safety profile. What remains missing for a two-parameter tool at 0% schema coverage is the id format and the semantics of limit — gaps the description should have closed but does not.

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 carry the burden, yet it only restates the schema property labels ("id: Title id", "limit: How many to return"). It never specifies the id format (e.g., IMDb tt-prefixed ids) or any bound on limit, so an agent still cannot construct a valid call with confidence beyond guessing.

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 "Titles IMDb lists as more like this one" unambiguously identifies the resource: a similarity/recommendation list for a given title, clearly distinct from siblings like get_title, get_title_reviews, or get_title_credits. It lacks an explicit verb ("return"/"fetch") and is written as a noun fragment, so it falls short of the ideal verb+resource form, but the resource is unmistakable.

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?

There is no when-to-use guidance and no mention of alternatives, despite many siblings that could plausibly be confused with it (get_title, search_titles, get_title_reviews). The agent must infer that this is for recommendations rather than for general title lookup, entirely from the one-line purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds only that the payload is comprehensive, without covering not-found behavior, payload size/cost, or whether missing fields are omitted or nulled.

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 core sentence is front-loaded and dense with useful information, and the Args block is short. The field enumeration is slightly list-like and partially redundant with the output schema, but nothing is padded.

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?

An output schema exists, so return-shape detail is unnecessary, and rich annotations cover safety and idempotency. For a single-parameter read tool, the description supplies the one thing structured fields lack: the accepted id formats.

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 carries the parameter burden and does so well: it gives the IMDb-id format with a concrete example (tt0078748) and, importantly, states that a full IMDb URL containing an id is also accepted. It stops short of describing validation or error behavior for malformed input.

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?

States a specific verb and resource ('Get one title in full') and enumerates the returned facets (plot, ratings, cast and crew, genres, release, certificate, awards, taglines, poster). This implicitly separates it from narrower siblings like get_title_credits or get_title_reviews, though it never names them explicitly.

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?

There is no explicit when-to-use or when-not-to-use guidance; the routing signal is only implied by 'in full' versus the focused siblings in the same namespace. An agent must infer that this is the aggregate fetch and the sibling tools are the targeted ones.

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

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

Annotations already cover the safety profile (readOnly, idempotent, open-world, non-destructive), so the bar is lower. The description adds meaningful behavior beyond them: default ordering puts cast first, cast entries carry characters, and results are paginated via a cursor chain.

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 capability statement is front-loaded in one sentence, followed by a tight Args list with no filler. The phrasing is slightly telegraphic ('Omit for everyone, cast first') but every line earns its place.

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?

Output schema exists, so return values need not be explained, and all four inputs are covered. The only small gap is that it doesn't say whether non-cast categories include characters or role labels, but that is minor for a filtered list tool.

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 carry the load — and it does, documenting all four parameters including the allowed category values (director, writer, actor, actress, producer, composer, cinematographer, editor) and how cursor chains from the previous page. This is materially more than the schema conveys.

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 first sentence states a specific verb and resource ('List who worked on a title') plus the cast-character nuance, which separates it conceptually from the inverse get_name_credits. It stops short of explicitly naming the sibling it complements, so it falls just short of a 5.

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 useful in-tool guidance — omit category to get everyone with cast first, and use next_cursor for the next page — which is genuine usage help. However, it never says when to prefer this over get_name_credits, get_title, or advanced_title_search, so routing between siblings is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: episodes are paginated by limit and continue via the previous page's next_cursor, and omitted season returns all in order. It stops short of noting ordering guarantees beyond 'in order' or error behavior for invalid seasons.

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?

One front-loaded purpose sentence followed by a tight Args block; every line adds information. Slightly mechanical format but no wasted prose.

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?

With an output schema present, return values need not be described, and pagination plus filtering is fully specified. Enough to call correctly; only edge-case behavior (invalid season, cursor expiry) is unaddressed.

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%, so the description carries the full burden — and it does: id is identified as the series title id, season as an optional single-season filter, limit as page size, and cursor as the prior page's next_cursor. Only minor gaps (e.g. limit bounds/default of 50) remain.

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?

Specific verb ('List') plus resource ('a series' seasons and episodes with their ratings'), which clearly separates it from siblings like get_title_credits or get_title_reviews. It doesn't explicitly name the sibling it replaces (e.g. get_title for the overview), so it falls short of a 5.

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 args notes imply usage ('Omit for all, in order') and explain the paging flow via cursor. There is no explicit statement of when to choose this over get_title or other title-detail siblings, so routing guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds genuine context beyond that — the 'most helpful first' ordering and the pagination contract that cursor comes from the previous page's next_cursor — but says nothing about review language, filtering, or rate limits.

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 purpose sentence is front-loaded and wastes no words; the Args block is compact and scannable. Slight deduction because the docstring-style arg list duplicates parameter names already visible in the schema.

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 paginated read tool with an output schema (which covers return fields including next_cursor), the description supplies what's needed: ordering semantics and the page-chaining rule. Minor gaps remain around whether reviews are filtered by language or spoiler status, but nothing required to invoke it 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?

Schema description coverage is 0%, so the description carries the full burden, and it does define all three parameters: id as a title id, limit as reviews per page, and cursor as the next_cursor from the prior page. The definitions are terse (no format examples, and 'Title id' is nearly circular) but they disclose each parameter's role and the pagination linkage.

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?

States a specific verb and resource ('Read user reviews of a title') plus the result ordering ('most helpful first'), which no sibling tool provides. The resource is clearly distinct from get_title, get_title_credits, and get_title_episodes, though no sibling is named explicitly.

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?

Usage is only implied: an agent infers this is the tool for reviews as opposed to title metadata or credits. There is no explicit when-to-use statement, no exclusions, and no named alternative for related needs.

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

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. The description adds only that the subject is 'the configured user' (hinting at a config dependency) but says nothing about what happens if no user is configured or how counts are scoped.

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?

One sentence, front-loaded with the subject and immediately followed by the payload. No 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?

An output schema exists, so return values need no explanation, and annotations cover safety. However, for a tool whose whole purpose is resolving the current user, the description leaves out the configured-user precondition and its relationship to the my_* siblings.

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?

Zero parameters, so the baseline is 4 — there is no parameter semantics to explain. The description correctly implies the call takes no arguments by describing an implicit 'configured user' subject.

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?

States a specific resource — the configured IMDb user's profile — and names what it returns (ratings and watchlist counts), which separates it from list-style siblings like my_ratings and my_watchlist. It stops short of explicitly contrasting itself with those siblings.

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?

Usage is only implied: an agent can infer this is the entry point for 'who am I' before calling my_ratings or my_watchlist, but the description never says when to use this versus those tools or whether configuration/auth is a prerequisite.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful context that a rating may not exist ('if anything') and that the id comes from search_titles, but it does not elaborate on authentication/configured-user behavior or response details.

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 short and front-loaded: the core behavior appears in the first sentence, followed by a compact Args note. No unnecessary text.

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 read operation with rich annotations and an output schema, the description is nearly complete: it states the purpose, id source, and that absence is possible. Minor gaps remain around the 'configured user' context, but nothing essential 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?

Schema coverage is 0%, so the description must carry parameter meaning. It identifies the sole parameter as a title id and gives its source ('from search_titles'), which is meaningful context beyond the schema's bare type string.

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 clearly states a specific verb/resource: fetch the configured user's rating for one title, including the possibility that no rating exists. It implicitly distinguishes itself from plural/list siblings like my_ratings through 'one title', but does not explicitly name alternatives.

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?

Usage is implied: call this when you need the configured user's rating for a specific title, using an id obtained from search_titles. It does not explicitly say when to use my_ratings or find_my_ratings instead, so the guidance is adequate but not fully explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the safety profile is covered; the description adds the pagination mechanics (per-page window, cursor chaining) that annotations cannot express. It doesn't state what an exhausted/absent cursor yields, but the output schema carries next_cursor.

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?

One-line purpose, one-line routing rule, then a tight Args list. Front-loaded and every sentence carries either routing or parameter meaning; nothing is redundant.

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?

With an output schema present, return values needn't be described, and pagination plus alternatives are covered. Only minor edges are unaddressed, such as behavior on an invalid or expired cursor.

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% and the schema declares no enums, yet the Args block defines all four parameters: sort values (recent = by date rated, top = by rating given), order (DESC/ASC), limit with the 250 ceiling, and cursor tied to next_cursor from the prior page. This fully compensates for the missing schema descriptions.

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?

States the resource precisely — the configured user's own ratings — and adds the paginated scope ('one page at a time'), which separates it from bulk-aggregate siblings. It stops short of an explicit verb ('list/retrieve') but the meaning is unambiguous against my_ratings-style siblings.

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?

Names the alternatives explicitly (find_my_ratings, my_rating_stats) and the condition that selects them: 'questions over the whole history'. That leaves the agent with a clear rule for when to use this tool versus its two closest siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds the useful behavioral detail that the scope is the configured user's entire history rather than a filtered subset, which the annotations do not convey. It does not discuss cost or response size for a potentially large history.

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 front-loads what the tool returns, then enumerates the metrics in a compact colon list. Every clause adds content; nothing is redundant or padded.

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?

With no parameters, an output schema present, and rich annotations, the description only needs to convey scope and the metric set — both are stated. An agent has everything required to call this 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?

There are zero parameters, so the baseline is 4. The description still earns its keep by clarifying that the user is 'configured' — i.e., the tool implicitly targets the authenticated user, which explains why no parameter is needed.

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 resource (aggregate statistics over the configured user's ratings history) and enumerates exactly which figures are computed (count, average, 1-10 spread, per-year, genres, decades, IMDb comparison). The aggregation framing implicitly separates it from listing siblings like my_ratings or my_rating_for, but no sibling is named explicitly.

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?

Usage is only implied: the phrase 'whole ratings history' suggests when this aggregate view is appropriate rather than a per-title lookup. There is no explicit when-to-use/when-not, no mention of alternatives such as my_ratings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile needs no restating. The description adds one genuine behavioral fact beyond them — results come back in list order — and documents pagination mechanics, but says nothing about auth requirements, empty-watchlist behavior, or whether ordering is user-customizable.

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?

One front-loaded sentence states the core contract, followed by a compact Args block for the two parameters. No filler, though the docstring-style formatting is slightly verbose relative to the single sentence of real content.

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?

An output schema exists, so return-value explanation is not needed, and the cursor/next_cursor loop is covered. Still missing for a paginated list tool: whether the watchlist can be empty, whether ordering is fixed, and any hint about page-size limits or cost of large limits.

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 carries the full burden and largely does: limit is 'how many per page' and cursor is explicitly 'next_cursor from the previous page', which ties the input to the output field an agent must feed back. Defaults (50, null) are only in the schema, which keeps this from a 5.

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?

States a specific resource and scope: the titles on the configured user's watchlist, returned in list order. An agent can distinguish this from my_ratings, my_rating_stats, or get_list by the resource named, though it never explicitly contrasts itself with those siblings.

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?

Usage is implied by the resource name — fetch the authenticated user's watchlist — with no explicit when-to-use or when-not conditions and no named alternatives. The pagination args hint at a browse workflow but the description never states it.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds nothing beyond that — no note on result ordering, empty-match behavior, or truncation — which is a modest but not fatal gap given 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?

Two tight sentences plus a short Args block with zero filler. The purpose line is front-loaded correctly before the parameter notes.

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?

An output schema exists, so return values needn't be described, and annotations carry the safety semantics. For a 2-parameter search tool the definition covers what's needed to call it, with only ordering/limit-cap details 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?

Schema description coverage is 0%, so the Args block does real work by defining query as a full or partial name and limit as the match count. However it omits the default (10) and any upper bound, leaving the two parameters only partially specified.

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?

States a specific verb and resource ('Find people') and enumerates the entity subtypes (actors, directors, writers, crew), which cleanly separates it from search_titles. It doesn't explicitly name the sibling it replaces, so it stops short of a 5.

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?

'Find people' plus 'Name, or part of one' implies a fuzzy/prefix lookup as opposed to the exact-record lookup implied by get_name, but the description never says when to prefer which. Usage is inferable from the sibling list rather than stated.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds workflow context (this yields the tt id consumed by other tools), which is genuinely useful, but says nothing about result ordering, default page size behavior, or matching semantics (fuzzy vs prefix).

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 front-loaded sentences establish purpose and routing before any parameter detail, and the args block is terse with no filler. Nothing could be cut without losing information.

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?

With an output schema present, return values need not be described, and for a simple 3-parameter read tool the entry-point framing plus per-param notes are close to sufficient. Missing edge detail (max limit, tie-breaking/ranking) keeps it just short of 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 coverage is 0%, so the description must carry the full parameter burden and largely does: it explains that query accepts a title or partial title, and supplies the title_type values ('any, movie or tv') that the schema does not enumerate. Only limit is left thin—'How many matches to return' gives no default or ceiling.

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?

States a specific verb and resource ('Find films, series and episodes by name'), which cleanly separates it from search_names and the get_title_* retrievers. It does not explicitly contrast with advanced_title_search, the closest sibling, so the differentiation is implied rather than stated.

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?

'Start here to get the tt id every other title tool needs' is a clear positive routing instruction that tells the agent this is the entry point in the tool chain. However, it names no exclusions and does not mention advanced_title_search for more complex filtering, so the when-not side is absent.

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