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

With readOnlyHint=true, the safety profile is already covered, so the description adds value by flagging live-tested quirks: region has 'minor effect only', and certification/with_watch_providers have 'validation and silent-fallback rules'. It does not fully spell out those rules at the top level, but it points to the detailed field descriptions, which is reasonable navigation rather than concealment.

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 tool's core purpose, then organizes caveats, usage examples, and ID-resolution guidance in a logical flow. Each sentence earns its place; the repeated 'see its own description' pattern avoids duplicating long schema content while still highlighting important behavioral notes.

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

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

For a 26-parameter tool with an output schema and readOnly/openWorld annotations, the description covers purpose, typical use cases, exclusions, key caveats, and ID-resolution dependencies. The output schema removes the need to describe return values, and the field-level descriptions handle individual parameter details, making the top-level description appropriately complete.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful combination guidance beyond individual parameter entries: e.g., using with_crew/with_cast/with_people together with with_genres to answer genre-filtered person queries. It also summarizes the filter categories and flags the region parameter as having only a minor effect, which helps the agent reason about parameter choice.

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 movies by structured filters instead of a title query', which clearly distinguishes this from search_movies and other siblings. It enumerates the exact filter dimensions and explicitly contrasts with get_person_credits for genre-filtered person queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete example queries ('popular sci-fi from the 1990s rated above 7 available on Netflix') and explicitly names an alternative tool (get_person_credits) that lacks genre filtering, stating why discover_movies is the right choice. It also tells the agent to resolve IDs via sibling search tools, providing clear when-to-use 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 declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context: calling with cast/crew params causes a validation error (not silent no-op), certification and with_watch_providers have silent-fallback rules, and certification has no fallback for missing country data. These are important non-obvious behaviors not captured by 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 long but every sentence earns its place. It is front-loaded with the core purpose, then logically flows into exclusions, examples, and resolver references. The structure is purposeful, not padded, and delivers dense, actionable 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?

Given 25 parameters, an output schema, and complete annotations, the description covers all critical aspects: use cases, exclusions, error behavior, fallback rules, examples, and id resolution. It is more than sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the absence of cast/crew parameters as an intentional design choice with validation-error behavior, and by highlighting differences from discover_movies' parameter vocabulary. However, most parameter-specific semantics are already in the schema, so this is a modest increment.

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's purpose: 'Find TV shows by structured filters'. It explicitly distinguishes itself from siblings by naming the TV counterpart relationship to discover_movies and by explaining it does NOT handle cast/crew/person, directing users to get_person_credits instead. This is a specific verb+resource+scope with clear sibling 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?

