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

Annotations only declare readOnly/openWorld, so the description carries the real burden and does flag non-obvious behavior: validation and silent-fallback rules for certification, watch providers, monetization types, release type and region. It defers the specifics to the per-field descriptions rather than restating them, which is reasonable but means the agent must open the schema to learn what the fallback actually does.

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 scoping contrast is correctly front-loaded, but the middle portion is one enormous run-on enumeration of every filter family that largely duplicates a schema already at 100% coverage. The valuable parts (examples, sibling routing, fallback warning) are buried at the end of an overly long sentence.

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 33-parameter, all-optional query tool with an output schema and readOnly annotations, the description covers purpose, choosing against siblings, id-resolution helpers and fallback hazards — enough to call it correctly. Missing only a note on pagination/result limits (present in the schema) and any ranking caveat for sort_by defaults.

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 100%, so baseline is 3; the description adds cross-parameter semantics the schema does not state — notably that with_crew/with_cast/with_people must be combined with with_genres to answer 'a person's work in one genre'. The catalogue of filter families (include vs exclude, date-window vs original-release-date) also aids navigation of 33 parameters, though much of it echoes the field names.

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 precise verb+resource and an explicit contrast ('by structured filters instead of a title query'), which immediately separates it from search_movies. It also names the exact capability boundary against get_person_credits ('has no genre filter, so this combination is the right tool for that question, not that one').

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?

