rotv-mcp

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

Annotations already indicate a safe read-only operation; the description adds concrete behavioral details about the reported metrics (last-updated time, age, next refresh, staleness condition), going well beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and conveys all necessary information without redundancy.

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

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

Given low complexity, high schema and annotation coverage, and the presence of an output schema, the description adequately covers all behavioral aspects and outputs, leaving no significant gaps.

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

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

Schema coverage is 100% with one parameter, and the description reinforces meaning by listing the data sources, aligning with the enum values. It adds slight contextual value beyond the schema's description.

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

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

The description clearly states the tool reports last-updated time, age, next refresh, and staleness for specific data sources, using strong verbs and distinguishing itself from sibling tools that focus on recommendations or schedules.

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 does not explicitly state when to use this tool versus alternatives, nor does it provide context on prerequisites or when not to use it. The purpose is clear enough to infer but lacks explicit 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, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: scoring against mood, default 48h window, streaming lookup, and output format (side-by-side, winner). No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose. Every word is necessary; no redundancy.

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

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

Covers most aspects: inputs (2-5 titles, mood, window), process (scoring, airing, streaming), output (breakdown, winner). Missing explanation of 'prefer' parameter. Output schema exists, so return values are handled separately.

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 low (25%). The description explains the role of mood and upcoming_window_hours, and clarifies options. However, the 'prefer' parameter is not mentioned. Overall adds significant meaning beyond the schema.

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

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

The description clearly states the verb (compares), resource (program titles), and specific actions (scoring, finding airing, looking up streaming). It distinguishes from sibling tools like tv_recommend_by_mood and tv_get_title_details.

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 usage when comparing options but does not explicitly state when to use vs alternatives, nor does it mention when not to use. With 13 sibling tools, more guidance is needed.

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?

Goes well beyond the annotations: discloses built-in anti-noise filtering, title dedup (~46% duplicate-airing ratio), opportunity-cost lookahead, event-aware importance boosts, and that the result is exactly one pick plus up to 3 alternatives. It does not cover latency, data freshness guarantees, or failure modes. There is mild tension between the live-EPG/streaming sourcing and openWorldHint=false, but this is not a clear-cut contradiction.

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

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

The core decision contract is front-loaded in the first sentence, which is good. However, the single dense paragraph packs in trigger phrases, domain trivia (Romanian EPG duplication ratio), and parenthetical asides that inflate length without helping tool selection; it would be stronger with separated when/when-not/behavior blocks.

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-field explanation is not strictly required, and annotations cover the safety profile. The description nevertheless supplies the routing logic, the decision-vs-list contract, and the pause/window semantics that an agent needs. Only the under-documented input parameters keep it from a 5.

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 only 55% across 11 parameters. The description clarifies mood routing (internal, with RO/EN aliases) and the meaning of max_alternatives through the 'up to 3 diverse alternatives' return description, but says nothing about prefer, exclude_keywords, allow_pauses, or sources. It therefore does not compensate for the coverage gap, landing at the baseline-plus level.

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 ('decide for me what to watch right now', returns ONE primary decision) and explicitly contrasts itself with named siblings (tv_recommend_by_mood, tv_recommend_today return ranked lists, this returns a decision). An agent can distinguish it from all 13 siblings 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?

Explicit when-to-use ('the user wants ONE answer / a single decision'), explicit when-not ('when the user wants the whole window FILLED with several programmes... use tv_plan_evening instead'), and explicit alternate routing ('for questions like "what is important today?", prefer tv_important_today'). Trigger phrases are enumerated in two languages.

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 destructiveHint=false, so the description adds value by detailing the output contents (per-component values, reasons, alternatives, etc.). It does not contradict annotations, and it provides behavioral context beyond what annotations 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 description is two sentences long, front-loaded with the key outputs, and ends with a usage recommendation. Every sentence is necessary and well-structured.

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

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

The tool has an output schema (not shown but implied), annotations, and 75% schema coverage. The description explains the return value in detail and states its purpose. It could mention prerequisites or that context is optional, but overall it is fairly complete for a debugging 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 75% (3 of 4 parameters described). The description mentions 'in a given mood/context' which adds context for the context parameter, but does not fully detail its structure. For parameters with schema descriptions, the description adds little beyond what the schema provides.

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

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

