amodb-mcp

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

Annotations already carry the safety profile (readOnly, idempotent, destructive=false, openWorld), so the bar is lower. The description still adds real behavioral value beyond them: it discloses that at most `limit` movies return (default 10) and warns that sorting by vote_average needs vote_count_gte to avoid low-vote titles leading the list.

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, usage examples, and output size, then the necessary detail. The genre enumeration is long but high-value reference data, not filler, and the closing tip is actionable. Slightly verbose but every sentence 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?

With 10 params, no output schema, and 0 required params, the description does exactly what's needed: it explains the return size, the filter interplay, and the genre codes, and annotations cover safety. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3. The description exceeds that by supplying the full genre-id mapping (28 Action, 878 Science Fiction, etc.) that the schema only alludes to as 'genre ids', plus the interaction rule between sort_by and vote_count_gte — neither is derivable from the schema 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+resource (find movies) and explicitly demarcates scope: by filters rather than by name. This distinguishes it from the sibling search_titles, so an agent can route correctly 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?

Provides concrete usage examples ('best rated sci-fi from 2010', 'popular French comedies') that map directly to filter combinations, giving clear context for when the tool applies. It does not name alternatives explicitly or state exclusions, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety bar is met; the description goes further and discloses the return structure (movie_results, tv_results, person_results with media_type), warns that tv_episode_results and tv_season_results are always empty, and states that an unknown external_source or malformed id is an error.

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?

Four sentences, front-loaded with the purpose and then the input examples, return shape and error behavior. Every sentence carries information, though the enumeration of id formats is slightly redundant with the parameter descriptions.

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?

There is no output schema, yet the description still explains the response buckets, the always-empty ones, the media_type discriminator, and how to chain into sibling tools. For a two-parameter lookup with rich annotations, 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 already 100%, so the baseline is 3; the description adds practical value by mapping id shapes to source values (tt/nm prefixes imply imdb_id, Q implies wikidata_id, Kinopoisk digits imply kinopoisk_id) and by restating which sources return nothing rather than erroring, though much of this duplicates the schema's own descriptions.

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

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

States a specific verb (look up) and resource (movie, TV show, person) and immediately scopes it to lookups by an id from another system rather than the amodb numeric id, which cleanly separates it from get_movie/get_tv_show/get_person and search_titles.

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 condition ('when you do not have the amodb numeric id') and gives concrete typical inputs (IMDb tt0137523 / nm0000093, Kinopoisk digits, Wikidata Q ids). It also closes the loop by telling the agent to pass results to get_movie, get_tv_show or get_person, so the adjacent workflow is fully specified.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: append values enlarge the response ('request only what you need') and the caveat that the reviews section is empty for most titles.

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 then the sibling handoff, with denser append detail after. The appended-data inventory is long and somewhat list-heavy, but nearly every clause conveys information an agent needs to choose append values, so little is 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?

No output schema exists, so the description must carry return-value detail, and it does: the core fields, every append section's contents, and the amodb extras (ratings scales, moods scale, soundtracks, wikidata). It even notes the reviews section is usually empty, which is exactly the kind of expectation-setting an agent needs.

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 than the schema by explaining what each append value actually yields (credits = cast/crew, videos = trailers, watch/providers = streaming locations, external_ids = IMDb/Kinopoisk ids) and describing the shape of ratings, moods and soundtracks. That is meaning the bare enum list does not carry.

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

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

