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

Annotations already cover read-only, idempotent, non-destructive and open-world, so the bar is lower; the description still adds real behavioral context by disclosing that Filimo rows carry year, rating, IMDb and summary while Namava rows only carry title, kind and id. It does not discuss rate limits or failure behavior when a genre string is unrecognized, which keeps it short of a 5.

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

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

Front-loaded with purpose, then examples, then return-shape differences, then next steps and the exclusion — a sensible priority order with no filler. The telegraphic fragments ("Next: vod_title or vod_episodes") are dense but each clause carries 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 7-parameter browse tool with no output schema, the description covers what rows look like per site and which sibling to use next, which is the information an agent actually needs to sequence calls. Pagination depth and the genre-name list are delegated to the schema and vod_genres, which is reasonable but leaves genre lookup slightly implicit.

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 every one of the 7 parameters is already documented in the schema, including that sort and country are Filimo-only and that Namava ignores kind. The description only echoes the Filimo-only nature of sort and country filters, adding no syntax, format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (list movies and series of one genre) plus the two catalogs it covers, and immediately distinguishes itself from vod_title, vod_episodes and vod_collections by name. An agent can tell this apart from the search/browse siblings 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 quoted example intents ("best comedy series on Filimo", "Iranian dramas", "new documentaries"), names the follow-up calls (vod_title, vod_episodes), and explicitly routes themed lists (IMDb top 250, Oscar, kids, coming soon) to vod_collections instead. That is an explicit when/when-not/alternative mapping.

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 it is a safe, idempotent read. The description adds real behavioral context: Filimo lists reach ~200 titles and accept sort/country, Namava lists are fixed in newest or editorial order, 'upcoming' marks undated titles, and the 'kids' key expands into multiple rows rather than a single list.

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

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

Front-loaded with the purpose, then sequencing, then provider-specific caveats — no filler. The middle sentence is dense and packs several unrelated facts (titles reach, ordering, upcoming flag, kids key) but each 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?

For a six-parameter read tool with no output schema, the description covers what comes back (titles plus refs usable by vod_title) and the provider-specific quirks an agent would otherwise discover by trial. Pagination limits and the exact return shape stay implicit, which is the only shortfall.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning beyond it by tying sort/country to Filimo only and noting sort does not apply to the kids age keys, plus the ~200-title reach that informs paging. It does not restate kind/page/limit, which the schema already covers.

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 and resource ('Show the titles of one curated list on Filimo or Namava') with an example list, and implicitly contrasts with vod_collections, which supplies the key. An agent can distinguish it from vod_search/vod_browse without reading the schema.

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

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

Gives an explicit pipeline: use after vod_collections, then vod_title with a returned ref. It also clarifies which sub-features apply where (sort/country only on Filimo). It stops short of saying when NOT to use it versus vod_browse or vod_featured, so not a 5.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuine workflow context beyond that: entries carry a `key` consumed by vod_collection, and any vod_genres slug works as `namava:category:<slug>`. It doesn't say anything about result size or pagination, but for a read-only listing tool with full annotations the bar is low.

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 with examples, followed by the use trigger and the chaining detail. Three short lines with no filler, though the trailing `namava:category:<slug>` sentence packs a second concept into what reads like a parenthetical aside.

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

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

For a one-parameter read-only listing with no output schema, the description covers what the tool returns at a high level (entries with a `key`) and how to use it. It leaves the entry shape otherwise unspecified and says nothing about ordering or result volume, which are minor given the tool's simplicity.

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 a single parameter at 100% schema description coverage and an enum, the schema fully documents `site`. The description only echoes the two site names and adds no detail on default or how 'both' results are distinguished. Baseline 3 is appropriate.

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

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