The description clearly states the tool returns a full score breakdown for a specific program in a given mood/context, listing specific outputs. It distinguishes itself from sibling tools like tv_recommend_by_mood by focusing on explaining an existing recommendation rather than generating one.

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

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

The description explicitly says 'Use to understand or debug a recommendation,' providing clear guidance on when to use it. It doesn't explicitly state when not to use it, but the context and sibling tool names imply alternatives for other tasks.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: the two-step fallback cascade, the response fields (requested_/effective fairness, threshold_relaxed, degraded), and the instruction to inform the user when their threshold was relaxed. That is exactly the kind of out-of-band behavior an agent cannot infer from structured fields.

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

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

Four sentences, front-loaded with the purpose and then the fallback rules, with no obvious filler. It is dense but each sentence carries load; the only mild friction is the long parenthetical about scoring 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?

For a complex nested-parameter tool with an output schema, the description covers the fallback mechanics and the key response signals (threshold_relaxed, degraded) that the agent must surface. It is nearly complete, with the only gap being the undocumented secondary parameters (limit, timeframe, include_streaming_xref).

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 29% across 7 parameters, so the description must compensate. It does define fairness semantics ('min(scoreA,scoreB) >= threshold — no veto') and the min_score halving behavior, but says nothing about limit, timeframe, include_streaming_xref, or the person_a/person_b preference fields, leaving most parameters 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 with a distinguishing scope: 'Finds TV programs that satisfy two people with different moods/preferences.' This clearly separates it from single-user siblings like tv_recommend_by_mood or tv_concierge without needing to open 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?

The description defines the operative condition for the default (fairness=strict) and the exact fallback ladder when strict yields nothing, which is real when-to-use guidance. It never names an alternative sibling (e.g. tv_recommend_by_mood for solo requests) or states when NOT to use this tool, so it stops short of a 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral context: the tool returns data grouped by channel, excludes news channels by default, and interprets dates in Europe/Bucharest timezone.

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

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

The description is two sentences with no redundant words. It front-loads the core functionality, includes example queries, and states a notable default behavior.

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

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

The description covers the main use case, time range, timezone, grouping, and default behavior. However, it does not explain the 'scope' parameter (main vs all), which is a gap. Output schema exists, so return values are handled externally.

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 low (33%). The description mentions the default exclusion of news channels for the 'exclude_news' parameter, but does not clarify the 'scope' parameter or add format details for the 'date' parameter beyond what the schema provides.

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

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

The description clearly states the tool returns prime-time lineup (20:00–23:00 Europe/Bucharest) for a given date, grouped by channel. It includes example queries and distinguishes from siblings by specifying a specific time range and region.

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 says 'Use for queries like...' which gives clear usage context, but does not mention when not to use this tool or provide alternatives among the 14 sibling tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds behavioral details: it scans upcoming TV airings with configurable window (default 48h) and queries specific streaming catalogs for Romania. No contradictions with annotations.

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

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

Two sentences efficiently convey purpose, scope, and examples. No fluff; front-loaded with the main action.

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

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

Given the complexity (two data sources), rich annotations, full schema coverage, and presence of output schema, the description provides all needed context: geographic scope (Romania), time window, and platforms. No gaps.

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

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

Schema covers all 3 parameters with descriptions. The description provides extra context by linking parameters to use cases (e.g., window size for TV airings) and example queries, adding value beyond 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 clearly states the tool looks up a title across upcoming Romanian TV airings and streaming catalogs (Netflix, HBO Max, etc.), with specific verb 'Looks up' and resource 'title'. It distinguishes from sibling tools like tv_search_program by covering both TV and streaming.

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 example queries ('is Avatar on Netflix?', 'when does Game of Thrones air next?') indicating when to use the tool. It does not explicitly exclude situations or mention alternative sibling tools, but the context is clear enough for appropriate use.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: detection is keyword-based because the EPG lacks structured metadata, and live_status is derived with quoted evidence, with 'unknown' meaning the EPG is silent. This is exactly the kind of reliability caveat an agent needs to interpret results correctly.

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 longer than average but front-loaded: the scope comes first, then the detection caveat, then the routing instruction. Each sentence carries distinct information (scope, method, live_status semantics, usage), so nothing reads as 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 structure need not be restated. Given the moderate complexity, the description covers scope, detection methodology, live_status semantics, and when to use it — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents date, limit, and min_tier. The description echoes the tier concept ('major' vs 'notable') in prose but adds no format or default detail beyond what the schema states, so the baseline of 3 applies.

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

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