Gives two concrete use cases ('popular sci-fi from the 1990s with a TMDB vote average above 7 available on Netflix'; 'which of this director's films are animated') and explicitly routes the agent away from the wrong sibling. It also tells the agent how to prepare inputs via get_movie_genres, search_people, search_keywords, search_companies, search_watch_providers.

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?

Beyond the readOnly/openWorld annotations, the description discloses critical behavioral quirks: cast/crew/person params are validation errors rather than silent no-ops, TMDB's own /discover/tv silently ignores them, and certification/watch-provider filters have validation and silent-fallback rules. This is exactly the kind of surprising behavior an agent needs surfaced before calling the tool.

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 and front-loads the core filter scope before the important exclusion of cast/crew/person. Given 31 parameters and complex TMDB fallback behavior, the length is largely justified, though the single long paragraph and nested parentheticals make it less scannable than it could be.

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 31-parameter discovery tool with an output schema already present, the description covers the important selection guidance, exclusions, resolver tools, and silent-fallback warnings. No return-value explanation is needed because an output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines all 31 parameters in detail. The description still adds value by mapping natural-language intents to parameters, such as with_networks='HBO shows,' with_type='Miniseries,' with_status='Ended,' and the certification-country pairing, plus which resolver tools supply ids.

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 TV shows by structured filters,' then names the supported filter families and explicitly excludes cast/crew/person parameters. It directly distinguishes this from discover_movies and get_person_credits, so an agent can identify the tool without opening the schema.

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 routing guidance: use get_person_credits for shows featuring someone, use with_networks for 'HBO shows,' with_type='Miniseries' for limited series, with_status='Ended' to exclude ongoing shows, and certification='TV-Y7' for kid-appropriate TV. It also names resolver tools for ids, covering when to use this tool and its alternatives.

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 and openWorld, so the description's job is to add beyond that, and it does: it discloses that unresolved or episode ids return all result lists empty and are indistinguishable from unknown ids — a real failure mode an agent must plan around. It does not mention multiple-match behavior or ordering, which keeps it from a 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?

Three sentences, front-loaded with purpose then usage then caveat; each carries distinct information. The episode-id caveat is slightly long but is the highest-value content, so it earns its space.

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 described. With a single fully documented parameter, annotations covering safety, and the key semantic pitfall called out, an agent has everything needed to call this correctly and interpret empties.

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 100% and already documents the tt/nm pattern, so baseline is 3. The description still adds value by giving a concrete example id ('tt0133093') and clarifying that episode-level ids pass the format check but fail semantically — meaning the agent cannot rely on the pattern alone.

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: 'Resolve an IMDb id ... to TMDB entities', and specifies the returned entity types (movie, TV, person). This distinguishes it clearly from the sibling search_* tools, which take free-text queries rather than ids.

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?

Gives an explicit trigger ('Use when you only have an IMDb id and need the TMDB id for the other tools') and an explicit exclusion: IMDb episode-level 'tt' ids are not resolved. The alternative is implied by the sibling tool family and named indirectly as 'the other tools'.

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 and openWorldHint=true, so safety is covered; the description adds a real behavioral detail not in annotations: results include every part of the franchise and are returned in release order. It doesn't discuss failure modes (bad id) or localization interaction with the language parameter, keeping it short of a 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?

Two sentences, front-loaded with what the tool returns and followed by the prerequisite for calling it. No filler, no repetition of schema 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?

With an output schema present and annotations covering safety, the description only needs to add scope, ordering, and id provenance — and it does all three. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3; the description nevertheless adds meaning to `id` beyond 'TMDB numeric id' by explaining its two authoritative sources. The `language` parameter is left entirely to the schema, which documents it thoroughly.

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 (get) plus resource (movie collection/franchise) plus a scope guarantee (all parts in release order), with a concrete example ('The Dark Knight Collection'). An agent can distinguish it from search_collections or get_movie without opening the schema.

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 how to obtain the required id — from search_collections by franchise name, or from a movie's `collection` field in get_movie — which routes the agent to the correct preceding tool. It also implicitly excludes use of this tool for lookup-by-name.

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 only declare readOnlyHint/openWorldHint, but the description discloses far more: the certification fallback chain (region → US → any country) and how to detect it via certification_region, and the graceful-degradation contract where ratings becomes {found:false, reason} rather than failing on missing key/imdb_id/lookup error. It also flags that OMDb's ratings.rated is a separate value that can disagree with this tool's certification — a non-obvious behavior an agent would otherwise get wrong.

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 scope are front-loaded and every clause carries information (fallbacks, degradation, sibling routing). However, it is a single dense run-on paragraph with heavy nested parentheticals and partially restates the ratings enrichment twice, costing some readability.

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 spelled out, yet the description still covers the failure mode and fallback behavior an agent must anticipate. Combined with 100% param coverage and annotations, nothing needed to call this 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 coverage is 100%, so baseline would be 3, but the description adds real meaning: the non-obvious region fallback semantics and the certification_region output cue, plus the failure behavior tied to include_ratings. It adds less about `language` (the schema already documents localization and null-overview behavior) and repeats some of the include_ratings schema text, so it stops short of 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?

Opens with a specific verb+resource+key ('Get full details for one movie by TMDB id') and then enumerates the exact payload (overview, genres, runtime, budget/revenue, vote average, certification, links). It ends by naming the sibling it is not (get_movies, trimmed on purpose) and the sibling that supplies the id (search_movies), so an agent can distinguish it without opening either schema.

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?

Explicit routing is given in both directions: 'If you only need the headline info ... for one id or several — use get_movies instead' plus 'Get the id from search_movies.' Prerequisite (OMDB_API_KEY) and the opt-out (include_ratings=false) are stated, leaving nothing 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: results are truncated to the top 20 cast and a curated 'headline' crew list (director, writers, composer, DoP), so the agent knows this is not the full credit roll.

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 sentences, no filler, with the scope and the 20-item cap front-loaded before the id-sourcing instruction. Every clause carries 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?

Low-complexity single-parameter read tool with an output schema and read-only annotations; the description covers scope, truncation limits, and id provenance. Nothing further is needed to select and invoke it 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?

Schema coverage is 100% and the single parameter is already described as 'TMDB numeric id.' The description adds the practical step of sourcing that id from search_movies, which is value beyond the schema.

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 precise resource scope: top-billed cast (capped at 20) and headline crew roles for a movie. It is clearly distinguishable from sibling get_tv_credits (TV) and get_person_credits (by person) without opening a schema.

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 routes the agent to search_movies to obtain the required TMDB id, which is the main prerequisite. It does not state exclusions (e.g. use get_tv_credits for TV shows), so it stops short of full when/when-not guidance.

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 and openWorldHint=true. The description adds that the data is reference and rarely changes, providing useful behavioral context beyond 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 sentences, no wasted words, front-loaded with the core purpose and then a usage hint. Concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully explains what the tool does and how its output is used. With an output schema present and no parameters, the description is complete for the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description's job is minimal. The schema coverage is 100%, and the description adds no parameter info because none exist. Baseline for 0 params is 4.

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 the tool lists TMDB movie genres with numeric ids and names, using a specific verb and resource. It distinguishes from the sibling tool get_tv_genres by specifying 'movie' genres.

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 tells when to use the tool (to get genre ids) and how to use the output (feed into discover_movies' with_genres/without_genres). It also notes that the data rarely changes, implying caching. No explicit when-not-to-use, but context is sufficient.

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 and openWorldHint=true, so safety and scope are covered. The description adds genuinely useful behavioral context by disclosing what the ranking is actually based on (co-viewing/personalization) and warning that get_similar can surface 'tonally unrelated titles' — a quality trait an agent can act on. It doesn't discuss result volume or pagination, though the schema already handles the latter.

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 the operation and the key routing decision, and every sentence carries usable information. Slightly longer than needed — the parenthetical gloss 'what users who liked this also liked' and the editorial 'blunter heuristic' restate the same contrast twice.

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 the id-provenance plus sibling routing cover the calling decision. The only soft spot is that result volume ('up to 20 per page') lives solely in the param schema rather than the description, which is acceptable here.

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 100%, so the baseline is 3; the description earns above that by telling the agent where the required id comes from ('Get the id from search_movies'), which the schema's 'TMDB numeric id' does not say. Pagination is left to the schema, which documents it fully.

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 movies TMDB recommends for the given movie id') and immediately characterizes the underlying signal (co-viewing/personalization). It explicitly contrasts itself with the closest sibling, get_similar, so the agent can differentiate without opening either schema.

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?

Gives an explicit default recommendation ('Prefer this over get_similar as the default choice') and explains the condition that selects the alternative ('matches on shared genres/keywords, a blunter heuristic'). It also routes to search_movies for obtaining the required id, closing the prerequisite loop.

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 read-only/open-world, but the description adds substantial non-obvious behavior: region changes the actual movie set rather than re-sorting, an unrecognized code like 'ZZ' yields an empty page while 'XX' is a real pseudo-region, release_date is the country's date and may predate the window for re-releases, and ordering is popularity-based, not chronological.

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 purpose and alternatives, then the caveats; every clause carries information and nothing is filler. It is nonetheless a single dense paragraph whose nested parentheticals make it harder to scan than a short bulleted structure would.

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 four-parameter list tool with an output schema, everything an agent needs is present: mode selection, regional filtering semantics, window derivation and its approximate bounds, and result ordering. Nothing material is deferred to the schema or left to inference.

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 100%, so the baseline is 3; the description still adds real meaning for `region` (per-country result sets, invalid-code behavior, the 'XX' pseudo-region) that the schema's one-line 'ISO-3166-1 country code' does not convey. It also documents where the implicit date window comes from and that it is returned as `dates` {minimum, maximum} with approximate spans per list, though page/language are left entirely to the schema.

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 ('List movies in cinemas now ... or opening soon ... in one country') and binds each mode to a concrete parameter value. It explicitly distinguishes itself from get_trending and discover_movies, so an agent can route correctly without reading any schema.

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?

Gives the triggering user intents ('what's playing in theaters', 'what comes out next month') and names two alternatives with the condition that selects each: get_trending for popularity regardless of release, discover_movies for an arbitrary date range.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses graceful per-id failure with a `{id, found:false, reason}` shape, guarantees result ordering matches `ids`, and warns about a burst of OMDb calls and rate limits when include_ratings is set. This is exactly the behavioral context annotations cannot carry.

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 the resource and field list, then the sibling routing, then the failure semantics. Every sentence carries information, though the parenthetical enumerations make it denser than strictly necessary; it is long but not 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?

Complete for a 3-parameter read tool: an output schema exists so return structure need not be restated, and the description still documents the one non-obvious return case (per-id not-found entries). Sibling routing, defaults, and rate-limit caveats are all covered.

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 already 100%, so the baseline is 3, but the description adds value the schema does not: it explains that include_ratings enriches every card via OMDb, that its default is false here (unlike get_movie/get_tv), and that batches amplify OMDb traffic. `ids` and `language` are covered by the schema and not repeated, which is appropriate.

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 a compact card — title, year, genres, vote average, and (opt-in) ratings — for 1-20 movies by TMDB id') with explicit scope (1-20 ids, trimmed field set). It distinguishes itself from the sibling get_movie by naming the exact fields it excludes and what the sibling provides.

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?

Gives explicit when-to-use guidance including the non-obvious case ('use this for a single id too when you only need that headline info'), and names the alternative with its selection condition ('Call get_movie instead when you need the full details ... including region-specific certification'). No inference required.

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 and openWorldHint, so the safety profile is covered; the description adds valuable scope disclosure about what the response contains and deliberately omits. It does not mention language/localization behavior or the shape of the returned links, but the output schema and the language parameter description carry those 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?

Three short sentences with zero padding: what it returns first, the exclusion second, how to obtain the id third. Every clause carries information an agent needs to route the call.

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 single-record lookup with an output schema, full parameter documentation, and read-only annotations, the description supplies the remaining unknowns: field coverage, filmography exclusion, and id provenance. Nothing needed to call 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 100%, including a detailed explanation of the language override and TMDB fallback behavior, so the schema does the heavy lifting. The description only echoes 'by TMDB id' and adds no semantics beyond the schema — the expected baseline of 3.

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 full details for one person by TMDB id') and enumerates the returned fields (biography, birthday/deathday, department, links). It explicitly separates itself from get_person_credits, so the agent can distinguish the two without opening either schema.

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 excluded use case and the alternative ('Does not include filmography — use get_person_credits for that'), plus prerequisite routing for the id ('Get the id from search_people or a credits list'). Both the when and the when-not are stated outright.

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 carry readOnlyHint/openWorldHint, but the description adds substantial non-obvious behavior: default 25-per-side caps applied separately to cast and crew, self/talk-show guest credit exclusion, de-duplication of repeat titles, single-count for multiple crew jobs on one title, and the asymmetry that cast rows have vote_average while crew rows do not. The cameo caveat and the Tom Hanks verification are exactly the edge case an agent would otherwise get wrong.

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 the core behavior and exclusions, then parameters, then routing guidance — good ordering. It is long and a couple of parentheticals (the live Tom Hanks verification, the 50+ directing aside) are illustrative rather than strictly load-bearing, but almost every sentence conveys a rule an agent needs.

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 an output schema and full annotation coverage, the description still supplies everything missing: ordering, cap semantics, exclusion policy, what rating fields appear where, and cross-tool routing for the genre case the tool cannot handle. Nothing an agent needs to call this correctly and interpret the result is 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 coverage is 100%, so the baseline would be 3, but the description adds real semantics the schema cannot: department is framed as the reliable way to get a complete single-department filmography because other departments compete for the same cap, and limit should be raised specifically when the department filter still under-returns for prolific people. That is decision-relevant, not paraphrase.

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 ('List the movies and TV shows a person is known for') and immediately distinguishes scope from siblings by noting it covers both cast and crew, ordered by popularity. An agent can tell this apart from get_movie_credits/get_tv_credits and discover_movies without opening any schema.

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 names the trigger ('what has this actor/director been in'), names the exclusion ('no genre filter'), and routes to the correct alternative per case: discover_movies with with_cast/with_crew for movie genres, and a manual TV workaround because discover_tv can't filter by person. It also names search_people as the source of the id.

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 only say read-only and open-world; the description adds the real behavioral load: the API key requirement, that a no-match returns `{found:false, reason}` rather than an error, that the title path silently resolves to one arbitrary OMDb entry with no runner-up and no validation, and a concrete verified Halloween example showing a wrong-work risk. It even prescribes the mitigation (read back returned imdb_id/title/year).

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 what it returns, then routing, then failure and ambiguity caveats — a sensible order with no filler sentences. It is dense and slightly overlong as a single paragraph, and the Halloween anecdote plus the repeated 'always read back / pass year' advice partly restate each other.

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 spelled out, yet the description still covers the one non-obvious return case (`found:false`) and the awards-summary shape. Combined with the annotations and schema, an agent has everything needed to call it correctly and interpret a suspicious result.

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 100% and the schema itself already documents precedence and the type/year disambiguation with examples, so the description is not carrying the full burden. It still adds operational guidance beyond the schema: 'imdb_id preferred', 'always pass year (and type) whenever you know them', and that type/ year only matter on the title path.

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 plus the exact resources it returns: IMDb/Rotten Tomatoes/Metacritic ratings, an awards summary (explicitly free-text, whole-title or single-episode, never a person), and OMDb's `rated` age rating. It also names its data source (OMDb) and its two lookup keys, so an agent can immediately distinguish it from get_movie/get_tv and find_by_imdb_id.

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?

Gives explicit routing rules: prefer get_movie/get_tv when holding a TMDB id because they already include this data, and prefer search_movies/search_tv → get_movie/get_tv for title-only queries because that path validates against TMDB's year. It also states the precondition (OMDB_API_KEY) and the argument rule (one of imdb_id or title required; pass year/type when known).

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 and openWorldHint, so the safety profile is covered. The description does add real value beyond that: the rating can be null, and review text is clipped to ~1500 characters — a non-obvious truncation behavior worth knowing. It stops short of describing pagination or total-count behavior, so a 3 is fair.

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 action and result, and no filler. The nested em-dash clauses make the seating of the rating caveats slightly hard to parse on first read, but every clause carries needed 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?

Output schema exists, so return values needn't be explained, and all three parameters are covered via schema plus the id-source hint. Missing only pagination/total-results guidance for paging through reviews, which matters for a tool capped at page 500.

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 100%, so the baseline is 3, but the description goes further by explaining where id comes from and by characterizing media_type semantics ('movie or TV show'). The only gap is the page parameter, which the schema already documents.

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+resource ('Get user reviews for a movie or TV show') and then explicitly disambiguates the returned rating from aggregate vote_average and from IMDb/RT/Metacritic scores, which is exactly the confusion a sibling like get_ratings would create.

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 tells the agent to obtain the id from search_movies/search_tv, a concrete prerequisite no other wording provides. It lacks an explicit 'do not use this for aggregate ratings — use get_ratings' routing statement, so it falls short of the 5 bar.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful, non-annotation context: the heuristic is noisy, results come in TMDB rank order, 20 per page, and the list can run into the whole catalog. However, some of this overlaps the schema's pagination text, so the added value is real but not exceptional.

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 the core definition and the sibling comparison before the caveats. Dense but largely earning its place; the 'verified live' anecdote is illustrative but slightly verbose for a definition.

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 explained, and the description still covers quality expectations, ordering, pagination limits, and id acquisition. Nothing an agent needs to call this 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 coverage is 100%, so baseline would be 3, but the description adds value the schema lacks: it sources the id from search_movies/search_tv and frames page usage via the 'first page or two' caveat. The media_type/page semantics are otherwise left to the schema.

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 titles TMDB considers similar), the underlying basis (shared genres and keywords), and explicitly contrasts with get_movie_recommendations/get_tv_recommendations. An agent can distinguish this from its nearest siblings without inspecting either schema.

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?

Gives an explicit routing rule: try recommendations first for thematically closer picks, use this when you specifically want genre/keyword-adjacent titles. Also tells the agent how to obtain the required id (search_movies/search_tv), covering the only real 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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: each result row carries its own media_type, which can differ from the requested filter when 'all' is used — an agent would otherwise likely assume homogeneous results. It does not mention rate limits or auth, but for a public read endpoint that is minor.

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 sentences, front-loaded with the core purpose, then parameters, then the result-routing caveat. No restatement of the title and 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?

For a three-optional-parameter read tool with full schema descriptions, an output schema, and annotated safety, nothing essential is missing. Pagination limits and return shape are handled by the structured fields, so the description correctly spends its budget on the cross-row media_type caveat instead.

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 100%, so the baseline is 3; the description still earns credit by mapping the enums to plain meanings ('day vs this week') and by calling out the 'all' default's consequence for result routing. The page parameter is left entirely to the schema, which is acceptable given its thorough description there.

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 what's trending on TMDB') and names the two dimensions that shape the result (media_type, time_window). 'Trending' is inherently distinguishable from the search_* siblings, though the description never explicitly names them as alternatives, so it stops 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?

Gives a clear use context ('Good for what's popular right now') and a downstream routing instruction ('check the per-row media_type to route to the right get_* tool'). It omits any when-not guidance — e.g., that search_movies/discover_movies serve lookup or filter queries rather than popularity ranking.

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?

With only readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: certification fallback behavior, the separate OMDb ratings.rated field, ratings degradation to {found:false, reason} instead of failure, the extra request for expand_episodes, and the episode caps and trimming order. No contradiction with 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 front-loaded and all major information is present, but it is a very dense single paragraph with nested asides and semicolon-heavy clauses. It is appropriately sized for a complex tool, though it could be easier to scan if structured more cleanly.

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 a complex read tool with five parameters, an output schema, and minimal annotations, the description is complete: it covers routing, fallback behavior, enrichment behavior, degradation behavior, and expansion limits. No critical invocation detail appears 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 already 100%, the description adds important cross-parameter meaning: region fallback rules and certification_region, include_ratings degradation and API-key dependency, and expand_episodes budget/order behavior beyond the schema text. These details materially help correct invocation.

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 — full details for one TV show by TMDB id — and enumerates the payload included. It also explicitly distinguishes this tool from get_tv_shows and get_tv_season, so an agent can identify its role without opening the schema.

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 routing: use get_tv_shows for headline info across one or several ids, use get_tv_season for one season's full detail, and use expand_episodes instead of repeated get_tv_season calls when all episodes are needed. It also says where to get the id via search_tv.

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 safety (readOnlyHint, openWorldHint), and the description adds substantial non-annotation behavior: result caps (20 cast, 5 per crew job), ranking by episode_count, and the semantic that the first Director is the one who directed most episodes. That is exactly the kind of context annotations cannot express.

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 the core purpose and no filler sentences, but the payload is one long run-on sentence with nested clauses that an agent must parse in pieces. Slightly shorter, chunked phrasing would improve scanability.

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 tool with an output schema and full annotation coverage, nothing an agent needs is missing: it knows what comes back, how it is ordered, how it is capped, and where to get the input and the alternatives.

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 100% and the `id` description already says TMDB numeric id, so the baseline is 3; the description adds marginal value by telling the agent to obtain the id via search_tv, closing the provenance gap. It does not add format constraints beyond the schema.

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 (List) and resource (a TV show's cast and key crew across its whole run), plus the identifier domain (TMDB id). It is clearly distinct from get_movie_credits and from get_tv, so an agent can select it without opening the schema.

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 routes the agent: creators live in get_tv's `created_by`, a single episode's director/writer is get_tv_episode, and the id comes from search_tv. Both exclusion and prerequisite are named.

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 and openWorldHint, so the safety profile is known. The description adds useful behavior beyond annotations: it notes no OMDb call is made, lists guest stars capped at 15, and explains the imdb_id handoff to get_ratings. It does not cover error cases or rate limits, but those are minor given the output schema and openWorldHint.

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 front-loaded with the core purpose and every clause (rating clarification, imdb_id handoff, show id source) earns its place for disambiguation. However, it is a dense, parenthetical-heavy run-on that would be easier to parse as separate sentences or bullets.

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 a simple 3-parameter read-only tool with an output schema and annotations, the description covers everything an agent needs: what it returns, how to obtain the show id, and how to get per-episode IMDb ratings via get_ratings. No critical gaps remain.

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 100%, so the baseline is 3. The description adds a useful pointer ('Get the show id from search_tv') and reiterates the required id/season/episode combination, but does not expand on the semantics of season_number (0 = specials) or episode_number beyond what the schema already states.

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 episode of a TV show') and enumerates returned fields, then explicitly distinguishes itself from get_movie/get_tv (whole-show ratings only) and get_ratings (per-episode IMDb via imdb_id). An agent can identify the exact operation and scope without opening the schema.

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?

Provides explicit routing: 'pass that id to get_ratings for this one episode's IMDb rating' and 'Get the show id from search_tv.' It also clarifies that get_movie/get_tv ratings are whole-show only, which implicitly tells the agent when not to use this tool for aggregate 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 readOnlyHint and openWorldHint. The description adds that it is reference data which rarely changes, providing useful stability context beyond 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 concise sentences with front-loaded purpose and a usage hint. No wasted words; every sentence adds value.

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 no parameters and an output schema (referenced in context), the description explains the output content (genre ids and names) and how to use them, making it complete for a reference data retrieval 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?

No parameters exist, so schema coverage is 100%. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4.

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?

Clearly states it lists TV genres with ids and names, and notes it is reference data. The sibling get_movie_genres is similar but the tool name and description provide enough specificity for differentiation.

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 instructs to feed ids into discover_tv's with_genres/without_genres, providing clear usage context. Does not explicitly mention when not to use, but the directive is strong enough.

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 and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context the annotations don't: the recommendation basis is co-viewing/personalization data, which tells the agent how results are ordered and how much to trust them. Pagination and return shape are left to the schema and output schema.

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 dense sentences, front-loaded with purpose, followed by the tool-selection rule and the id prerequisite. No filler; the comparative clause about get_similar earns its length by directly changing tool selection behavior.

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 described, and both parameters are fully documented in the schema. Combined with the sibling routing and the id-sourcing hint, nothing an agent needs to invoke this 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 100%, so the schema already documents both id (TMDB numeric id) and page (pagination, max 500). The description only adds provenance for the id ("Get the id from search_tv"), which is a useful but minor supplement — baseline 3 applies.

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 TV shows TMDB recommends for the given show id") and immediately disambiguates from the sibling tool get_similar. The agent can distinguish this from get_similar without opening either schema.

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 prescribes default choice: "Prefer this over get_similar as the default choice", then explains why the alternative differs ("matches on shared genres/keywords, a blunter heuristic that can surface tonally unrelated titles"). It also gives the prerequisite for the id parameter ("Get the id from search_tv").

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?

Beyond the readOnly/openWorld annotations, the description discloses important behavior: no OMDb call is made, TMDB's season payload has no per-episode IMDb ids, results are capped at 50 episodes while episode_count reports the true total, and season 0 can contain hundreds of specials. These are exactly the traits an agent needs before invoking it.

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 key purpose and constraints are front-loaded, and every sentence carries useful guidance. However, the long nested parenthetical about vote_average, OMDb, and IMDb ids is dense and could be split or tightened for readability.

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 available, the description does not need to explain return values, and it already covers the important edge cases: the 50-episode cap, season 0 specials, and when to use sibling tools instead. Nothing essential is missing for correct invocation.

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 100% and both parameters are already documented, so the baseline is 3. The description adds real meaning by explaining where the id comes from (search_tv) and warning that season_number 0 means specials that may be unusually large.

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: get one season of a TV show by show id and season number, and lists exactly what comes back (overview, episode list, air dates, runtimes, vote averages). It clearly distinguishes itself from get_tv, get_tv_episode, and search_tv.

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 routing rules: use get_tv with expand_episodes=true for every season at once, call get_tv_episode when you need a per-episode imdb_id, and get the show id from search_tv. It also flags the season 0 specials case as a usage caveat.

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 only declare readOnlyHint/openWorldHint; the description adds genuinely non-obvious behavior — trimmed payload contents, opt-in ratings that cost one OMDb lookup per id with its own rate limit, a default that differs from get_movie/get_tv, and partial-failure semantics where a bad id returns `{id, found:false, reason}` in input order rather than failing the batch.

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 the payload shape right after the verb, and every sentence carries operational information. The nested parenthetical clauses and the self-correcting 'not just for checking many at once' aside make it denser than it needs to be.

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 prose, yet the description still spells out the per-entry error shape and ordering. Combined with the exclusions list, the batch cap, and the ratings cost model, an agent has everything needed to call this correctly instead of get_tv.

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 100%, so a 3 is the baseline; the description goes beyond it by explaining that `include_ratings` is opt-in and defaults to false here (unlike sibling tools) and that each id incurs a lookup. It also reinforces the 1-20 batch bound and the ordering guarantee for `ids`, though it adds nothing about the `language` parameter beyond what the schema documents.

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 ('Get a compact card'), the exact fields returned, the batch limit (1-20), and the keying by TMDB id. It is immediately distinguishable from get_tv and get_tv_season because it names what is deliberately excluded from the payload.

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 prescribes both directions: use get_tv 'when you need the full details for a title (including region-specific certification)', and use this tool even for a single id when only headline info is needed. It also names the motivating use case (spotting miniseries via low episode count).

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 and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: YouTube entries include watch URLs and results span the configured language, English, original language, and untagged entries, with each entry's language field indicating its language. It stops short of describing ordering or pagination, but the main return semantics are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with its primary purpose and contains no filler sentences. The language-handling sentence is dense but every clause carries useful information for interpreting the returned videos.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter lookup with an output schema and annotations, the description covers the key missing context: where to obtain the id, what kind of videos are returned, how language selection works, and how to interpret each entry's language field. Nothing essential for correct invocation is 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 100%, so both parameters are already documented in the input schema. The description adds only provenance for the id via search_movies/search_tv and notes that no language parameter exists; it does not need to explain media_type or id syntax beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'List trailers, teasers and clips for a movie or TV show.' It also distinguishes the YouTube return detail and tells the agent where to get the required id, making the tool easy to separate from sibling detail endpoints like get_movie or get_tv.

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 a clear prerequisite by saying 'Get the id from search_movies/search_tv,' which helps an agent route correctly. It also states there is no per-call language override, but it does not explicitly name alternatives or when-not-to-use conditions beyond the id source.

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 only cover readOnly and openWorld, so the description carries the rest: it discloses the return shape (provider names per access type per country) and the failure mode (`available:false` plus `available_regions`), which is genuinely actionable behavior an agent could not infer from annotations alone. It does not mention rate limits, caching, or data freshness, which is the only remaining gap.

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 tight sentences, front-loaded with the core purpose, then return/fallback behavior, then the id prerequisite. No filler or restated name/title.

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 fully spelled out, yet the description still flags the one non-obvious return case (available:false with available_regions). Combined with full param coverage and the id-sourcing hint, an agent has everything needed to call it 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?

Schema coverage is 100%, so baseline is 3. The description still adds value by tying `region` to country-scoped results and by establishing where `id` must come from (search_movies/search_tv), which is workflow semantics not present in the schema.

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 where a movie or TV show can be streamed, rented or bought in a given country', plus the data provenance (JustWatch via TMDB). It is clearly distinguishable from data-retrieval siblings like get_movie or search_watch_providers, though it never names the closest sibling (search_watch_providers) 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?

Gives the concrete prerequisite and upstream alternative: 'Get the id from search_movies/search_tv', which tells the agent the required call order. It also explains what to do when the result is empty (retry with available_regions). No explicit when-not-to-use or sibling exclusion 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 readOnlyHint and openWorldHint, so the safety profile is covered; the description adds real behavioral context beyond that — multiple matches are possible, TV queries return zero results, and results are localized by `language`. It stops short of describing pagination limits, but the schema covers those.

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 the core purpose and tightly written with no filler. It is dense — one long multi-clause paragraph with several parenthetical examples — which costs a bit of scannability but every clause carries 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?

Covers selection criteria, alternatives, the movies-only constraint, ambiguity handling, and localization behavior; an output schema exists, so the return-value detail given is a bonus rather than a requirement. Nothing an agent needs to call 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 coverage is 100%, so the baseline would be 3; the description adds genuine meaning by showing how `language` alters the `name` field ('de-DE' → 'Harry Potter Filmreihe') and by enumerating the returned row fields. `query` is clarified as a franchise name, though `page` is left entirely to the schema.

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 precise verb and resource: resolve a franchise name to a TMDB collection id, and defines what a collection is. It explicitly separates itself from get_collection (which takes the id) and get_movie (whose `collection` field carries the same id).

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?

Gives an explicit when-to-use rule ('Use this when you only have the franchise name'), names the alternative path when you already have a movie, and states a hard exclusion ('Movies only... a TV series name finds nothing'). It even handles the ambiguous-name case with a disambiguation 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: company names are not unique, multiple TMDB rows may share a name, and origin_country plus logo_url are needed to distinguish them. It does not describe pagination behavior, but the schema covers 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?

The description is three tight sentences with no wasted text. The core purpose is front-loaded, followed by the downstream usage and the disambiguation warning in a logical order.

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 read-only annotations, complete parameter schema, and output schema, the description is complete enough for correct selection and invocation. It covers the purpose, the downstream integration, and the key real-world ambiguity an agent must handle when resolving company names.

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 100%, so both query and page are already documented in the schema. The description adds examples for query ('A24', 'Pixar') and clarifies the disambiguation fields to check, but it does not add format or pagination semantics beyond the schema. Baseline 3 is appropriate.

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: resolve a production company name to its TMDB numeric id. It gives examples ('A24', 'Pixar') and clearly distinguishes the tool's output from sibling search tools by explaining that the id is for use with discover_movies/discover_tv via with_companies.

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 explicitly explains the downstream use: feed the returned id into discover_movies or discover_tv via with_companies. It also gives a clear warning about non-unique company names and how to disambiguate using origin_country and logo_url. It does not explicitly contrast with other sibling search tools, but the intended usage context is clear.

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 provide readOnlyHint and openWorldHint. The description adds the purpose (resolving) and downstream usage, disclosing that it returns ids for discovery. No contradictions.

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 sentences, each earning its place: purpose with examples, then usage instruction. No fluff.

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?

Covers purpose, usage, and examples. Does not mention pagination or output format, but schema and output schema handle those. Sufficient for a simple lookup 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 coverage is 100%, so baseline is 3. Description provides example inputs ('time travel') adding marginal value beyond 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?

The description clearly states the tool resolves keyword names to TMDB keyword ids, with examples. It distinguishes from sibling tools (e.g., search_movies) by focusing on keywords.

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 tells when to use the output (feed into discover_movies/discover_tv with with/without_keywords). Does not explicitly state when not to use, but context makes it clear.

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?

Beyond the readOnly/openWorld annotations, it discloses return characteristics (compact summaries, required TMDB id, pagination info) and a non-obvious live-verified behavior of `region` that could otherwise mislead an agent. This is meaningful behavioral context, not repetition of structured fields.

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 front-loaded with the core purpose and return value, then moves into sibling routing and a high-value caveat about `region`. Every sentence carries actionable information for tool selection or invocation.

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 full schema, existing output schema, and annotations, the description supplies the remaining routing and behavioral context an agent needs. It covers the main trap (`region` semantics), the sibling alternative, and the downstream use of returned ids.

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 100%, so parameter documentation is already strong. The description still adds important meaning for `region`, explaining that it only selects which country's release_date is displayed rather than filtering or reordering results, which goes beyond the schema's basic ISO-code description.

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 ('Search TMDB movies by title') and explains what the tool returns: compact summaries with the TMDB id needed by related movie tools. It also distinguishes itself from the sibling search_multi, so an agent can route correctly without opening schemas.

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 routing guidance: use this over search_multi when the result is known to be a movie. It also clarifies that `region` does not filter or reorder matches and points to get_watch_providers for actual region-based availability.

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 and openWorldHint, so the safety profile is covered. The description contributes beyond that by disclosing the shape of results — every record carries media_type with its three possible values — which lets the agent plan routing. It does not discuss pagination limits or adult-content defaults, but those are handled in the schema.

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 sentences, front-loaded with the capability, then the result contract, then the alternative routing. No filler or restated field names.

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 enumerate return fields, and it correctly highlights only the one result property an agent must reason about (media_type). Nothing critical is missing for correct invocation, though it says nothing about result volume or paging expectations at the description level.

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 100%, including paging limits, language fallback behavior, and the adult flag default, so the schema carries parameter meaning. The description adds only the implication that the query is type-agnostic; baseline 3 is appropriate.

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 set ('Search movies, TV shows and people in one call') and explicitly separates this tool from search_movies/search_tv/search_people by scope. An agent can distinguish it from every sibling without opening a schema.

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 states both the selection condition ('when the user's query could be any of these') and the alternative ('if you already know the type, search_movies/search_tv/search_people are more precise'). Both branches of the decision are given explicitly.

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 and openWorldHint, so safety and external-data traits are covered; the description adds real value by describing the return payload shape (id + best-known titles) and the get_person workflow dependency. It doesn't mention pagination or the adult-filter default, but the schema documents both, so the gap is minor.

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 doing three jobs: what it searches, what it returns, and when to prefer it over search_multi. Front-loaded with the core action and free of 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 an output schema present and full parameter documentation, the description need only cover routing and the downstream dependency, and it does exactly that. An agent has everything required to pick this tool and call it 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?

Schema description coverage is 100%, so query, page, language, and include_adult are all documented in structured data. The description only implies that query is a person name and adds nothing about page or language behavior, so the baseline 3 is appropriate.

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 (search TMDB people), scopes it to actors/directors/crew, and describes the payload (TMDB id plus top 5 known_for titles). It also names search_multi as the contrasting sibling, so the tool is distinguishable without opening the schema.

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 routes the agent: use this over search_multi when the target is known to be a person. That names both the alternative and the condition that selects it, and it also flags the downstream tool (get_person) that consumes the returned id.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses that results are compact and that the returned TMDB id is the key required by get_tv and sibling TV tools — valuable chaining context. It does not add anything about rate limits, pagination limits, or empty-result behavior, though those are partly covered by the page schema description.

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 sentences, no waste, with the core purpose and the return-value/chaining fact front-loaded before the routing note. Every clause carries 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?

An output schema exists and annotations cover the safety profile, so the description only needs to convey purpose, routing, and the ID-chaining detail — all present. Nothing an agent needs to call 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 100%, so query, year, page, language, and include_adult are already fully documented in the schema (including the hard first-air-year note and the discover_tv redirect). The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 (search TMDB TV shows by name) and adds a return-shape summary (compact summaries with the TMDB id). It also names the sibling it replaces (search_multi), so an agent can distinguish it without opening a schema.

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?

"Use this over search_multi when you already know the result is a TV show" gives an explicit alternative-plus-condition rule. It does not explicitly address other adjacent siblings like search_movies or search_people, but the routing intent is clear.

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?

Beyond the readOnly/openWorld annotations, it discloses that provider catalogs are large (269+ for the US), that ids and availability are region-dependent, and that an unscoped search returns the global list which may contain ids invalid for the caller's region. Return format and pagination are not described, but an output schema exists, so that gap is minor.

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-loads the core name-to-id mapping in the first sentence, then the downstream usage and the region caveat in order of importance. The middle clause about TMDB lacking name lookup is slightly redundant with the opening but still justifies the 'don't guess an id' warning in the same sentence.

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 4-param search tool with an output schema and safety annotations already present, the description covers the purpose, the downstream consumer, the region consistency requirement, and the failure mode of guessing ids. An agent has everything needed to invoke it correctly and use the result.

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 100%, so baseline is 3, but the description adds cross-tool meaning the schema cannot: watch_region must match the region later passed to discover_movies/discover_tv, and media_type filters availability while the id stays constant. It reinforces the schema's example-style guidance for query rather than merely restating it.

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+resource: resolving a service name ('Netflix', 'Disney Plus') to a TMDB numeric provider id. It also implicitly distinguishes itself from siblings by framing the id as input to discover_movies/discover_tv rather than as a per-title lookup like get_watch_providers.

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 says what to do with the result (feed into discover_movies/discover_tv's with_watch_providers, keeping watch_region consistent), and explicitly warns not to guess ids since TMDB has no name-based lookup. It also states the consequence of omitting watch_region versus supplying it, giving the caller a clear conditional.

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