"List the curated lists vod_collection can open on Filimo and Namava" gives a specific verb, resource, and scope, and explicitly ties itself to the sibling vod_collection. The concrete examples (IMDb top 250, Oscar, kids, coming soon) remove any ambiguity about what a "collection" is here.

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 when the user asks for a themed list (best-of, festival winners, kids, Korean or Turkish series, true stories)" is a clear use trigger, and it names the follow-up tool (vod_collection) that consumes the returned key. It stops short of explicit exclusions – it never says to prefer vod_genres or vod_search for non-themed queries, and the namava:category note blurs the line with vod_genres.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: a movie ref produces an error rather than an empty result, the default season is the latest, and streaming links are deliberately omitted from the output.

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 paragraphs with the purpose front-loaded and the operational caveats second. Minor duplication of the 'default season is the latest' fact already present in the season schema description keeps it from being fully waste-free.

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 does the necessary work of naming the returned fields and flagging that streaming links are absent. Pagination semantics for limit (e.g., whether more episodes exist beyond the cap) are the one notable remaining 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 100%, so ref, limit and season are already fully documented, including that the season default is the latest. The description's only added meaning is the series-vs-movie ref constraint, which is a useful but small increment over the schema's pattern and descriptions.

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

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

States a specific verb and resource ('List the seasons of a series and the episodes of one season') and even enumerates the returned fields (title, summary, length, publish date). It is clearly distinguishable from vod_search and vod_title, which are named as the upstream discovery tools.

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

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

Gives explicit triggers ('when the user wants episodes, how many seasons exist or the newest episode') and explicit sequencing ('Use after vod_search or vod_title'), plus a when-not condition: a movie ref returns an error. This is close to complete routing 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, idempotentHint, openWorldHint and destructiveHint=false, so safety and idempotency are covered. The description adds genuinely non-obvious behavior: results are editorial/curated rather than metric-driven, and returned refs are designed to be chained into vod_title. It stops short of describing pagination or how many rows come back per site.

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

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

Three sentences, front-loaded with the resource and scope, then the use case, then the routing alternatives. The parenthetical row list is compact and informative rather than padding; nothing is redundant with the annotations 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 does the necessary work of sketching the return shape (per-site rows, slider, list) and the ref-chaining path onward, and all three params are covered by schema descriptions. It could be slightly more complete about row counts or what 'both' returns in terms of volume, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so the enum meanings for kind and site and the per_row bounds are already fully documented. The description only indirectly reinforces parameter behavior by describing which rows exist per site, which adds little beyond the schema text. Baseline 3 applies when the schema carries the semantic load.

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?

Names a specific verb+resource ('Show what Filimo and Namava promote right now') and enumerates the exact surfaces returned (Filimo front-page rows: new, popular, box office, genres; Namava top slider and top list). It also explicitly distinguishes the content type — 'editorial picks, not view counts' — which separates it from sibling tools like vod_search or vod_collection.

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 use case ('what is popular / trending on Filimo or Namava') plus two named alternatives with conditions: vod_title for details from a ref, and vod_collection(key="namava:popular") for Namava's most-viewed list. That is close to textbook when/when-not routing, with only a mild unaddressed overlap with the vod_new sibling for the 'new' row.

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, so the safety profile is covered. The description adds genuinely new behavioral context: the list is cross-site (Filimo and Namava), Persian names are portable across both, and Filimo-specific filters (sort, country) live in vod_browse rather than here. It stops short of describing the return shape or ordering, which keeps it below a 5.

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

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

Three short sentences, front-loaded with what the tool returns, then when to call it, then the accepted name forms. The parenthetical cross-reference to vod_browse earns its place and nothing is repeated from the 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 zero-parameter lookup tool with no output schema, the description covers everything an agent needs: what is returned (genre names plus aliases), which sites are covered, and how to consume the result. No missing prerequisite or return-format gap remains.

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 the baseline is 4 and there is nothing for the description to disambiguate. It does usefully note that site-specific filtering belongs to vod_browse, implicitly clarifying that no filtering arguments exist here.

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

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

States a specific verb and resource ("List the genre names") and immediately scopes it to what vod_browse accepts for Filimo and Namava, including English aliases. An agent can distinguish this reference-list tool from vod_browse without opening either schema.

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

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

"Use before vod_browse when unsure of a genre name" gives an explicit trigger condition and names the sibling tool it feeds. It also resolves the main ambiguity up front by stating that both Persian names and English aliases (comedy, drama) are accepted, so the agent knows what to do with the output.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive) and open-world reach. The description adds behavior annotations cannot express: payload asymmetry between sources, with Filimo returning year, rating and summary while Namava returns only title and kind. It stops short of stating pagination or ordering guarantees for merged results.

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

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

Three short sentences, front-loaded with the core action and ordering, then usage triggers, then alternatives. No filler and nothing repeated from 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?