Opens with a precise verb+resource ('Get the full record of one movie by its numeric id') and enumerates the returned fields, making it immediately distinguishable from get_tv_show, get_person and get_season. It also routes the agent to search_titles for id acquisition.

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 the alternative for a related need ('For cinema times use get_showtimes') and the prerequisite workflow ('Get the id from search_titles first'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds some context in explaining that append pulls combined vs. split credit sets, but it does not disclose what happens on an unknown id, payload size implications, or language fallback 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?

Two sentences, front-loaded with verb and returned fields, then the append guidance. The field enumeration is slightly sprawling but every element is informative; nothing is 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 no output schema, the description carries the burden of describing return content and does so by listing the core fields. It is complete for correct invocation, with only minor gaps (error behavior for a bad id, whether append results are nested under a key).

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 goes beyond the enum list by interpreting each append value semantically (combined_credits = full filmography with movies and TV together; movie_credits/tv_credits = one kind; images = photos; external_ids = the IMDb id), which resolves ambiguity the bare enum cannot.

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 and resource (get the record of one person) and enumerates exactly what is returned: name, biography, birth/death dates, place of birth, known department. It clearly distinguishes itself from siblings like search_titles and get_movie, which is enough for an agent to route correctly 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?

Gives explicit routing for the required id ('Get the id from search_titles with media_type person') and explains the append path for extra data. It lacks an explicit 'do not use this for X, use Y instead' exclusion, but the when-to-use context is clear and actionable.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that by listing the return payload (since no output schema exists) and flagging the specials case, though it says nothing about pagination or behavior on an invalid season number.

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 and return payload, then usage, then the specials caveat and the id dependency. Every sentence earns its place with no filler.

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

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

For a read tool with no output schema, it compensates by listing the episode fields returned, and annotations cover safety. Missing only minor operational detail such as behavior for out-of-range seasons or how the language fallback interacts with episode overviews.

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 each parameter is fully documented there. The description's 'Season number 0 holds the specials' merely restates the schema's own 'Use 0 for specials', and the language parameter is left entirely to the schema, so no new semantic value is added. 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+resource ('Get one season of a TV show with its full episode list') and enumerates the returned fields, which cleanly distinguishes it from get_tv_show (show-level) and the other siblings. An agent can tell exactly what this returns 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?

Gives clear usage context ('Use it to answer questions about episodes, air dates or season length') and explicitly routes the agent to search_titles or get_tv_show for the required tv_id. It does not name a sibling to avoid or state exclusions, which keeps it short of a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: start times are local to the cinema, output is truncated by max_venues and max_showtimes_per_venue with totals (showtimes_total, venues_total) giving the full counts, the no-country reply has an empty results list, and many titles have no showtimes. These are real operational traits an agent needs and none are derivable from 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?

Effectively one dense paragraph that is front-loaded with the core purpose and the country/no-country fork before drilling into return fields and pagination limits. Every sentence carries information, though the middle payload enumeration is long and the truncation caveat is buried near the end rather than surfaced early.

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

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

With no output schema, the description carries the full burden and does so: it documents the shape of both the country-summary reply and the cinema/showtime reply, including per-showtime fields (local start time, date, formats, auditorium, price, booking_url) and the totals fields for detecting truncation. An agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: what omitting country actually produces ('results is then empty'), that country must be a two-letter code, and that the max_* limits truncate rather than filter the underlying totals. The per-parameter enumeration largely repeats the schema, so it falls 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 and resource ('Find where and when a movie or TV title is showing in cinemas'), scoped by title type and starting from today. This is clearly distinguishable from siblings like get_movie or search_titles, which return metadata rather than venue/showtime 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?

Explicitly describes the two-step call pattern: omit country to get a country summary, then re-call with a two-letter code to get cinemas, including what the reply looks like in each case. It also warns that many titles have no showtimes, which sets expectations. It does not name alternatives (e.g., when to prefer search_titles first), leaving that to the schema.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds genuinely useful context beyond that: that 'append' inflates the response and should be requested sparingly, and that certain sections are empty for most shows.

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

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

The purpose and return shape are front-loaded, followed by append semantics and routing. It is long but nearly every clause carries information; the only mild waste is enumerating append values that the schema also lists.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly (field list, empty sections, appended extras). Nothing an agent needs to call this correctly appears to be 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, but the description explains what each append value actually returns (credits for cast/crew, external_ids for IMDb/TVDB/Kinopoisk ids, etc.) and notes moods/soundtracks/ratings/wikidata mirror the movie shapes — meaning the schema alone does not provide.

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

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

The description names a specific verb and resource ('Get the full record of one TV show by its numeric id') and immediately enumerates the returned fields, so it is unmistakably distinct from get_movie, get_season and get_showtimes.

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 routes the agent to siblings under stated conditions: get_showtimes for cinema times, get_season for the episodes of one season, and search_titles to obtain the id. It also tells the agent which sections are usually empty (reviews, created_by), which prevents wasted calls.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuine behavioral context beyond them: what fields come back, that results are capped at `limit` (default 10), and that the year filter only applies to movie/tv searches, not person or multi.

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?

It is front-loaded with purpose and the routing rule, then details returns and defaults. It is dense and mostly earns its space, though the year-filter explanation partially duplicates the schema's own year parameter description.

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

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

With no output schema, the description correctly takes on the burden of describing return values (id, title/name, release date, overview, popularity) and the result cap. Combined with the routing guidance and defaults, 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 the baseline is 3, but the description reinforces defaults and cross-parameter behavior: `limit` default of 10, "multi" as the media_type default, and the year filter's applicability. It also discloses a return-side effect not in the schema (each multi result carries a media_type field), which is slightly beyond the baseline.

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 for movies, TV shows or people by name") and distinguishes itself from the sibling get_movie/get_tv_show/get_person tools, which are detail lookups rather than searches. An agent can identify the tool's 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 clear when-to-use context: "Call this first when you have a title or a name and need the numeric id that the other tools require," which effectively routes the agent from search to the get_* tools. It also advises using media_type "multi" when the kind is unknown. It stops short of naming specific alternative siblings or stating when not to search.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: results are capped at 'limit' and ordered most-popular-first, which tells the agent how to interpret the return list.

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: purpose first, then usage triggers, then return behavior. Every sentence carries information and nothing is padded.

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

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

With no output schema, the description usefully discloses the result cap and ordering, and annotations carry the safety profile. Minor gaps remain (e.g., no note on how person entries differ from movie/TV entries in the result set), but an agent has enough 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 description coverage is 100%, with limit, language, media_type and time_window all thoroughly documented including enums and defaults. The description only restates the limit default and media-type scope, adding nothing the schema doesn't already say, 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?

The description opens with a specific verb+resource ('List what is trending now') and enumerates the scope ('movies, TV shows, people, or all three mixed'), so an agent immediately knows this returns currently-popular items. It does not explicitly contrast itself with related siblings like search_titles or discover_movies, but the time-based popularity framing is distinct enough.

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 concrete trigger questions ('what is popular today', 'what are people watching this week'), which is clear usage context. However, it names no alternatives or exclusions (e.g., when to prefer search_titles or discover_movies), so the routing guidance stops short of full when/when-not coverage.

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