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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, covering the safety profile. The description contributes only that the target is a 'static list'; it says nothing about duplicate handling, partial success when some IDs fail resolution, or what happens if the list_id is invalid or not owned by the user.

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

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

A single front-loaded sentence with no filler, and the resource scope leads. It is appropriately sized for a simple append operation, though the terseness is part of why the guidance gaps exist.

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?

Incorrect resolution — see below.

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% – list_id, movies, shows and the imdb/tmdb identifier shapes are all documented in the schema with examples. The description only echoes the parameter names, adding no format or constraint information beyond that. Baseline 3 applies.

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

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

States a specific verb and resource (add movies/shows) plus the target (one of the user's static lists), which cleanly separates it from remove_list_items and from add_watchlist_items. The word 'static' hints at the list-vs-watchlist distinction but the description never names the sibling it is not.

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?

No when-to-use guidance: it does not say how to obtain a valid list_id (get_user_lists / get_list) or when to prefer the watchlist variant. The only implicit cue is 'static lists,' leaving the agent to infer everything about 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation/idempotency profile is covered structurally. The description adds nothing beyond that: no word on what happens with duplicate entries, invalid IDs, or partial failures when multiple items are submitted.

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

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

A single waste-free sentence, well front-loaded, but its brevity comes from under-specification rather than disciplined editing. It says the minimum and leaves the rest to the schema.

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

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

Annotations cover the safety profile and the schema is fully documented, so an agent can technically invoke it. Gaps remain around batching behavior, duplicates, and the fact that neither parameter is required (empty call semantics are undefined).

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 per-field examples for imdb and tmdb IDs, so the baseline is 3. The description only echoes the two parameter concepts ('movies/shows') without adding format or batching 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?

States a specific verb ('Add') and resource ('movies/shows to the user's watchlist'), which clearly distinguishes it from get_watchlist and remove_watchlist_items by action. It doesn't explicitly name the sibling alternatives, but the action+resource is unambiguous.

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

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

No guidance about when to use this versus remove_watchlist_items, add_list_items, or mark_watched, and no prerequisites stated. An agent must infer the use case from the name alone.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the available browsing sources but does not explain pagination behavior, authorization requirements, or what kind of list data is returned.

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 front-loaded sentence with no wasted language. It efficiently lists the supported browsing categories while staying appropriately short for a simple read-only tool.

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-only browse tool with annotations and a documented enum, the description is adequate but not complete. It does not clarify how this tool relates to sibling list tools such as get_user_lists, search_lists, or get_list, which could cause selection ambiguity.

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

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

The description adds meaningful semantics for the required source enum by mapping top to top public lists, liked to your liked lists, official to official MDBList lists, and external to connected external lists. Limit and offset are left to the schema, which already documents their applicability to top, curated, and liked sources.

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 gives a clear verb-resource pair, 'Browse lists', and enumerates the five source categories the tool exposes. It is more specific than a generic list tool, though it does not explicitly distinguish itself from sibling tools like get_user_lists or search_lists.

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 five source categories imply when each browsing mode is appropriate, especially for liked and external lists. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternatives such as search_lists or get_user_lists are named.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds only the "static" list-type distinction, but says nothing about name uniqueness, default visibility for the private flag, or whether creation fails on duplicates.

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

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

A single short sentence with the action front-loaded and no filler. It is under-specified rather than verbose, which is a completeness issue more than a conciseness one.

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 creation tool with no output schema and zero parameter documentation, the agent lacks what it needs: the meaning/default of private, behavior on duplicate names, and what the call returns (e.g., new list id). The description does not fill any of these 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 description coverage is 0% for two parameters, so the description must carry the burden and it does not. Neither the required name (any constraints beyond minLength) nor the private boolean (default value, effect on visibility) is explained anywhere.

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

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

States a specific verb and resource ("Create a new static list") and scopes it to the user's account. It does not contrast with sibling creation/mutation tools such as add_list_items or delete_list, but the core action is unambiguous.

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

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

No guidance on when to create a list versus using an existing one via get_user_lists or browse_lists, and no prerequisites (e.g., authentication) are mentioned. The agent must infer usage entirely.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them: "Permanently" confirms irreversibility, and the parenthetical specifies which list types are rejected, which annotations cannot express. It does not describe the failure response when a non-deletable list is targeted.

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

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

A single sentence with the verb and the object front-loaded, and the constraint packed into a parenthetical. No filler or restated title 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?

For a one-parameter destructive tool with full annotation coverage and no output schema, the definition supplies the essentials: permanence, target resource, and eligible list types. Only the behavior on invalid/non-deletable IDs is unaddressed.

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

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

There is a single parameter (list_id) with 100% schema description coverage ("Numeric MDBList list ID"), so the schema already carries the semantics. The description adds no format, range or acquisition hints beyond what the schema states, which is the baseline-3 case for 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?

States a specific verb (delete) and resource (the user's static lists), and narrows the scope by excluding dynamic, official and external lists. This lets an agent distinguish it from read-oriented siblings like get_list or get_user_lists, though it never names an alternative explicitly.

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

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

"Permanently delete one of the user's static lists" plus the parenthetical exclusion gives a clear condition for use and a clear when-not. It stops short of routing the agent to alternatives (e.g. remove_list_items for partial removal, create_list for creation), so it is clear context without full alternative guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered externally. The description adds nothing beyond them: no note that results are paginated via cursor, no default page size behavior, no statement about what an empty result or the append_to_response expansion means in practice.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though efficiency here comes partly from omission rather than disciplined editing.

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 an 18-parameter discovery tool with no output schema, the description should explain result shape, pagination contract, and at least the sorting/expansion semantics. Instead the agent is left to reverse-engineer cursor pagination and enum behavior from the schema alone.

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

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

With 18 parameters and only 56% schema description coverage, the description carries real compensation duty, yet it only says 'filters and sorting' generically. It never explains the 13-value sort enum, the default of genre_mode, or the append_to_response expansion options that are undocumented in the schema.

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

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

The description gives a specific verb plus resource (browse the movie/show catalog) with filters and sorting, so the agent knows it is a filtered enumeration tool. It does not distinguish itself from the close sibling search_media, leaving the browse-vs-search boundary implicit.

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

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

There is no statement of when to prefer this over search_media, get_media_info, or get_genres, and no exclusions or preconditions. An agent must infer from the word 'browse' that this is the filtered/sorted enumeration path rather than keyword lookup.

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=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds one piece of genuinely new context — that a tier-based limit gates the operation — but it does not say what happens when the limit is hit, nor does it acknowledge the idempotent behavior for an already-favorited person.

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

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

A single front-loaded sentence with no filler. The mutation and its gating constraint are both stated immediately, and nothing redundant is included.

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 two-parameter mutation with full schema coverage and an annotation set covering safety, this is close to adequate. The remaining gap is the tier-based limit: the description raises the constraint but leaves the agent without a way to know the limit or predict the failure, and there is no output schema to clarify what the favorite record looks like.

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% for both parameters (tmdb_id as TMDb person ID, role as an actor/director enum defaulting to actor), so the schema carries the semantics. The description adds nothing about either parameter — notably it never clarifies why role matters or how it interacts with the favorite entry.

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 gives a specific verb and resource ('Add a person to the user's favorites') that an agent can match against the directionally opposite siblings unfavorite_person and get_favorite_people. It stops short of naming those siblings, but the add/remove/list triad is unambiguous from the verb.

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

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

There is no explicit when-to-use or when-not-to-use guidance; the only conditional information is the parenthetical tier-based limit, which is a constraint rather than a routing rule. An agent must infer from the name that this is the write counterpart to unfavorite_person and that get_favorite_people should be used to check existing favorites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the meaningful detail that the tool switches to upcoming movies/episodes featuring the favorited people, but it says nothing about pagination behavior, response shape, or what happens with an empty favorites 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?

One sentence, front-loaded with the primary behavior and with the mode switch appended. The parenthetical is a bit dense but nothing is wasted.

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 3-param read-only tool with no output schema, the description conveys the two distinct return modes, which is the key thing an agent needs. Remaining gaps (pagination, response contents) are minor for a read-only list tool.

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

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

Schema coverage is 67%: offset and upcoming are documented in-schema, limit is not. The description usefully clarifies that the upcoming flag returns releases 'featuring them' rather than the favorites themselves, which goes beyond the schema's terse 'Return upcoming releases instead', but it leaves limit/offset semantics untouched.

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 the user's favorited people') and names the alternate mode. It never distinguishes itself from the sibling mutations favorite_person/unfavorite_person or from get_person, so the sibling differentiation is only partial.

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 'upcoming=true' clause implies an alternate usage, but there is no guidance on when to call this versus get_person or favorite_person, and no mention of prerequisites such as authentication or a populated favorites 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?

readOnlyHint=true already declares this is a safe read, so the description's burden is lower. It adds the useful downstream hint that returned slugs are the filtering keys, but says nothing about ordering, size, or return shape beyond slugs.

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

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

A single tight sentence with the core action front-loaded and the usage hint in parentheses. No wasted words, though it could surface the anime toggle.

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

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

For a one-optional-param read-only lookup with a fully documented schema and clear annotations, the description covers intent and output key (slugs) adequately. Only minor gaps like anime scope and ordering remain.

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

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

Schema description coverage is 100%, so the 'anime' boolean and its default are fully documented in the schema. The description adds no parameter detail of its own, making baseline 3 correct.

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 ('List available genres') and no sibling overlaps with genre retrieval, so the agent can identify it easily among the many media tools. It stops short of clarifying the anime scope, which is the one dimension a sibling could be confused on.

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 parenthetical 'use the slugs to filter catalogs and lists' implies downstream usage but gives no explicit when-to-call guidance or prerequisites. Usage is inferable rather than stated, which fits the 3 tier.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 100-item batch ceiling and enumerates the four state categories returned, which is useful context, but says nothing about authentication requirements, partial-failure behavior for mixed media types, or response shape.

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

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

A single front-loaded sentence that states the returned fields, the entity types, and the batch cap with zero filler. Every clause carries information the agent needs before calling.

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 three required parameters and no output schema, the description does well to enumerate the four state categories returned, but it omits the response structure per item and whether all four states are always present. For a batch tool that could return 100 heterogeneous objects, that leaves a meaningful gap.

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 67%, with media_type undocumented in the schema, so the description's mention of 'movies, shows or episodes' partially compensates for that gap. However it adds nothing about the provider/ID-type pairing (TMDb integers vs MDBList strings) or why episodes are restricted to tmdb, leaving the agent to read 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 names a specific verb (get) and a compound resource (watched, rated, collected and watchlist state) plus the entity types it accepts, so the agent knows exactly what data comes back. It is implicitly distinguishable from narrower siblings such as get_ratings or get_watchlist because it aggregates all four states in one call, but it never states that differentiation explicitly.

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

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

The description implies a batch status-lookup use case via 'up to 100', but gives no explicit when-to-use, when-not-to-use, or named alternative. With 30+ siblings including get_ratings, get_watchlist, and get_media_info, an agent must infer on its own why it should call this aggregated tool instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavioral context by naming the data domains covered (watched items, ratings, sync data) and that the values are timestamps rather than content, but it says nothing about scope, ordering, or granularity of those timestamps.

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

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

A single front-loaded sentence with no filler; the returned concept is stated immediately and nothing is repeated from the title or schema.

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

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

With no output schema, the description carries the burden of explaining the return value; it does name timestamps and the data categories, but 'other sync data' is vague and the shape of the response (per-item? aggregated?) is left undefined. Adequate to call, but not fully complete for a read tool with no structured output documentation.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the call is user-scoped with no filtering arguments needed.

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

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

The description states a specific verb (get) and resource (timestamps of last changes to watched items, ratings, and sync data), which is meaningfully more informative than the title 'Get last activities'. It does not explicitly contrast with close siblings like get_sync or get_user_stats, so the agent must infer the distinction, but the resource is clear enough to act on.

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

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

There is no guidance on when to call this versus get_sync, get_user_stats, or get_item_state, all of which plausibly overlap with 'sync data'. The description only defines what the tool returns, leaving the selection decision entirely to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-field context (name, owner, item count, likes), which matters since there is no output schema, but it says nothing about error behavior for invalid identifiers or whether unlisted shares behave differently.

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

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

One short sentence, front-loaded with the verb and immediately followed by the payload. Nothing redundant or padded.

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

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

For a single-parameter read tool with annotations and a fully documented schema, the description covers the essentials and names the returned fields, compensating for the absent output schema. The only gap is that it doesn't mention the multiple lookup forms the agent is expected to pick among.

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 the union of five identifier forms ({id}, {username,listname}, {official}, {share_token}, {external_id}) is documented entirely in the schema, so the baseline of 3 applies. The description contributes nothing beyond 'of a list' — the parameter forms are invisible in prose.

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

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

Specific verb ('Get') plus resource ('list') with an explicit enumeration of the metadata returned (name, owner, item count, likes), which implicitly separates it from get_list_items and get_user_lists. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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

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

No guidance on when to use this versus get_list_items, get_user_lists, browse_lists, or search_lists. An agent must infer from the sibling names alone that this fetches a single list's header rather than its contents or a collection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that results are paginated/sortable/filterable, but says nothing about return shape, whether cursor pagination invalidates offsets, or how access to private/shared lists is gated.

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

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

A single front-loaded sentence with no filler; every clause (resource, filtering, sorting, pagination) carries information.

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

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

With 10 parameters, a five-way anyOf for list identification, and no output schema, the description should say more about what an item record contains and how pagination terminates. It is adequate but leaves meaningful gaps for a tool of this 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 70%, so the schema does most of the work, and the description's "filtering, sorting and pagination" merely paraphrases parameter names. It adds no meaning about the five mutually exclusive list identifiers or the append_to_response cost/behavior.

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 the movies and shows in a list") plus the capabilities it supports, which is enough to separate it from siblings like get_list (metadata), get_list_membership, and add/remove_list_items. It doesn't explicitly name those siblings, so it falls short of a 5.

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

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

Usage is only implied: the agent infers this is the read path for list contents. There is no statement of when to choose this over get_list or get_list_membership, and no note on prerequisites such as needing a share_token for unlisted lists.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the useful scope fact that only static (non-watchlist) lists are checked, but says nothing about authentication requirements, the behavior when a media item matches multiple lists, or how seasons/episodes are resolved.

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

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

A single, front-loaded sentence with zero filler. It is efficient, though it is arguably terse to the point of omitting needed qualifiers about the ID parameters and shared 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 six parameters, no output schema, and a tool that returns a set of matching lists, the description never says what comes back (list names? IDs? count?) nor how the four alternative ID fields interact with mediatype. For a reverse-lookup with no output schema, that is a significant gap.

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 83%, so the schema already documents imdb/tmdb/tvdb/trakt and include_shared. The description adds only a restatement of the mediatype enum values and does not explain that different media types allow different ID types or what include_shared expands to.

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 gives a specific verb ('Find which ... contain') and a specific resource ('the user's static lists'), scoped to four media types. An agent can tell this is a membership/reverse-lookup rather than a listing tool, though it never names a sibling to contrast with.

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

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

There is no explicit guidance on when to use this instead of get_list, get_list_items, or get_user_lists. The adjective 'static' implicitly excludes the watchlist, but how to pick between this and the other list tools, or when include_shared matters, is left entirely to inference.

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

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

Annotations already establish readOnly/openWorld, so the description isn't burdened with the safety profile. It adds real behavioral context beyond them: recommendations cap at ~8 items and are sparse for niche titles — an agent-visible expectation about result quality. It omits what happens on an invalid/mismatched provider ID.

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

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

Two tight sentences with the core capability front-loaded and the optional feature second. No filler, though the quoted 'recommendations' phrasing is slightly awkward.

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, and the description compensates by naming the main return fields (ratings, scores, streams, IDs). With three required params and a clear primary path, an agent has enough to call it correctly; only the secondary append values and media_type semantics are left thin.

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?

At 50% schema coverage, the description partially compensates: it explains that the identifier is provider-specific and details the 'recommendations' value of append_to_response. It says nothing about media_type (including the non-obvious 'any' enum) or the other append values (episode_ratings, extra, keyword, review).

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

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

Specific verb + resource ('Get full details for a movie or show') plus an enumeration of what's returned (ratings, scores, streams, IDs). The 'by provider ID' scoping implicitly separates it from the sibling search_media, though no sibling is named explicitly.

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

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

The 'by provider ID' framing implies the precondition (you must already have an ID, otherwise use search_media), and it explains the optional recommendations add-on. But no explicit when-to-use/when-not or named alternative is given, so usage must be inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-API nature are covered. The description adds that results cover people in film roles (actor, director, …), but says nothing about what detail fields are returned or error behavior for unknown IDs — acceptable given the annotation coverage, but thin.

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

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

A single sentence with the resource and the identifying parameter front-loaded; nothing extraneous and nothing buried.

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?

It is a simple one-parameter read tool with clear annotations, so the core need is met. However, there is no output schema, and the description does not characterize the returned payload beyond 'details', leaving an agent to guess what fields come back.

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 sole parameter is fully described as 'TMDb person ID'. The description only restates that; it adds no format guidance (e.g., that it is the numeric TMDb ID, not an IMDb ID), so the baseline 3 applies.

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

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

States a specific verb and resource ('Get details of a person') and scopes the input to a TMDb person ID, so an agent can distinguish it from search_media or get_favorite_people. It stops short of explicitly naming which sibling to use instead, but the ID-lookup framing is clear.

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 phrase 'by TMDb person ID' implies the prerequisite (you must already have an ID rather than a name), which is the key usage condition. No explicit when-to-use/when-not, and no mention of what to do if only a name is known (presumably use a search sibling).

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds a genuine quota detail (10 IDs per call, 100 for supporters) that the structured fields do not convey. It leaves open what happens on exceeding the limit and how 'supporter' status is determined, and the stated cap of 10 is looser than the schema's maxItems of 100, which is slightly confusing.

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

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

Two tight sentences with the capability first and the hard limit second. No filler, nothing repeated from the schema or annotations.

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 read-only batch lookup with no output schema, the description plus schema covers what an agent needs. Missing details (failure behavior for unknown IDs, enum semantics) are gaps but not blockers for correct invocation.

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

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

Schema coverage is only 50%: ids and provider are documented inline while media_type and rating_source have bare enums with 11 values, several of them non-obvious (score vs score_average, mal, tomatoes). The description clarifies that only one rating_source is returned per call, but adds nothing about provider selection or the enum meanings. Baseline 3 for a description that partially compensates.

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

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

States a specific verb (get), resource (ratings) and the batch scope, plus a meaningful constraint ('one rating source for many movies or shows'). That distinguishes it from sibling rate_media and remove_ratings, though it never names them explicitly.

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

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

The batching note and per-call limits imply when this tool is appropriate (bulk lookups rather than single-item calls), but there is no explicit 'use X instead when Y'. An agent must infer the routing against get_media_info and rate_media from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description adds nothing: no mention of pagination via `cursor`/`limit`, no explanation that `since` enables incremental sync, and no statement about result size or ordering. For a bulk-read tool, the incremental/pagination behavior is the most important thing to disclose.

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

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

One short sentence, front-loaded with the verb and the payload, with no filler. It is efficient, though brevity here comes at the cost of the missing behavioral detail noted elsewhere.

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

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

With six parameters, no output schema, and pagination plus a timestamp-based incremental filter, the description should say how paging and delta-sync work and roughly what a response contains. It covers only the kind enumeration, leaving the agent to discover pagination behavior from the schema alone.

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 83%, so the baseline is 3. The description's kind list is essentially a restatement of the `kind` enum and adds no syntax, default, or format detail for `since`, `cursor`, `limit`, or `tmdb` beyond what the schema already says.

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 clear verb ('Get') and enumerates the five record kinds it returns, so an agent can tell it is a bulk snapshot reader rather than a single-item lookup. It loses a point because it never distinguishes itself from sibling readers that overlap heavily (get_ratings, get_watchlist, get_user_stats), and the title's 'sync snapshot' framing is not developed in the description.

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

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

Usage is only implied: the enumerated kinds map to the required `kind` parameter, so an agent can infer what each call retrieves. There is no explicit when-to-use/when-not-to-use and no routing to alternatives such as get_ratings or get_watchlist, which return overlapping 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=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that about ordering, what an item in the result looks like, or pagination interaction with the view modes, so it meets only the lowered bar set by 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?

A single dense sentence, front-loaded with the resource and immediately followed by the mode semantics. Every clause carries information; nothing is redundant with the schema or title.

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

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

For a 5-parameter read tool with no output schema, the description covers mode selection but says nothing about what the returned items are (episode vs show objects) or their ordering. It is adequate to invoke the tool but leaves the agent guessing about the result shape.

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 schema documents days, limit, offset and hide_unreleased, but the critical 'view' enum has no description in the schema — the description supplies the meaning of all four enum values, which is a real addition beyond structured data. It does this compactly and completely, though it does not clarify how days and hide_unreleased interact across the non-matching views (it leaves that to the schema).

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

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

States a concrete verb+resource ('Get next episodes') and enumerates all four view modes with a short gloss for each, so an agent knows exactly what data this returns. It doesn't distinguish itself from the sibling get_watchlist, even though the 'watchlist' view clearly overlaps with it.

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 parenthetical glosses implicitly tell the agent which view to pick for a given situation (in-progress vs caught-up vs all followed vs watchlisted), which is useful routing guidance. However, there is no explicit statement of when to prefer this tool over siblings like get_watchlist or get_sync, and no exclusions.

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 read-only and open-world nature, and the description adds value beyond them by disclosing that the response carries supporter status and API rate limits — a genuinely useful signal since the agent can use this call to inspect its quota. It also discloses the two-mode behavior (self vs. public profile). It stops short of describing error behavior for nonexistent users or privacy scoping.

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

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

One sentence with zero filler, and the primary outcome (profile, supporter status, rate limits) is front-loaded before the secondary mode. Nothing is repeated from the schema verbatim.

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 and only one optional parameter, the description is nearly sufficient: it names the key returned fields and both access modes. The remaining gap is minor — no mention of what happens when the requested username does not exist.

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 the single parameter already carries 'Omit for your own profile', so the schema does the heavy lifting. The description corroborates the self-vs-other distinction but adds no new syntax, format, or constraint detail beyond it.

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

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

Uses a specific verb ('Get') plus the resource ('user') and enumerates what is returned: profile, supporter status, API rate limits, or another user's public profile. The two access modes (self vs. other) are stated, which separates it from get_user_stats and get_user_lists, though those siblings are not named explicitly.

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

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

Usage is only implied: the agent can infer it should call this for profile data and can infer from the schema that omitting username yields the caller's own profile. There is no explicit guidance on when to prefer this over get_user_stats or get_user_lists, and no stated preconditions or failure cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered structurally. The description adds valuable behavioral context by excluding imported lists and specifying public-only access for other users, though it does not mention pagination or return shape.

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 the main operation and scope, followed by the exclusion and alternative. There is no redundant or filler text.

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

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

With readOnly/openWorld annotations and no output schema, the description covers enough for an agent to call the tool correctly: scope, exclusions, and the alternative for imported lists. It omits some parameter detail and pagination behavior, but those gaps are modest for this simple list tool.

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

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

Schema coverage is 67%, with username and unified documented but sort only represented as an enum. The description adds context for username ('another user's public lists') but does not explain sort values or unified merging, leaving some parameter meaning to the schema.

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

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

The description states a specific verb and resource ('List ... lists') and clearly scopes it to MDBList-made lists, distinguishing it from imported lists. It also explicitly routes imported lists to browse_lists, making the tool's purpose unambiguous against 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?

It gives clear context for use: the authenticated user's MDBList-made lists or another user's public lists, with an explicit exclusion and alternative for imported lists. It does not cover all sibling relationships, such as when to prefer search_lists, but the core routing 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 declare readOnlyHint=true and openWorldHint=true, so safety and reachability are covered. The description adds two useful facts beyond that: the data is 'precalculated' (i.e., cached/possibly stale rather than live-computed) and it is scoped to the authenticated user. It stops short of saying what the statistics contain or how fresh they are.

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

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

A single short sentence with the key qualifiers ('authenticated', 'precalculated', 'watch statistics') front-loaded. No filler, nothing repeated from the title.

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

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

With no output schema and no parameters, the description is the only place an agent can learn what comes back. 'Watch statistics' is not expanded (counts, hours, episodes, ratings?), so the agent knows the shape of the call but not the shape of the result. Adequate for invocation, thin for planning.

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 takes zero parameters and the description correctly implies no input is needed, matching the empty schema. Baseline 4 applies for a parameterless tool; nothing more was required.

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

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

States a specific verb and resource: retrieves the authenticated user's precalculated watch statistics. It clearly is not get_user (profile) or get_up_next (queue), but the description never names a sibling to sharpen the distinction. What counts as 'statistics' is also left generic.

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

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

Usage is only implied by the phrase 'authenticated user's', which suggests it works without arguments on the calling user's own data. There is no when-to-use framing, no mention of alternatives such as get_user or get_last_activities, and no exclusions. An agent can guess but is not guided.

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

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

The readOnlyHint and openWorldHint annotations already establish the safety profile. The description adds that the watchlist belongs to the authenticated user, implying authentication and personal data scope, but it does not describe pagination behavior, default ordering, or error 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 a single front-loaded sentence with no filler or repetition. Every word contributes directly to identifying the tool's resource and scope.

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 annotations cover the read-only nature, and the schema documents several pagination and filtering parameters. However, with no output schema and three parameters lacking schema descriptions, the description is still minimal for a tool with nine optional parameters and does not explain the returned item structure.

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 moderate at 67%, and the description adds no parameter meaning at all. Parameters such as sort, order, and mediatype have only enums and no descriptions, so the description does not compensate for those gaps.

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: get the authenticated user's watchlist items. It is clear what the tool retrieves, though it does not explicitly differentiate itself from sibling tools such as get_list_items or get_user_lists.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention add_watchlist_items, remove_watchlist_items, or custom-list alternatives such as get_list_items.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot convey: empty results for non-supporters and possible rejection under API-key access, which materially affects how an agent should interpret a response.

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 compact sentences with no padding; the core capability is front-loaded and the caveats follow in a logical order. Every clause conveys distinct 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?

For a simple read tool with no output schema, the description covers purpose, access caveats, and the empty-result case. It stops short of describing the link payload's shape or whether multiple providers per item are returned, which is a minor gap.

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 only 33%, and the description mentions 'movie or show' (mapping loosely to media_type) but says nothing about the provider enum values or the id format. The schema itself does document id with an example and both enums are self-explanatory, so the schema carries most of the load, leaving this at a 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?

States a specific verb (get) and resource (direct streaming/watch-provider links) scoped to a movie or show, and explicitly distinguishes itself from the sibling get_media_info, which 'also lists providers.' An agent can tell the two apart 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 concrete usage conditions: it is a supporter feature, returns empty for non-supporters, and may be rejected for API-key access. It also names get_media_info as an alternative provider source, though it does not say explicitly when to prefer that alternative.

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 this is a non-read-only, non-destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds the useful behavioral hint that a show can be marked as a whole rather than episode-by-episode. It does not explain what happens when watched_at is omitted (defaults to now?), whether existing history is overwritten given idempotentHint=false, or what happens to partially-watched show state.

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

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

A single front-loaded sentence with no filler and the key distinction stated immediately. It is efficient, though so terse that the efficiency shades into under-specification.

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 two-array mutation tool with full schema coverage, no output schema, and complete annotations, the essentials are present. Missing pieces an agent would want: whether watched_at defaults to the current time, whether marking a show cascades to episodes, and whether repeated calls duplicate history (relevant given idempotentHint=false).

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

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

Schema description coverage is 100%, including ID examples and the ISO 8601 format for watched_at, so the schema carries the parameter burden. The description only adds the mapping of 'movies' and 'whole shows' to the two arrays, with no extra detail on the watched_at default or whether either array may be empty (0 required params).

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

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

Specific verb (mark) plus resource (movies / whole shows) and the target (for the user). The 'movies or whole shows' distinction is genuinely informative and maps to the two top-level params. It stops short of naming the obvious sibling unmark_watched, so the inverse operation is left to inference.

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

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

Usage is implied by the name and one-liner: use it to record viewings. There is no explicit when-to-use versus rate_media, no note on whether marking a show also marks its episodes, and no guidance about authentication/current-user context despite the 'for the user' phrasing.

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=false, idempotentHint=true, and destructiveHint=false. The description's 'add or update' wording is consistent with the idempotent upsert hint and usefully confirms that existing ratings are overwritten rather than duplicated. It adds nothing about rating scale, auth, or per-item partial updates.

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

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

A single compact sentence with no filler or repetition. It is front-loaded and wastes nothing, though it is sparse enough that brevity shades into under-specification.

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 and full annotation coverage, the safety and mutation profile is conveyed. However, a two-array batch mutation tool that silently replaces existing ratings should say more: whether at least one of shows/movies is required, the rating range or scale, and the effect of re-rating an already-rated item.

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 ids, rating, and rated_at are already documented with examples. The description adds no parameter meaning, such as the rating scale (the schema only says 'e.g. 8'), whether both arrays may be sent, or whether omitting rated_at defaults to now. 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 ('Add or update') and resource ('user ratings of movies/shows'), so the agent knows this is an upsert on ratings. It does not explicitly distinguish itself from get_ratings or remove_ratings, leaving the sibling differentiation weak.

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 phrase 'Add or update' implies the create-or-modify use case, but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., authenticated user), and no reference to remove_ratings as the inverse operation.

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 destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the agent knows this mutates and is repeat-safe. The description adds only the 'static lists' constraint; it says nothing about what happens when an item is absent from the list, whether the removal is partial across movies/shows arrays, or whether error responses are returned.

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

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

A single front-loaded sentence with no filler, and the destructive action is stated first. It is efficient, though its terseness leaves real gaps rather than being maximally useful.

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, so the description should carry more of the response story for a destructive bulk operation, such as partial-success behavior or confirmation of what was removed. With rich annotations in place, the essentials are covered, but a destructive array-based mutation warrants a bit more.

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 IMDb/TMDb ID examples already documented, so the baseline applies. The description does not clarify whether the movies and shows arrays are mutually exclusive, whether either is optional alongside required list_id, or how multiple identifiers per object are resolved.

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 (remove) and resource (movies/shows in a user's static list), which distinguishes it from add_list_items. The 'static lists' scoping also loosely separates it from remove_watchlist_items, though it never names that sibling explicitly.

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

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

Usage is implied by the phrasing 'from one of the user's static lists', which hints the target must be a static list rather than the watchlist. But there is no explicit when-to-use guidance, no prerequisites (list ownership, item must exist), and no routing to the nearest alternative, remove_watchlist_items.

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 destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds valuable beyond-schema context by stating that watched status is kept, clarifying the boundary of what is removed. It does not describe permissions or failure behavior, so it is not a 5.

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

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

The description is a single, front-loaded sentence with zero wasted words. The key action and the preserved state are both stated immediately.

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 low-complexity destructive mutation with rich annotations and full schema coverage, the description is mostly complete: it says what is removed and what is kept. It does not clarify behavior when both optional arrays are omitted or when only some items fail, which is a minor gap for a bulk destructive 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%, so the parameters are already fully documented in the schema. The description does not add any parameter-specific meaning such as ID format, empty-array behavior, or whether arrays can be omitted. This matches the baseline of 3 when the schema carries parameter 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 states a specific verb and resource: remove user ratings for movies/shows. It also clarifies that watched status is preserved, which helps distinguish the effect from related state-changing tools. It does not explicitly name sibling alternatives such as rate_media, so it falls short of a 5.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives like rate_media, unmark_watched, or get_ratings. The implied use case is clear from the name, but there are no exclusions or alternative-selection instructions.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no behavioral context beyond the basic action, such as what happens if an ID is not present or whether authentication is required.

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, front-loaded sentence with no wasted words. It states the action and target immediately.

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 rich annotations, 100% schema coverage, and no output schema, the description is minimally adequate. However, it lacks detail on behavior for edge cases, return response, or distinction from remove_list_items, leaving clear gaps for a destructive mutation 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%, so the shows and movies array parameters are already documented in the schema. The description only mentions movies/shows generically and adds no further meaning about ID formats or array behavior.

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

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

The description uses a specific verb and resource: remove movies/shows from the user's watchlist. It is clear enough to distinguish from add_watchlist_items, but it does not explicitly differentiate itself from the sibling remove_list_items tool.

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 no guidance on when to use this tool versus alternatives such as remove_list_items or add_watchlist_items. It also omits any prerequisites or conditions for choosing it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful scope by saying only public lists are searched, but it does not explain result ordering, pagination behavior, or rate limits.

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

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

The description is a single front-loaded sentence with no wasted words. It is efficiently sized for a simple search tool.

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

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

For a three-parameter search tool with no output schema, the description is minimally adequate. It should say more about what is returned, such as list summaries or pagination, since no output schema exists to carry that information.

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 moderate at 67%: query and offset have descriptions, but limit does not. The description adds the idea that searching is by title, yet it does not clarify pagination parameters or compensate for the undocumented limit 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 states a specific verb and resource: search public lists by title. It is clear enough to distinguish from get_list and get_user_lists, though it does not explicitly differentiate from browse_lists or search_media.

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

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

Usage is implied by the word 'search', but the description gives no explicit guidance on when to use this instead of browse_lists, get_user_lists, or search_media. It lacks any when-not or alternative-tool context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no ranking behavior, no note that year matching is fuzzy (±1 is only in the schema), no result ordering or pagination context.

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

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

A single short sentence with the action and resource front-loaded and zero filler. It is efficient, though its brevity comes at the cost of any routing or filter 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?

For a six-parameter tool with an enum and no output schema, the description accounts for only one of those parameters and gives no sense of result shape or when to prefer it over discover_catalog. The schema and annotations carry nearly all the load.

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 83%, so the schema already documents query, year, limit, media_type, sort_by_score, and limit_by_score. The description only gestures at the query parameter and adds no semantics beyond what the structured fields provide; baseline 3 applies.

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

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

States a specific verb and resource: search movies and shows by title. An agent knows what the tool does, but the description never distinguishes it from siblings like discover_catalog or get_media_info, and 'by title' understates the actual filtering surface.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of the obvious alternative discover_catalog. The only hint is the implied 'you have a title, so search for it', which the agent must infer.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds no behavioral context beyond them — no statement about auth requirements, what happens if the person is not currently favorited, or whether the removal is reversible. It repeats the mutation that annotations already declare.

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

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

A single short sentence with zero filler and the action front-loaded. Its brevity borders on under-specification rather than padding, but nothing in it is wasted.

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

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

For a one-parameter idempotent toggle-off with complete annotations and no output schema, minimal phrasing is nearly sufficient. Still missing is what an agent would want before calling: the auth/user context implied by "the user's" and the no-op behavior when the person is not a favorite.

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 (tmdb_id) and schema description coverage is 100%, so the schema fully documents it. The description adds nothing about the identifier's format or source, which fits the baseline of 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Remove a person from the user's favorites") in one unambiguous clause. It is implicitly the inverse of favorite_person, but the description never names or contrasts with that sibling, so the differentiation comes only from the tool name.

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

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

There is no explicit guidance on when to use this versus favorite_person or remove_list_items / remove_watchlist_items, nor any precondition such as the person already being favorited. Usage can only be inferred from the name pairing, which the description does not reinforce.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful side-effect context beyond that: ratings survive the operation, and the granularity is whole shows rather than episodes. It doesn't mention return values or what happens on an empty request.

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

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

One sentence, front-loaded with the action and the target, with the preservation note in parentheses. No filler and nothing an agent must scroll past.

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 two-optional-parameter mutation with no output schema and rich annotations, the description covers what changes and what is preserved. Minor gaps remain: behavior with neither array supplied and whether episodes can be individually unmarked.

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

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

Schema description coverage is 100%, so both 'shows' and 'movies' arrays and their imdb/tmdb item fields are already documented. The phrase 'whole shows' adds a small semantic clarification about the shows array, but nothing is said about whether both arrays may be sent together or how IDs are matched.

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

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

States a specific verb and resource ('Remove the watched status') and scopes it to 'movies or whole shows', which immediately separates it from mark_watched. The parenthetical '(ratings are kept)' distinguishes it from remove_ratings without naming that sibling explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is the inverse of mark_watched, and '(ratings are kept)' hints at when to prefer it over remove_ratings. There is no explicit when-to-use/when-not-to-use guidance or statement of prerequisites.

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