No output schema exists, so the description must carry return-value information, and it does by differentiating Filimo and Namava payloads and pointing to vod_title for the missing fields. Combined with usage routing and annotation-covered safety, an agent has enough to call it correctly.

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

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

Schema coverage is 100% and all three parameters are documented with enums and defaults, so the baseline is 3. The description earns an extra point by explaining that the site parameter changes the shape of results (two lists under 'both', thinner Namava payload), which is semantics the schema does not convey.

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 action (list newest titles added) against named resources (Filimo and Namava) with an explicit ordering rule (most recent first). This is clearly distinct from vod_featured and vod_search without needing to open either schema.

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

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

Gives a concrete trigger phrase ("what is new on Filimo/Namava") and explicitly routes two alternative intents elsewhere: vod_title for fuller details and vod_featured for front-page promotions. Both when-to-use and when-not-to-use are present.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world), and the description adds substantial non-obvious behavior: Filimo returns birth date/place while Namava returns bio text, the name matches the first search hit with exact matches preferred, `other_matches` holds near-name people, and series are deduplicated rather than listed per episode. These quirks materially change how an agent should interpret and present results.

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 clause, and later sentences are dense with useful specifics rather than filler. Slightly compressed phrasing ('Titles carry a `ref` for vod_title') asks the reader to infer the relationship, 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?

With no output schema, the description still tells the agent what comes back (bio, birth data per site, title list, `ref`, `other_matches`, deduplicated series) and how input names resolve. For a 3-parameter read tool, nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes further by explaining how `name` resolution works (first hit, exact name first, similar names surfaced via `other_matches`). It leaves `limit` semantics to the schema ('Max titles per site'), which is adequate but keeps it 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?

States a specific verb and resource ('Look up an actor, director or writer on Filimo and Namava') plus the payload ('short bio and the titles they appear in'). It also separates itself from vod_title by noting that returned titles carry a `ref` for that tool, so an agent can route correctly without opening sibling schemas.

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

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

Gives an explicit trigger phrase: use for "what has X acted in / directed on Filimo or Namava". It does not spell out when to prefer vod_search or vod_where instead (e.g., for unknown names or browsing-only queries), so guidance is clear but not exhaustive.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description focuses on what annotations cannot express: prices are pre-VAT toman amounts, and the distinction between list price, new-user price, and the auto-renewing monthly plan. It also discloses a real data-provenance limitation (Filimo pricing absent from the JSON API), which prevents a wasteful call.

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 usage trigger, with field definitions in a compact second block. The only waste is the Filimo caveat appearing twice — once as a parenthetical and again at the end with the URL — which could have been a single statement.

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 no-parameter, read-only lookup with no output schema, the description covers everything an agent needs: when to call it, what the returned fields mean, currency/tax basis, and the one case where data is unavailable. Nothing material is left to inference.

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

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

There are zero input parameters, so the baseline is 4. The description instead spends its effort defining the returned price fields (price, price_new_user, auto_renew), which is valuable given no output schema exists, though it does not describe ordering of plans or count of plans returned.

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

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

Opens with a specific verb+resource ("Show Namava's public subscription plans and prices") and immediately delimits scope with the parenthetical that Filimo prices are not in its JSON API. An agent can distinguish this from sibling tools like vod_title or vod_search without opening the schema, since none of them concern pricing.

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 phrase ("Use for 'how much is a Namava subscription'") and simultaneously states when-not/where-else: Filimo prices are only on the payment page, with the URL supplied. The routing decision is fully determined by the description.

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 a safe, idempotent, read-only, open-world call, so the description's added value is the provider divergence: Filimo returns related rows (same actors, writer, genre, decade) plus featured actors and writers, while Namava returns a single recommendation list. That is real behavioral context an agent cannot get from annotations, though pagination/truncation behavior is not mentioned.

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 sentence, followed by sequencing and chaining guidance in two short sentences. The parenthetical provider caveats are dense but each carries information; only light trimming would improve it.

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 does the expected work by sketching what each provider returns, including the extra related-row and actor/writer payloads on Filimo. It is not exhaustive about the shape of the recommendation list itself, but enough for an agent to call and interpret it.

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% — both `ref` (with a regex, examples and source tools) and `limit` (default 12, max 20) are fully documented in the schema. The description only adds that a `ref` can also come from a vod_title result, which is marginal but slightly extends the schema's stated provenance.

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

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