The description provides explicit when-to-use and when-not-to-use guidance, including 'to find TV shows featuring someone, call get_person_credits instead'. It offers concrete example use cases (with_networks for 'HBO shows', with_type='Miniseries', with_status='Ended', certification for kids' content) and points to id-resolution tools. This goes far beyond implied usage.

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 vital behavioral context: empty results are ambiguous (unknown id vs. episode id), which is not evident from annotations or 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?

Concise, front-loaded description of 3-4 sentences. No unnecessary words; every sentence adds value (purpose, usage, limitation).

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 tool with one parameter, good annotations, and an output schema, the description covers the key behavioral nuance (episode handling) completely.

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?

Only one parameter with 100% schema coverage. The description reinforces the parameter's purpose and provides an example, adding minor value beyond the schema's pattern and 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 clearly states the tool resolves an IMDb id to TMDB entities (movie, TV, person), with an example input. It distinguishes itself from siblings by specifying its unique role when only an IMDb id is available.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (when only IMDb id and need TMDB id) and provides a critical limitation: does not resolve episode IDs, with a real example. This helps the agent avoid misuse.

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 behavioral context by stating it returns all parts in release order, which is not covered by 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 filler. The purpose and usage hint are front-loaded and 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?

With an output schema present and only two parameters, the description covers all needed context: what it returns, how to get the ID, and the ordering. No gaps.

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%, but the description adds meaning beyond the schema by explaining that the 'id' parameter is the collection ID obtainable from get_movie's 'collection' field, aiding correct usage.

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 gets a movie collection/franchise and all its parts in release order, with an example (The Dark Knight Collection). It distinguishes from siblings by specifying that the collection ID comes from get_movie's 'collection' field.

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 clear guidance: get the collection id from get_movie's 'collection' field. However, it does not explicitly state when not to use this tool or name alternatives, leaving some ambiguity.

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 and openWorldHint annotations, the description discloses several important behaviors: certification fallback logic (region → US → any country), the degradation of 'ratings' to {found:false, reason} when OMDb is unavailable rather than failing, and the distinct nature of OMDb's ratings.rated vs the tool's own certification. This is rich, honest disclosure that anticipates real-world edge cases.

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

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

The description is long but densely packed with necessary information, and it is well-structured: main purpose, then certification details, then ratings/fallback, then guidance to alternatives. Every sentence earns its place; however, it could be slightly tightened without losing critical context. Still, the complexity of the tool justifies the length, so it's 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?

Given the tool's complexity (multiple fields, fallback behaviors, optional enrichment), the description is exceptionally complete. It covers prerequisites (OMDB_API_KEY), failure modes (degraded ratings), and the source of the ID, leaving no obvious gaps for the agent. The presence of an output schema reduces the need to explain return format, but the description already covers key behavior.

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

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

Although schema coverage is 100%, the description adds significant semantic depth: it explains how region affects certification fallback, what language does (localizes titles and genre names), and the full implications of include_ratings (including the requirement for OMDB_API_KEY and the benefit of skipping). These details go beyond the schema's bare descriptions and help the agent make informed decisions.

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 explicitly states it retrieves full details for one movie by TMDB ID, listing many fields (overview, genres, runtime, etc.). It clearly differentiates from sibling get_movies (plural) by noting the trimmed-down headline-only nature, and from get_tv by focusing on movies. The verb 'Get' and resource 'movie details' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'If you only need the headline info... use get_movies instead' and 'Get the id from search_movies.' This not only helps select the tool but also directs to the correct source for the required ID. It also explains the optional include_ratings flag and when to set it to false, providing clear alternative paths within the tool.

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 readOnlyHint and openWorldHint annotations, description specifies the limited scope (up to 20 cast, headline crew) and example crew roles.

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 efficient sentences with no wasted words, front-loading the purpose and necessary details.

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-parameter tool with high schema coverage and existing output schema, description fully covers purpose, input, and data source.

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%, but description adds extra context by mentioning where to obtain the TMDB id (search_movies), adding value beyond 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?

Description clearly states it lists top-billed cast (up to 20) and headline crew by TMDB id, distinguishing it from sibling tools like get_movie or search_movies.

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 get the id from search_movies, providing clear context for when to use this tool.

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. The description adds behavioral context about the recommendation basis and comparison to get_similar, without contradicting the annotations. It does not discuss rate limits or pagination details, but that is acceptable given the annotations.

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

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

The description is three sentences, each serving a distinct purpose: explaining the tool, giving usage preference, and providing input source. It is front-loaded and contains no unnecessary words.

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 presence of an output schema, the tool definition is complete. It covers purpose, usage guidelines, input source, and differentiation from siblings. No additional details are needed for effective 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%, so the baseline is 3. The description implicitly references the required parameter (movie id) but does not add new meaning beyond the schema. The page parameter is not mentioned, but the schema describes it adequately.

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 retrieves TMDB recommendations for a given movie ID, explains the basis (co-viewing/personalization data), and explicitly distinguishes it from the sibling tool get_similar. It also directs users to obtain the ID from search_movies.

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 advises to prefer this over get_similar as the default choice and explains the difference in recommendation logic. Also provides guidance on getting the movie ID from search_movies.

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?

Discloses that bad IDs do not fail the call, returning {id, found:false, reason} in order. Mentions OMDb rate limits for include_ratings. Annotations already declare readOnlyHint and openWorldHint; description adds complementary behavioral context without contradiction.

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

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

Well-structured and front-loaded with purpose, but slightly verbose in the middle listing exclusions and use cases. Each sentence earns its place, though could tighten some phrasing.

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 3 parameters, output schema present, and annotations, the description is complete. Covers error behavior, rate limits, scope of data, and contrasts with sibling tool. No gaps.

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%, but description adds meaningful context: IDs sourced from search/discover/etc., language override localization, include_ratings defaults to false and explains OMDb burst calls. Provides value beyond 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?

The description clearly states it fetches compact movie cards for 1-20 TMDB IDs, explicitly listing included fields (title, year, genres, vote average, ratings) and contrasting with get_movie for full details. It distinguishes from siblings effectively.

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 when-to-use (single or multiple IDs for headline info) and when-not-to-use (call get_movie for full details including region-specific certification). Also explains handling of bad IDs.

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 description's disclosure is minimal. It adds context about returned fields but does not mention rate limits, authorization needs, or error behavior. The description is adequate given the annotations.

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

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

The description is three sentences, each providing essential information without redundancy. It front-loads the purpose and follows with critical exclusions and id source, making it efficient for an agent to parse.

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 presence of an output schema and clear annotations, the description provides sufficient context. It lists the major return fields and clarifies what is not included. It does not address edge cases or error handling, but these are not critical for typical use.

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 description adds value by explaining the id's origin and the language parameter's purpose (localization). However, it does not elaborate beyond what the schema already provides for each parameter.

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

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

The description clearly states the action (get full details), the resource (one person by TMDB id), and lists specific returned fields. It explicitly distinguishes from the sibling tool get_person_credits by noting what is not included (filmography).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool (for person details) and when to use the alternative (get_person_credits for filmography). It also tells where to obtain the required id (from search_people or a credits list).

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 declare readOnlyHint=true and openWorldHint=true. Description adds details: default cap of 25, exclusion of talk-show appearances and duplicates, deduplication of multiple crew jobs, cast entries include vote_average but crew do not, and behavior of department and limit parameters for prolific people.

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?

Long but every sentence adds valuable information. Front-loaded with main purpose. Could be slightly more concise, but efficient given the complexity.

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?

Completeness is high: covers purpose, parameters, limitations, alternatives, and output details (e.g., cast vs crew attributes). Output schema exists but description still provides behavioral context.

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% but description adds significant value beyond schema: explains why raise limit for prolific people, why use department to avoid crowding, that department only affects crew credits, and that without department, other departments compete for cap.

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 the tool lists movies and TV shows a person is known for, with cast and crew roles, most popular first, capped at 25 each. Differentiates from sibling tools like search_people, get_movie_credits, and discover_movies by specifying its focus on a person's combined filmography and exclusion of guest appearances.

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: 'for what has this actor/director been in'. Provides alternatives: use discover_movies with with_cast/with_crew/with_people for genre filtering, and for TV genres, call this tool then check media_type. Says to get id from search_people.

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 declare readOnlyHint and openWorldHint. The description adds important behavioral details: no-match returns {found:false, reason}, imdb_id takes precedence over title, and the type parameter's effect on ambiguous title lookups. 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 well-structured and front-loaded with the main purpose. It includes necessary details but could be slightly more concise. However, it remains clear and informative without redundancy.

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 presence of an output schema (not shown), the description adequately covers all needed context: what is returned, how to use the parameters, prerequisites, and error behavior. It addresses potential ambiguity and provides complete guidance.

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% with detailed parameter descriptions. The description adds extra value by explaining the type parameter's role in disambiguation and noting imdb_id precedence, beyond what the schema 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 explicitly states the tool looks up IMDb, Rotten Tomatoes, and Metacritic ratings, an awards summary, and OMDb age rating. It clearly distinguishes from siblings like get_movie/get_tv by noting they already include this data.

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 when-to-use guidance: 'Prefer get_movie/get_tv when you have a TMDB id — they already include this.' Also specifies required API key, parameter requirements (one of imdb_id or title), and error handling for missing parameters and no-match lookups.

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 indicate read-only and open-world. The description adds that review text is clipped to ~1500 characters and that rating can be null, providing useful behavioral detail.

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 concise (two sentences), front-loaded with purpose, and contains 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?

Given the simple output and clear schema, the description fully covers what the tool does, including return fields and clipping behavior.

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

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

Schema coverage is 100% and parameters are well-documented. The description adds value by explaining where to obtain the 'id' parameter, justifying a score above baseline 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?

The description clearly states 'Get user reviews for a movie or TV show', specifying the verb and resource, and distinguishes from sibling tools that search or retrieve other entities.

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 advises using IDs from search_movies/search_tv, providing context on prerequisites, though it does not explicitly state when not to use this tool.

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. Description adds significant behavioral context: noise from shared keywords, filtering out broad genre matches, misleading total_pages/total_results counts, and per-page results may be thin or empty. No contradictions 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?

Description is front-loaded with purpose, but is somewhat verbose. However, every sentence adds value (contrast with recommendations, caveats about filtering and pagination). Could be slightly more concise, but the information density justifies the length.

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

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

Given complexity (filtering, misleading pagination counts, possibility of empty results) and presence of output schema, the description fully covers behavioral nuances and return value interpretation. It explains not to use total_pages/total_results for gauging similarity depth, which is critical. Very complete.

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

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

Schema coverage is 100% with all parameters described. Description adds minor context (e.g., 'Get the id from search_movies/search_tv' for id, pagination context for page), but does not significantly enhance parameter meaning beyond the schema. Baseline of 3 is appropriate given high coverage.

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

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

Description clearly states the tool retrieves titles TMDB considers similar based on shared genres and keywords, and explicitly contrasts with get_movie_recommendations/get_tv_recommendations. It uses specific verb 'Get' and specifies resource 'titles similar to a given movie or TV show', distinguishing it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use recommendations first for thematically closer picks, and use this for genre/keyword-adjacent similarity. Also states prerequisite: 'Get the id from search_movies/search_tv.' Provides clear when-to-use and when-not-to-use 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 and openWorldHint, so the description does not need to repeat safety. It adds value by explaining that each result row carries its own media_type for routing. However, it does not detail pagination behavior or other side effects, but the schema covers limits.

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

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

The description is three sentences, front-loaded with the purpose, then parameter roles, then routing guidance. Every sentence adds value with 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?

With an output schema present, the description does not need to explain return values. It adequately covers usage context (trending, routing). Could mention pagination limits, but those are in the schema. Complete enough for this straightforward 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 3. The description paraphrases the enum values for media_type and time_window but adds no new semantic detail beyond the schema. It does not mention defaults explicitly, but the schema does.

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 'Get what's trending on TMDB' with a specific verb and resource. It distinguishes itself from sibling search tools by focusing on trending content, and further explains the parameter roles.

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 explicitly says 'Good for "what's popular right now"', giving clear usage context. It also instructs on how to route results to other tools based on media_type, but does not explicitly exclude search tools for trending queries.

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 (readOnlyHint, openWorldHint) are minimal, so the description carries the burden of behavioral disclosure. It goes far beyond: explains rating fallback logic (region-specific certification with fallback chain, degradation of ratings to {found:false} when OMDb unavailable), expand_episodes caps (50 per season, 250 total, trimming behavior, specials-first ordering, skipped seasons returning null), and the distinction between tool's certification and OMDb's ratings.rated. No contradictions 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?

Though lengthy, every sentence adds essential information for a complex tool. It is front-loaded with the core purpose, then methodically covers optional behaviors and alternatives. The structure flows logically from primary details to edge cases and fallbacks, with no repetition or padding.

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

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

Given the tool's complexity (5 parameters, output schema exists, optional heavy expansions), the description is exceptionally complete. It addresses fallback scenarios, caps, degradation, alternative tools, and prerequisites. No gaps are evident for typical agent usage, and it even covers rare edge cases like trillion-épisode shows and long specials.

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 substantially enriches each parameter's meaning. For expand_episodes, it details caps, trimming, ordering, and season-skip behavior. For include_ratings, it clarifies what ratings and awards summary include and the fallback behavior. For region, it explains the certification fallback chain. The extra detail is far beyond schema descriptions, making parameter semantics highly valuable.

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 it gets full details for one TV show by TMDB ID, enumerating the specific data fields (overview, genres, seasons/episodes counts, networks, created_by, status, certification, links). It explicitly distinguishes itself from get_tv_shows ('trimmed on purpose') and get_tv_season, making its specific verb+resource+scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: 'If you only need the headline info ... use get_tv_shows instead' and 'call get_tv_season for that season's full detail' for episode-level detail. Also directs users to obtain the ID via search_tv, covering prerequisites and 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?

Adds significant behavioral context beyond annotations: states cast limited to 20, lists crew roles, and importantly verifies that director/writer/creator credits are not reliably exposed (with examples). This complements the readOnlyHint 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?

Every sentence serves a purpose: purpose, limitation with evidence, alternative tools, source of ID. No fluff, well front-loaded, and structured logically.

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

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

Given the output schema exists, the description compensates by explaining the structure (cast up to 20, specific crew roles) and limitations. It provides complete guidance for using this tool alongside its siblings.

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

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

Schema covers the single parameter 'id' with description 'TMDB numeric id.' Description merely restates 'by TMDB id', adding no new semantic information. With 100% schema coverage, a 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 clearly states the tool lists main cast (up to 20) and production crew by TMDB id. It distinguishes itself from siblings by detailing what it does not expose (director/writer/creator) and directs to alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use, when not, and alternatives: for creator credits use get_tv's created_by field, for episode specifics use get_tv_episode. Also mentions sourcing 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?

Annotations (readOnlyHint, openWorldHint) already indicate non-destructive and open-ended behavior. Description adds specific output fields and constraints (up to 15 guest stars), providing valuable behavioral details beyond annotations. No contradiction.

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

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

Two concise sentences, each serving a clear purpose: first explains functionality and output, second provides guidance for input. No unnecessary words, efficiently front-loaded.

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

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

Given the tool's simplicity (3 parameters, output schema exists), the description adequately covers the core functionality and return fields. It omits potential edge cases like missing fields or error handling, but these are minor given the openWorldHint and standard API behavior.

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

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

Schema coverage is 100%, so all three parameters are already well-described in the input schema. The description adds minimal value by linking the 'id' parameter to search_tv. Baseline of 3 is appropriate as description doesn't significantly enhance parameter understanding beyond what the schema 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?

Description clearly specifies the action ('Get one episode of a TV show') and the resource (episode identified by show id, season, episode number). It lists returned fields (overview, air date, etc.) and distinguishes from siblings like get_tv_season and get_tv by focusing on a single episode.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description tells the user to obtain the show id from search_tv, providing a clear prerequisite. While it doesn't explicitly state when not to use this tool, the context implies it's for individual episode details vs. season-level data. Could be improved by mentioning alternatives like get_tv_season for full season data.

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, indicating safe read operation. Description adds value by explaining the underlying algorithm (co-viewing/personalization vs. genre/keyword matching), giving agents behavioral 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 sentences delivering key information efficiently. Could be slightly more structured (e.g., separate usage guidance from description) but remains clear and front-loaded.

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

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

With only 2 parameters, full schema coverage, annotations present, and an output schema, the description is complete. It covers purpose, selection criteria, and parameter source, leaving no major gaps.

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 documents both parameters well. The description adds marginal value by linking the id to search_tv, but does not elaborate on parameter details that the schema doesn't already cover.

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 'Get TV shows TMDB recommends for the given show id' and distinguishes from get_similar by explaining the recommender logic. It is a specific verb-resource pair that differentiates it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends preferring this tool over get_similar as the default choice and clarifies when each is appropriate. Also instructs to get the id from search_tv, providing concrete 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 declare readOnlyHint=true and openWorldHint=true; description adds key behavioral details: 50-episode cap, true total in episode_count, and that season 0 (specials) can be large. 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, front-loaded with all essential info (input, output, cap, total). Second sentence adds valuable guidance on specials and alternatives. No wasted words.

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

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

Given the tool's simplicity (2 params, output schema provided), the description covers input, output, behavioral constraints, and context for using alternatives. Sufficiently complete for an agent to invoke 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 covers both parameters with descriptions (100% coverage). Description reinforces that season_number 0 is specials but adds no new semantic information 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?

Clearly states the tool retrieves one season of a TV show by show ID and season number, listing returned data (overview, episode list with air dates, runtimes, ratings) and noting the 50-episode cap and true total in episode_count. Distinct from siblings like get_tv and get_tv_episode.

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 suggests an alternative (get_tv with expand_episodes=true) for retrieving all seasons' episodes in one call and advises obtaining the show ID from search_tv. Doesn't explicitly state when not to use, but the alternative guidance 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 significant behavioral context: bad/unknown ids never fail the whole call and instead return {id, found:false, reason} in order; include_ratings defaults to false and has rate limit implications; language overrides localization. No contradictions 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 well-structured with a clear opening sentence, then specific details and usage guidance. It is moderately long but every sentence adds value. Slightly verbose in the middle but overall efficient.

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 presence of an output schema (not shown but mentioned), the description covers all necessary aspects: purpose, parameters, behavior on errors, use cases, and comparisons to sibling tools. It is complete for a read-only bulk 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 description coverage is 100% with each parameter having a description. The description adds further value: ids can be obtained from search_tv/discover_tv/etc.; language localization explanation; include_ratings defaults to false and notes OMDb rate limit. This goes 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?

The description clearly states the tool gets compact TV show cards for 1-20 shows by TMDB id. It specifies the exact data included (name, year, genres, vote average, season/episode counts, opt-in ratings) and explicitly distinguishes from get_tv by noting the trimmed payload and use case for quick scanning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: for quick headline info, spotting short/miniseries, and checking many candidates without per-title get_tv calls. It clearly states when to use get_tv instead (when full details including region-specific certification are needed). It also explains how to obtain ids (from search_tv/discover_tv/get_similar/get_tv_recommendations).

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=true and openWorldHint=true. The description adds significant behavioral context: it lists the types of videos included, mentions that YouTube entries include a watch URL, and crucially discloses the language restriction with a live example (29 vs 2 results). This goes beyond the annotations and fully informs the agent about the tool's behavior.

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 consists of two concise sentences. The first sentence states the main purpose and key feature (YouTube watch URL). The second provides usage guidance and a critical behavioral note. Every part earns its place, and it is front-loaded with the most important 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?

Given the complexity of the tool (two parameters with clear schema, an output schema exists for return values), the description covers all necessary aspects: what videos are returned, where to get the id, and the language limitation. It is fully informative for an agent to use the tool correctly.

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

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

The input schema has 100% coverage, so the baseline is 3. The description adds minimal extra meaning to the parameters: it mentions that the id comes from search tools, but the schema already describes id and media_type sufficiently. The language caveat is not a parameter. Thus, the description adds some context but doesn't significantly enhance parameter understanding 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?

The description clearly states the verb "List" and the resource "trailers, teasers and clips for a movie or TV show" and distinguishes the tool from siblings by noting that YouTube entries include a watch URL. It also directs where to get the required id from search_movies/search_tv, making the purpose specific and distinct from other listing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit context on when to use: after obtaining an id from search_movies/search_tv. It also warns about the language limitation (no per-call override) with a concrete example. While it doesn't explicitly list exclusions or alternatives, the provided context is sufficient for an agent to understand the appropriate usage.

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 valuable behavioral context: the return structure (provider names per access type, fallback with available_regions). It does not contradict 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 two substantive sentences plus a short instruction. It is front-loaded with the main purpose. Minor redundancy (e.g., 'JustWatch data via TMDB' could be tighter) but overall 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?

Given the output schema exists, the description need not detail return values, but it does describe the key return structure (provider names, fallback). It covers the essential edge case of no data and region handling, making it complete for this tool's complexity.

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

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

Schema coverage is 100% for all three parameters. The description adds value by instructing the agent to 'Get the id from search_movies/search_tv', which clarifies the parameter source beyond the schema's description. This subtle guidance enhances semantics.

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 verb 'find' and the resource 'watch providers for a movie or TV show', distinguishes from siblings like search_movies and get_tv by specifying the exact functionality (streaming, renting, buying via JustWatch) and hints at the necessary ID source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool (to find streaming options) and gives a fallback behavior ('if it has no data, returns available:false plus available_regions to retry with'). It also specifies the prerequisite source for the 'id' parameter. However, it does not explicitly contrast with sibling tools like 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?

Annotations already indicate readOnlyHint and openWorldHint. Description adds important behavioral context: the tool may return multiple rows for the same name, and suggests disambiguating fields. Does not contradict 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?

Three well-focused sentences. First states purpose with examples, second tells downstream usage, third warns about duplicates and gives disambiguation advice. No unnecessary words. Efficient and clear.

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

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

Given the tool's moderate complexity (simple search with pagination), the description covers purpose, usage, disambiguation, and downstream integration. Schema and annotations already provide rich structured data. The description is complete for agent decision-making.

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 covers 100% of parameters with descriptions. Description adds value by explaining how to use the output (feed id to other tools) and disambiguation hints, though it doesn't add extra parameter details beyond schema. Baseline 3, elevated for contextual addition.

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 the purpose: resolve company name to TMDB numeric id. Provides concrete examples (A24, Pixar) and explains downstream usage (feed to discover_movies/discover_tv via with_companies). Distinguishes from sibling tools by focusing on 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?

Explicitly tells when to use: to get a company id for use with discover endpoints. Warns about non-unique company names and advises checking origin_country and logo_url for disambiguation. Provides explicit guidance on handling multiple results.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context, such as the region parameter not filtering results (only selecting which release_date to display) and the year parameter being a soft bias. This complements the annotations without contradiction.

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

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

The description is concise (two sentences plus a clarifying note) and front-loaded with the main purpose. Every sentence provides essential information without redundancy.

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 6 parameters, full schema coverage, annotations, and presence of output schema, the description is thorough. It covers scope, alternative tools, parameter nuances, and addresses common confusions, making it complete for agent selection.

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%, but the description adds significant meaning beyond the schema, such as explaining region's non-filtering behavior, year's soft bias, and recommending alternatives. This enhances parameter understanding.

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 it searches TMDB movies by title and returns compact summaries with TMDB id and pagination info. It also distinguishes itself from the sibling tool 'search_multi' by specifying when to use each.

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 explicitly recommends using this tool over 'search_multi' when the result is known to be a movie, and advises using 'discover_movies' for exact-year filtering. It also clarifies region and year parameter behaviors, providing clear guidance on when to use 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 readOnlyHint and openWorldHint. Description adds value by explaining each result carries a media_type for routing, which is not in annotations. 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, front-loaded with purpose, then usage guidance. No wasted words.

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 multi-type search tool with annotations and output schema, description covers purpose, usage, and result structure adequately.

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% with detailed parameter descriptions. Description does not add extra parameter information 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?

Description clearly states the tool searches movies, TV shows, and people in one call. It distinguishes from siblings by noting more precise alternatives when the type is known.

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 to use when the query could be any type, and not to use when type is known, directing to specialized search 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 read-only and open-world behavior. Description adds that the tool returns the TMDB ID and top 5 known-for titles, which are useful behavioral details 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 sentences, no fluff, front-loaded with key information. Every word earns its place.

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

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

Given the tool's simplicity, full schema documentation, presence of output schema, and clear relationship to sibling tools, the description is complete and sufficient.

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 does not add new meaning per parameter 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 ('Search'), identifies the resource ('people'), and adds scope ('by name'). It distinguishes from sibling 'search_multi' by stating when to use this tool over the alternative.

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 'Use this over search_multi when you already know the result is a person,' providing clear guidance on tool selection.

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 results are compact summaries and that the TMDB id is the required input for downstream TV tools. It does not contradict annotations and gives useful behavioral context beyond schema 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?

Two dense sentences, front-loaded with the core action and followed by usage guidance. No filler or redundancy.

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 a full input schema, output schema, read-only/open-world annotations, and a clear sibling distinction, the description covers the essential context for a search tool. It does not need to repeat return-value details 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 description coverage is 100% and each parameter (query, page, year, language, include_adult) already has detailed meaning. The description's phrase 'by name' adds slight emphasis on query behavior, but no additional parameter semantics are needed, so 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?

Description states 'Search TMDB TV shows by name' — a specific verb and resource. It also explains returns compact summaries with TMDB id and explicitly distinguishes from search_multi, earning full marks.

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 'Use this over search_multi when you already know the result is a TV show,' which both names an alternative and sets the condition for choosing this tool. It also notes get_tv and other TV tools require the returned id, clarifying downstream usage.

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 declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context beyond annotations: explains that TMDB has no name-based lookup, only numeric IDs; that provider IDs differ by region; and that omitting watch_region searches the global list. 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 a single paragraph that is front-loaded with the primary purpose. It is slightly long but every sentence adds necessary guidance (usage, region nuance, pagination). No redundancy.

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 complexity (name-to-ID mapping, region variation, pagination), the description is thorough. It addresses key aspects: why numeric IDs are needed, region dependency, and the impact of watch_region. The output schema exists but is not needed for completeness 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%, baseline 3. The description adds meaning: explains watch_region's role in matching discover queries, media_type's effect on provider existence, and that the same ID applies to both movie and TV. This adds value beyond the schema definitions.

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's purpose: 'Resolve a streaming/rental/purchase service's name to its TMDB numeric provider id.' It uses a specific verb ('resolve') and identifies the resource (service name to ID). It also distinguishes from sibling tools like search_movies by explaining the conversion is for use with discover tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear guidance: 'Feed the id into discover_movies/discover_tv's with_watch_providers...' and warns against guessing IDs. It explains region differences and the effect of omitting watch_region. It does not explicitly state when not to use, but provides sufficient context for correct invocation.

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