The description states a specific resource (Romanian TV broadcasts) and a clear scope (major sporting events: World Cup/Euro/Champions League, finals, knockouts), which distinguishes it from recommendation siblings like tv_recommend_today and tv_now_on_tv. The verb is slightly soft ('what actually matters') but the content type 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?

It gives explicit primacy guidance — 'Use this FIRST for questions like "what's important to watch today?"' — which tells the agent when to reach for this over siblings. It does not name specific alternatives to avoid, so it stops short of a full when/when-not statement.

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. The only behavioral claim in the description is the default scope, which merely restates the schema default of 'main'. No permissions, snapshot/freshness behavior, or limits are added beyond structured 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?

Three short sentences, purpose front-loaded, no filler. The final sentence partially repeats the schema's scope default, which is the only thing keeping it from a 5.

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, rich annotations, and fully documented parameters, the description covers enough for correct invocation. It could note that results are a point-in-time snapshot, which would matter given the sibling tv_check_freshness, but nothing essential 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%, with enum and default values and a rich scope description, so the baseline is 3. The description's mention of scope='all' duplicates what the schema already documents and adds no new syntax or 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?

States a specific verb and resource ('Returns the programs currently broadcasting on Romanian TV channels') with a clear present-moment scope that separates it in spirit from tv_tonight_card and tv_get_prime_time. It does not name any sibling explicitly, so the differentiation is implicit 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?

Gives an explicit trigger ('Use this for "What is on TV now?" type questions'), which is clear usage context. It offers no when-not guidance and never points to alternatives such as tv_search_program or tv_tonight_card, so it stops short of the top band.

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 genuinely useful domain constraints not in the annotations: TV-only from live Romanian EPG, no streaming titles. Minor overlap with the output schema in the 'Output:' sentence.

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 core behavior and constraint, then usage triggers, then the sibling alternative. Dense but every clause carries signal; the quoted example phrases are slightly heavy but serve the routing function.

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 re-explained (though it does briefly). Domain boundaries (live EPG only), window semantics and the sibling handoff are all present. The only real gap is the three undocumented numeric/toggle parameters.

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 14% (just 'start'), so the description must compensate, and it names start time, duration budget, mood and channel preferences — four of seven. It leaves max_gap_min, max_segments and allow_channel_switch entirely unexplained in both description and 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 (builds a plan), resource (TV watching plan), and precise scope (fills a window with one long or 2-3 consecutive programmes). It explicitly contrasts with the single-pick sibling tv_concierge, so an agent can separate the two 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?

Gives concrete trigger phrases in two languages ('plan my evening', 'ce văd toată seara', 'fă-mi un program pentru 20–24') and an explicit when-not rule (single decision that may be streaming → tv_concierge). The 3+ hour window condition is spelled out.

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, idempotentHint=true, destructiveHint=false. The description adds valuable context: it explains the combination logic (channel category, mood-fit, time proximity, streaming cross-reference) and mentions that output includes mood_parts breakdown and freshness. There is no contradiction with annotations.

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

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

The description is two sentences with no wasted words. The first sentence states the core purpose, and the second adds essential details about the algorithm and output. It is front-loaded and efficient.

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

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

Given that an output schema exists (mentioned but not shown) and annotations cover safety, the description covers the key aspects: mood parameter, combination factors, output structure. It could mention the Romanian context more explicitly, but it already does. It is mostly complete for the task.

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 43% (only 3 of 7 params have descriptions: mood, prefer, timeframe). The description adds meaningful information for mood (lists aliases) and timeframe (explains format), but does not add semantics for limit, dislike_genres, dislike_keywords, include_streaming_xref. Baseline 3 is appropriate given moderate 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?

