ReelRecs

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

Beyond the readOnly/idempotent annotations, it discloses the result ceiling (twelve candidates), what each result carries (score, genres, cast, runtime, links), that an authorized connection adds personal Rec Score predictions, and the distinction between chart attention, new releases, chart market and availability country. It also explains what trending/rising/popular actually measure and how chart_freshness/chart_age_days qualify the data.

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 triggering phrases are front-loaded and most sentences carry distinct information (chart semantics, freshness, market vs availability). A few clauses are marginal or redundant with the schema, such as enumerating every returned field and the trailing "No ReelRecs account required" repeat of the earlier no-questionnaire point.

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

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

Given a nested request object, five sibling alternatives and an output schema, the description covers routing, the providers/country pitfall, chart definitions and freshness. The enumerated return fields are mildly redundant with the output schema but do not leave any gap an agent needs before calling.

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

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

Although reported schema coverage is 0%, the description supplies the key semantic traps: providers must be paired with constraints.country because country alone does not establish availability, genre/runtime/year/exclusion filters exist, and limit tops out at twelve. It does not explain variety, languages, offer_types, or the movie-vs-episode runtime split, so some nested parameters rely on the schema alone.

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

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

The description names a specific resource (U.S. audience charts) and a specific action (find current candidates, then judge fit for the viewer's mood), and opens with concrete triggering queries. It separates itself from recommend_titles/search_titles by stating no reference title or preference questionnaire is needed, so an agent can route correctly without opening the schema.

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

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

It explicitly says when to use it ("Start here for 'Netflix tonight'...") and when-not ("not live sports fixtures or broadcast schedules"), and clarifies it needs no account or seed title. The "find candidates first, then judge their fit" instruction gives a clear workflow, and the exclusions point the agent elsewhere for other 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 readOnly/idempotent/non-destructive/closed-world, yet the description still adds substantial non-obvious behavior: newest-first ordering, bookmarks:read permission requirement, conditional Your Rec Score field tied to personal recommendation permission, matched_count as the total for applied filters, and the warning not to infer watch history or likes from a save. Those are exactly the traps an agent would otherwise fall into.

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

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

Front-loaded correctly with the intent list, but the body becomes a dense run-on that mixes retrieval mechanics, pagination policy, response-field inventory, and downstream recommendation etiquette in one block. Most sentences earn their place, yet the volume of procedural advice ("show remaining fetched titles before fetching more...") makes it heavier than a tool definition needs to be.

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

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

For a single nested-request parameter with an output schema present, this covers everything an agent needs: filtering, paging, permission prerequisites, total-count semantics, and explicit negative constraints. The return-field list is redundant with the output schema but harmless and does not leave a functional 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?

The schema's own field descriptions are limited (kind has none, and top-level coverage reads as 0%), so the description compensates: query "searches the full list by title fragment", kind "filters movies or shows", and offset is expressed in terms of the returned next_offset cursor. limit is left to the schema, which is the only real gap.

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 — "Lists the connected viewer's own saves, newest first" — and enumerates the concrete user intents it serves (my bookmarks, watchlist, saved titles, "did I save this title"). The phrase "own saves" plus "Cannot read another account" cleanly separates it from sibling tools like search_titles and get_my_ratings.

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

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

Gives clear when-to-use triggers (browse my list, verify a save, pick from my list) and scope exclusions (cannot read another account, cannot add/remove saves), which implicitly routes write or cross-account needs elsewhere. It also nudges toward check-watch-options behavior. It stops short of naming the specific alternative siblings, so it is strong but not fully explicit about the 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond them: an auth precondition (connected ReelRecs account) and a privacy boundary ('Never exports full history'). It does not describe failure behavior when the account is not connected.

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

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

Four short sentences, no repetition, and the return fields are named precisely. The usage sentence sits in the middle rather than up front, and the precondition could be merged more tightly with the purpose sentence, but there is no filler.

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

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

An output schema exists, so return values need not be spelled out, yet the description still flags the key field path (streaming_preferences.services). With zero parameters and rich annotations, the addition of the auth precondition, the sibling relationship, and the privacy limit makes the definition complete for an agent to call it correctly.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no words on arguments.

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

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

The description names the concrete return payload (display identity, saved-taste availability, streaming_preferences.services), so the agent knows exactly what this tool yields. It also separates itself from get_watch_options by noting that tool matches offers to the preferences returned here. The leading sentence is a precondition rather than a purpose statement, which slightly blunts the front-loading.

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 an explicit trigger ('Use these when the viewer asks about their services') plus a prerequisite ('Requires a connected ReelRecs account') and relates the tool to get_watch_options. It stops short of stating when not to call it, e.g. what to do if no account is connected.

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

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

Beyond the readOnly/idempotent annotations, it discloses the required ratings:read scope, an account boundary ('Cannot read another account or change ratings'), a 50-per-page cap with next_offset paging, and that a successful lookup confirms the connection. These are exactly the operational facts an agent needs and that annotations do not carry.

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

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

It is front-loaded with the core browse verb and the key mode switch, and every sentence is largely functional. It becomes a bit run-on in the taste-analysis passage and carries an optional stylistic instruction ('Curate a few picks... personal predictions are secondary') that reads as padding in a tool definition.

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

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

With an output schema available and annotations covering safety, the description still supplies scope, limits, pagination, and account boundaries, which is close to complete. The closing line 'A successful lookup confirms the connection' is vague and slightly ambiguous about what the return actually confirms.

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 real meaning around title_ids (must be resolved, max ten, omission switches to browse mode, returns confirmed absence) and around pagination and sort intent. Much of this overlaps the schema's own field descriptions, so it is reinforcement rather than purely new information.

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 specific verbs and resources: browsing the viewer's own rated movies and shows, or looking up whether specific titles were rated. It explicitly separates this from bookmarks ('independently of bookmarks'), from audience scores, and from personal predictions, so an agent can tell it apart from siblings like get_my_bookmarks or recommend_for_me.

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 an explicit branching rule: omit title_ids to browse the full list, or supply up to ten resolved title_ids to check specific titles including confirmed absence. It also states the procedure for the harder case ('read all pages and use both high and low ratings') and names bookmarks as a distinct resource.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-structured context: the watchplus:read permission requirement and the negative-space guarantee that emails and pending invitees are never returned, which matters for privacy-sensitive answers.

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?

Dense and front-loaded: scope first, then output contents, then the follow-up tool and tie-break rule. Every sentence carries information, though "Proceed directly when the people are clear" is a slightly loose autonomy hint that could be tightened.

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

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

With an output schema present, the description need not describe return fields, and rich annotations cover safety; auth and result-set exclusions are still spelled out. The one real gap against tool complexity is that result-set sizing and pagination are never mentioned despite limit/offset params.

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 reported as 0% for the nested request, so the description must compensate. It does explain the query semantically (group or member name; match usernames to disambiguate duplicates) but says nothing about limit (default 10, max 20) or offset paging, leaving pagination behavior undocumented in both places.

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?

"Find the connected viewer's accepted Watch+ groups by group or member name" names a specific verb, resource, and scope, with an example query (Jenna). It is clearly distinguishable from recommend_for_group and search_titles, though it never explicitly contrasts with get_watchplus_context, which is the nearest sibling by 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?

It routes the agent forward ("Use these IDs ... then recommend_for_group") and gives a concrete tie-break rule: prefer the smallest matching group when people overlap, unless the viewer names one. What is missing is an explicit when-not/alternative case, e.g. when to call get_watchplus_context 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 cover readOnly/idempotent/non-destructive, and the description adds meaningful selection semantics: candidates are not personalized, do not represent a shared rater group, and no peer average is computed. It also discloses that missing scores are null and streaming offers are excluded, which prevents the agent from misreading the payload.

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

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

Front-loaded with the core purpose, but the middle sentences are convoluted and partly redundant ('do not represent a shared group of raters' and 'no peer average is calculated' restate the same idea). The 'without audience-score or viewing/rating-affinity selection' phrasing takes effort to parse.

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

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

An output schema exists, so restating the return fields is optional; the more valuable content is the disclaimers about what the peers are not, which are present. What is missing is how this differs from recommend_titles and how to supply a resolved title_id, both material for a comparison tool with a nested request object.

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 never mentions title_id or limit; all parameter meaning lives in the nested schema. Reported schema coverage is 0% at the top level, so the description should have compensated by noting the resolved-id requirement and the soft, non-fixed limit — it does neither.

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 verb 'Find' and scope 'one resolved movie or show' are clear, but the object is described as 'optional content references', which is vague jargon for what the schema calls 'reference candidates' (similar titles). The title 'Compare similar movies or shows' is clearer than the description itself, and no sibling tool (recommend_titles, search_titles) is named for contrast.

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?

'when a comparison is useful' is an implied trigger rather than an explicit one, and no alternative is named. The negative framing (candidates are not audience-score or viewing/rating-affinity selected) does implicitly separate it from recommend_for_me, which is real usage guidance, but the agent must infer that routing decision itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely new behavior: offer categories are kept separate (subscription, free/ad-supported, rental, purchase), rentals/purchases still cost extra even when matched, an empty or stale result does not prove unavailability, and no account is needed for public offers. The personal-access enrichment (streaming_preferences.services, matches_saved_service) is disclosed as a conditional behavior change.

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

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

Front-loaded with purpose and workflow, then caveats. Every clause carries information, though a few statements (return field lists) duplicate what the output schema already provides and could be trimmed.

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

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

An output schema exists, so the return-field enumeration is partly redundant, but the description still supplies what the schema cannot: auth tiers, ranking preference for included offers, and the unavailability caveat. The main missing piece is any guidance on the country parameter.

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 real meaning for title_ids (ten-item cap, must be exact IDs from search_titles) and corrects the temptation to pass names. However, it never mentions the country parameter or its US default, which is a substantive input the agent must choose deliberately. With reported low schema coverage, that omission leaves a gap.

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

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

States a specific verb and resource ('Find where to watch a movie or show') and immediately distinguishes scope by including the viewer's saved services. It also names the sibling tool search_titles as the prerequisite resolver, so the agent can place it in the workflow without reading other definitions.

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

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

Explicit sequencing guidance: 'Resolve names with search_titles first, then pass up to ten exact IDs', plus a usage rule ('Use saved services without asking the viewer to repeat them') and a framing instruction for presenting included offers. It lacks explicit when-not-to-use conditions, which keeps it below the top score.

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/idempotent/non-destructive/closed-world, so the safety bar is met without prose. The description still adds meaningful context beyond them: required scope watchplus:read, the privacy and block boundaries, the explicit exclusion of strangers, pending invitations and private chats, and the epistemic caveat that 'missing evidence is unknown.' It also pre-empts a likely misinterpretation by noting similar saved titles show overlap but are not causal explanations of scoring.

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

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

Purpose is front-loaded in the first two sentences, which is good, but the body is a dense run of short declaratives with compressed jargon ('Watch+ interest/pass', 'resolved title IDs', 'evidence beyond the overview examples') that reads as terse rather than efficient. Several clauses, such as the scoring-model causality caveat, are valuable but buried at the end where an agent may skim past them.

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

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

With an output schema present, return values need no explanation, and the nested request object is small enough that the schema covers its fields. The description supplies the authorization scope, privacy boundaries, and the 'missing evidence is unknown' fallback that an agent needs in order to interpret empty or partial results. The remaining gap is the absent statement of when this beats a sibling tool for the same user question.

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?

Reported schema coverage is 0%, so the description carries weight here, and it does add some: 'up to ten resolved title IDs' and 'selected accepted group members' map to title_ids and member_ids respectively, and it lists the per-person signals returned (prediction, saved rating, Watch+ interest/pass, saved references). It does not explain group_id or the member_ids roster/default semantics, which the nested schema does document inline; the description therefore adds partial rather than decisive meaning.

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

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

The description names a specific verb and resource: 'Explore the selected accepted group members' accessible tastes,' and states what comes back ('liked and less-liked examples and descriptive patterns'). It is clearly a group-taste inspection tool rather than a recommendation generator, but it never names a sibling such as recommend_for_group or get_my_watchplus_groups to sharpen the boundary.

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

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

Use is implied by 'Helps explain shared appeal, differences, reservations and compromises,' which tells the agent this is an explanation/diagnostic tool rather than a discovery tool. However, it gives no explicit when-to-use or when-not-to-use rule, and no guidance on choosing this over recommend_for_group when the user asks about group taste.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description adds substantive context beyond them: requires watchplus:read and current accepted membership, privacy and blocks are re-checked before returning, seen titles are excluded unless allow_rewatch, and predictions require fresh completed scores with missing coverage never implying agreement. Those are real operational caveats an agent cannot infer from 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?

Front-loaded with the purpose and the prerequisite, then dense operational rules in a single tight paragraph with no filler. It is on the long side and packs several distinct rules together, but each sentence contributes a constraint or caveat rather than restating the name.

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

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

For a nested-request tool with an output schema, the description covers everything the agent needs: prerequisites, auth scope, exclusion defaults, prediction-freshness caveats, privacy re-checks, and how many candidates come back. Return-value formatting is correctly left to the output schema.

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 top-level schema exposes a single 'request' object, so the description carries weight in explaining semantics: focus, votes being lower priority without changing predictions, allow_rewatch, mood/reference inputs, and streaming filters. It does not mention limit, intent, qualities, member_ids, avoid_seed_ids or use_saved_services by name, though the nested schema documents those thoroughly.

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

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

States a specific verb and resource: choosing what a group of accepted Watch+ members watching together might enjoy. The framing (group session, up to twelve candidates for the assistant to curate into two or three) makes it clearly distinct from recommend_for_me and recommend_titles without opening any schema.

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

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

Gives concrete ordering guidance — resolve the group and people with get_my_watchplus_groups first — and conditions for focus=all_titles versus the default balanced fit. Also tells the agent not to demand a questionnaire and to use mood/references/streaming filters when known. It never explicitly states when to prefer recommend_for_me or recommend_titles over this tool, which keeps it below a 5.

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

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

Annotations already establish a safe read-only, idempotent, non-destructive closed-world operation. Beyond that, the description discloses the return size and contents, ten-point score scale, null missing predictions, the qualities_applied field, saved-service usage, and that an authorized account is required and no account identifier is accepted.

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

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

Front-loads the trigger and the key alternative before moving into ranking behavior, return shape, and exclusions. It is dense and slightly repetitive around 'saved taste,' but nearly every sentence earns its place.

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

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

Complete for a complex nested personalization tool: it explains authentication, source of preference signal, return format and score handling, rewatch and service behavior, and the chart alternative. The output schema exists, and the description still adds enough to call it correctly.

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

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

The nested schema documents many fields in detail, but the description adds useful relational meaning: positive and disliked reference titles map to seed and avoid inputs, desired qualities map to mood constraints, watched titles are excluded unless rewatch is requested, and saved streaming services can be used. It still leaves the intent enum values and limit shortlist behavior to the schema.

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

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

States a specific verb and resource: ranks the wider catalogue by saved taste, incorporating liked and disliked references plus desired qualities. It explicitly distinguishes itself from the charts sibling for mood-only starts and clarifies that it uses lasting saved preferences rather than transient mood.

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

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

Gives an explicit trigger, 'when the viewer asks to explore their saved taste or the wider library,' and routes open-ended 'Netflix tonight' or 'What should I watch?' requests to get_charts first even when connected. It also states the watched-title exclusion unless rewatch is requested, and the authorization requirement.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered; the description adds real behavioral detail beyond that: up to twelve candidates, what each candidate carries, that general similarity sets the neighborhood while intent shifts evidence emphasis, that dislikes adjust affinities versus exclusions hiding exact titles, and that qualities_applied reveals whether mood text influenced ranking. It stops short of describing pagination or latency, but for a read-only recommendation call this is substantial added 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?

Front-loaded with the use case, then prerequisites, then return shape, then semantics — a sensible order with no filler sentences. Some sentences are heavy with semicolon-joined clauses ('General similarity supplies the neighborhood; intent selects the supporting evidence emphasis'), which trades readability for density, so it is efficient but not maximally clean.

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 nested-request tool with constrained IDs, country/provider interactions, and several sibling alternatives, the description covers routing, key parameter relationships, and the return payload. With an output schema present it does not need to enumerate return fields exhaustively, and what it does say about candidates and qualities_applied is sufficient 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?

The description explains the semantic division between positive seeds, disliked seeds, and exclusions ('Dislikes adjust comparable affinities; exclusions hide exact titles') and clarifies that qualities express the desired experience rather than saved taste. Unmentioned fields (kind, variety, genres, languages, offer_types) are left to the schema, and because the reported coverage signal is low those remain partly undocumented, which keeps this from a 5.

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

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

The opening sentence gives concrete verb+resource phrasing with three recognizable use cases: 'Find movies like X, shows to watch after Y, or alternatives when someone liked one title but disliked another.' It explicitly routes to siblings ('Resolve names with search_titles first', 'use get_charts first'), so an agent can distinguish it from search_titles, get_charts, and recommend_for_me without opening the schema.

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

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

It names prerequisites (resolve names with search_titles first) and a clear alternative path (get_charts for open-ended or mood-only starts). It also states when constraints do and do not take effect ('Provider filters apply in the requested country; country alone does not filter availability'), which is exactly the kind of boundary guidance that prevents misuse.

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

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

Annotations only declare this is a non-idempotent, non-destructive write; the description goes well beyond that by stating reports are unverified observations, cannot change saved ratings or taste, are subject to host approval controls and viewer opt-out, and return a receipt acknowledgement. It also sets a firm one-report-per-signal rate limit, which the annotations do not convey.

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 paragraph is front-loaded with purpose and then layers constraints in roughly priority order, with no filler sentences. It is dense and somewhat run-on — several rules (evidence types, confidence limits, excluded content) are packed into single clauses, making it easy to skim past 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 nested-object write tool with an output schema, it covers the essential burdens: privacy exclusions (no transcripts, identity, credentials, sensitive details), evidence integrity, and the fact that reports have no effect on recommendations. The only real hole is that 'when permitted by viewer and host' leaves the agent without a way to verify the precondition before calling.

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 reported as 0%, so the description must carry the load, and it does for most fields: reference_request_id must be copied and never invented and grants no access, title_ids are copied from results with a five-item cap, and summary is a ≤300-character paraphrase. It falls short on the seven enum values for 'category' and 'reaction,' which are never mapped to concrete situations, leaving the agent to guess at 'constraint_missed' versus 'tool_problem'.

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

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

The description opens with a specific verb and resource — 'Record a brief quality report' — and narrows the scope to 'a meaningful acceptance, rejection, correction or concrete problem with ReelRecs results.' No sibling tool in the list does anything similar (all others are retrieval/recommendation), so an agent can identify this as the sole feedback-capture tool without opening the schema.

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

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

It gives real when-to-use signals: only 'when permitted by the viewer and host,' 'at most one report per new signal across ReelRecs tools,' and explicitly 'silence or continued use is not evidence of a reaction.' The main gap is that the permission gate ('when permitted by the viewer and host') is named but not operationalized — the agent isn't told how to determine permission.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: fuzzy matching tolerates misspellings and fragments, results carry canonical IDs that must not be guessed, and the payload includes description, genres, tags, cast, directors, language and runtime. It does not mention result cap or ranking/ambiguity handling.

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

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

Front-loaded with the core action, followed by sequencing, then return contents — a sensible order with little filler. The closing sentence about 'viewer-mentioned titles or assistant-chosen mood references' is vague and slightly dilutes an otherwise tight definition.

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

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

An output schema exists, so the enumerated return fields are a bonus rather than a necessity. For a single-parameter search with a nested request object, the definition covers purpose, precondition, and fuzzy-match tolerance; the gap is the undocumented kind/limit controls inside the nested object.

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 reported at 0%, so the description must compensate; it explains the query semantics well ('remembered fragment or a typo') and gestures at version resolution, which maps to the year field. However, the nested request object's 'kind' (movie/show/any) and 'limit' controls are never mentioned, leaving half the nested surface undocumented.

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

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

States a specific verb and resource ('Find a movie or TV show') and immediately broadens the input tolerance to fragments and typos. It also scopes the output ('canonical IDs and rich title context'), which separates it cleanly from siblings like get_title_peers or get_watch_options that consume an already-resolved title.

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

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

Gives explicit sequencing guidance: 'Resolve its exact version before recommendations or availability checks,' which tells the agent to call this before recommend_titles/get_watch_options. It stops short of naming those siblings or stating when NOT to use it (e.g., browsing rather than searching).

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