States a specific verb and resource (list similar titles for one movie or series) and qualifies it across the two providers Filimo and Namava, with the colloquial gloss "viewers also watch". It is clearly distinct from vod_title (which resolves one title) and vod_search (which finds titles by query).

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 after vod_title when the user wants more like it" gives an explicit trigger and ordering, and "Take a `ref` from the result to vod_title" documents the chaining in both directions. It stops short of naming when not to use it, e.g. browsing a whole genre, which is what vod_browse/vod_genres are for.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavior beyond them: every hit carries a `ref` for chaining, and the return shape differs by site (Filimo returns year, rating, genres and summary; Namava returns only title, kind and year). With no output schema, that asymmetry is important 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?

Four short sentences, front-loaded with purpose then routing then return-shape caveat. Nothing is filler, though the final clause packs two site-specific behaviors into one compound sentence that could be split for easier scanning.

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 search with a fully documented schema and no output schema, the definition covers purpose, routing, chaining, and per-site return differences. It stops short of stating behavior for zero results or how `limit` interacts with the combined two-site response, which would fully close the loop.

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 enums on `kind` and `site` and bounds on `limit`, so the schema does the heavy lifting. The description implies the query is matched against titles but adds no format, matching, or limit semantics beyond what the schema already documents. 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 (search) plus the exact resources (Filimo and Namava catalogs) and the retrieval mode (by title, returning movies and series with a ref). The scope is immediately distinguishable from sibling browse/where tools.

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

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

Gives an explicit trigger ('Use first when the user names a title'), names the alternative for the other case ('Use vod_where instead to learn which service has one specific title'), and routes follow-up steps to vod_title and vod_episodes via the ref. When-to-use, when-not, and alternatives are all present.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value on top: rating fields differ per site (Filimo stars/5 with vote count and IMDb vs Namava like/dislike counts) and cast semantics differ (Filimo movie cast is scraped from description text, series cast is a few featured actors). Those are meaningful data-quality caveats an agent should know before reading results.

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

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

It is front-loaded with purpose, then usage chaining, then per-site caveats, with no filler or repeated phrasing. The per-site rating and cast clauses are dense but each carries information an agent cannot get 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 single-ref read tool this is complete: annotations cover mutability and idempotency, the description enumerates the returned fields despite there being no output schema, and it explains how the ref relates to sibling tools. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema description already lists the accepted formats and examples ('filimo:0bd4p', 'namava:series:2377'). The description only reiterates that the value comes from a prior search hit, adding no format or constraint detail beyond the pattern in the schema, so the baseline 3 applies.

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

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

The first sentence gives a specific verb and resource ('Get full details of one movie or series on Filimo or Namava') and enumerates the returned fields (synopsis, genres, year, rating, age rating, cast, director). It is unmistakably distinct from vod_episodes, vod_related and vod_person, which are named later as follow-ups.

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

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

It states the prerequisite explicitly ('Use after vod_search, vod_browse or vod_new with the `ref` of a hit') and then routes onward ('For a series, follow with vod_episodes', 'vod_related gives similar titles and vod_person a cast member's filmography'). Both what selects this tool and what comes next are spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the match ordering (exact title first, then titles containing the words), the returned keys (per-site matches and available_on), and the catalog-only scope limit. It stops short of describing result limits or what happens when nothing matches.

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

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

Front-loaded with the core purpose and the trigger question, then scope limits and handoffs. Tight overall, though the final sentence about passing vod_search results to vod_title is a workflow note rather than information about this 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?

With no output schema, the description compensates by naming the returned fields and match ordering. For a two-parameter, annotation-covered read tool this is nearly complete; only empty-result or result-count behavior is unstated.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the year's remake-disambiguation purpose. The description adds no further semantics about title format or year handling, 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 ('Tell which of Filimo and Namava carries a title') plus the mechanism (searches both catalogs and matches title text). An agent can distinguish it immediately from vod_search (discovery) and vod_title (details), both of which are named.

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 phrase ('is X on Filimo or Namava') and an explicit exclusion: it only checks catalogs, not subscription requirements, and routes that need to vod_title. It also points to vod_search as the upstream step, so the when/when-not/alternative triad is fully covered.

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