The description clearly states it returns top-N Romanian TV programs ranked for a given mood, listing exact mood values and explaining the combining factors (channel category, mood-fit, time proximity, streaming cross-reference). This distinguishes it from sibling tools like tv_recommend_today or tv_now_on_tv.

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

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

The description tells when to use (when a mood is specified) but does not explicitly state when not to use or mention specific alternatives. However, the sibling list and the phrase 'Returns top-N Romanian TV programs ranked for a given mood' make the usage context 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: uses a deterministic scorer that rewards films/documentaries/generalist channels, penalises news, and boosts upcoming programs. No contradiction with annotations.

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

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

The description is two sentences: first explains what it does and how, second provides example queries. No filler, front-loaded, every sentence earns its place.

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

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

With 4 parameters, schema coverage at 75%, and an output schema present, the description adequately covers the tool's behavior (scoring logic) and usage context. It might be slightly improved by mentioning timezone or locale, but overall it is sufficient.

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

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

Schema description coverage is 75% (3 of 4 parameters have descriptions). The tool description does not add parameter-specific meaning beyond the schema; it only mentions 'up to N' which maps to limit. Baseline 3 is appropriate as schema covers most 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 clearly states verb ('Returns'), resource ('program recommendations'), and scope ('for a given timeframe', 'up to N ranked'). It also provides specific query examples, making it easy for the agent to understand the tool's purpose and distinguish it from siblings like tv_recommend_by_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?

The description gives explicit usage examples ('recommend me something for tonight', 'ce e bun la TV diseară') that define when to use the tool. However, it does not explicitly state when not to use or mention alternatives, which would strengthen 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, destructiveHint=false and non-openWorld, so the safety profile is covered. The description adds nothing behavioral beyond search semantics: no ordering of results, no mention of how matches are ranked, and no note that all filters are optional with defaults.

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 tightly written sentences that front-load the core capability followed by example queries and the accepted time formats. Every clause carries information; 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?

With an output schema present, return values need no explanation, and the description covers the query surface well. It could note that all six parameters are optional with defaults, but is otherwise complete for a search 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%, and the description's time-reference list largely duplicates the timeframe schema description. The undocumented parameters (limit, exclude_news) receive no explanation in either place, so the description does not compensate for the coverage 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 (Search) and resource (programs across all Romanian TV channels in the guide) and enumerates the matchable dimensions: free-text title, channel, category, and time window. The scope 'across all channels' implicitly distinguishes it from narrower siblings like tv_now_on_tv or tv_get_prime_time.

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

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

Provides concrete usage examples ('documentaries on Discovery tomorrow', 'football on Saturday', 'what is on Antena 1 right now') that make the intended use case clear. It does not name alternatives or state when NOT to use it versus siblings like tv_now_on_tv, so it falls short of a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is settled. The description adds real behavioral detail beyond that: the deterministic fallback chains per vertical (prime-time film fallback, stage-today-else-online-else-next-performance, box office ∩ real screenings), daily regeneration, and the ui://rotv/tonight-card resource for MCP Apps hosts.

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

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

The purpose is front-loaded in the first clause and every subsequent clause carries selection rules rather than padding. It is dense — one long em-dash-chained sentence — which costs some readability, but no sentence 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 zero parameters and an output schema present, the description needn't explain return shape; it instead supplies the non-obvious selection logic for each vertical, which is exactly the missing context. It stops short of disambiguating the tool from its overlapping recommendation siblings, which is the 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?

The tool takes zero parameters, so the schema imposes no semantic burden and this dimension is baseline-adequate by construction. There is nothing for the description to disambiguate 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 output (a daily 'what is worth watching tonight' card) and enumerates its components: one importance-scored main event plus one pick per vertical (TV, streaming, theater, cinema) and measured stats. It clearly distinguishes itself from search/detail siblings, but never names the overlapping recommendation siblings (tv_recommend_today, tv_get_prime_time, tv_important_today) that an agent must choose between.

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: it tells the agent this is the homepage-hero equivalent rendered as an interactive card in MCP Apps hosts, which is a genuine capability condition. However, there is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives among the many tv_* recommendation siblings.

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