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?

Annotations only declare readOnly/idempotent/non-destructive; the description adds substantial behavior: a built-in anti-noise filter (news/politics/reality/talkshow) that requires no manual effort, title dedup of repeat airings, opportunity-cost lookahead outside the window, and event-aware ranking boosts for major broadcasts. It also explains the best_by_source/gap_pct semantics that govern how the agent should present results — none of that is derivable from annotations or schema.

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 opening sentence is well front-loaded, and the PREFER-THIS-TOOL routing sits early, but the block is bloated: the mood vocabulary is restated from the schema, the trigger-phrase list is long, and feature claims (dedup, lookahead, anti-noise, event boost) are stacked as a feature dump rather than prioritized. Dense but not wasteful to the point of harm.

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, 11-parameter, nested-window tool with an output schema, the description covers the decision semantics, source coverage, and sibling routing well enough to call it correctly. Remaining shortfall is the unexplained optional filters (prefer/allow_pauses/exclude_keywords), which would matter if a user asks to steer the pick.

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%, and the description compensates for part of that: it explains mood routing with EN aliases, the 'I have X hours' window shorthand, the anti-noise exclude_categories default, and that max_alternatives/risk_aversion control up to 3 alternatives. But 'prefer', 'allow_pauses', and 'exclude_keywords' are left entirely unexplained in both schema and description, which is a real gap for an 11-parameter tool.

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 concrete verb and resource ('decide what to watch right now', returning ONE primary decision from TV EPG + streaming catalog) and explicitly contrasts itself with named siblings: it is a decision tool, not a ranked list like tv_recommend_by_mood / tv_recommend_today, and not a scheduler like tv_plan_evening.

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 positive triggers ('decide for me', 'am 2 ore', 'alege tu'), explicit exclusions (wants the whole window filled with several programmes in sequence → tv_plan_evening; 'what is important today?' → tv_important_today), and named alternatives for browsing. The routing condition between decision vs. list vs. plan is unambiguous.

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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds genuinely useful scope context the annotations cannot express: the results are Romania-specific TV airings plus four named Romanian streaming catalogs. It says nothing about coverage gaps (e.g. titles absent from all sources) or result ordering, and with an output schema present the remaining burden is light, so a 3 is fair.

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

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

Two sentences, front-loaded with the sources covered, followed by illustrative examples that each earn their place by mapping to one of the two result channels. No filler or restated title text.

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

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

For a three-parameter read tool with a full output schema, the description covers sources, region and time window adequately, so an agent can invoke it correctly. It stops short of describing how the two result sets are combined or what an empty match looks like, which is the only 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% and each parameter is documented with type, bounds and default, so the baseline is 3. The description restates the default 48-hour window and lists the streaming providers, which duplicates rather than extends the include_streaming description; it adds no new semantics such as matching behavior or what happens when include_streaming is false.

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 ("looks up") and resource ("a title") and bounds the scope precisely: upcoming Romanian TV airings within N hours plus the Romanian streaming catalog of four named providers. That is far more specific than the title alone. It does not, however, draw an explicit line against close siblings like tv_search_program, so an agent must infer the difference.

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?

Two concrete example queries ("is Avatar on Netflix?", "when does Game of Thrones air next?") make the intended use case immediately recognizable. There is no statement of when to prefer a sibling tool or when this tool is the wrong choice, 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description then adds genuinely non-obvious context: detection is keyword-based from EPG titles and descriptions, there is no structured event metadata, results carry quoted evidence, and live_status is honest about 'unknown' when the EPG is silent. That is exactly the kind of caveat an agent needs to set user expectations.

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 key claim and the 'use this FIRST' instruction frame it well, and the detection-methodology caveat earns its length because it prevents the agent from treating output as ground truth. The middle sentence is long and parenthetical-heavy, pushing the tier definitions into a dense clause, so it's slightly harder to scan than it 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?

An output schema exists, so return-value shape needn't be explained, and annotations cover the safety profile; the description fills the remaining gap (provenance of detection, live_status semantics). Minor omissions such as behavior on empty days or the date-range scope are small, but they're the only things left unstated for a 3-param tool.

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

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

Schema description coverage is 100%, and min_tier is fully enumerated in-schema with the same tier-1/tier-2 definitions the description uses, so the description adds little new parameter meaning. Baseline 3 applies; the mention of tier 1/tier 2 restates the schema rather than extending it.

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

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

The description specifies the resource (Romanian TV broadcasts today), the exact criteria for inclusion (World Cup/Euro/Champions League matches, finals, knockouts, national-team fixtures, named derbies, top-club matchups), and how tiers map to that. An agent knows precisely what this returns versus a generic search or now-on-TV tool.

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

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

"Use this FIRST for questions like 'what's important to watch today?'" gives explicit routing and a sample query, which is strong guidance. It doesn't, however, name the sibling alternatives (tv_recommend_today, tv_tonight_card, tv_plan_evening) or state when NOT to use it, so the agent must infer the boundary 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, 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 read-only, non-destructive, idempotent, non-open-world behavior, but the description adds substantial operational detail: relevance floor formula, anti-noise category filter, unfilled-minute reporting, gap causes, overflow_min, and the 30-minute minimum slot.

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 purpose and usage guidance, and most sentences add meaningful behavioral detail. It is dense and includes some output-format detail that overlaps with the output schema, but no sentence is clearly wasted.

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

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

For a complex planning tool with an output schema, the description supplies everything important: scope, selection logic, anti-noise filtering, unfilled-time handling, overflow behavior, and routing to the right sibling. Return values are appropriately summarized.

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 25%, so the description must compensate. It covers start time, duration budget, mood, channel preferences, max_segments behavior, and the configurable category filter, but leaves max_gap_min and allow_channel_switch unexplained and gives no format details for prefer.

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: builds a TV watching plan/timeline for a time window, with concrete behavior (one long programme or 2-3 consecutive programmes). Explicitly distinguishes itself from tv_concierge for single picks.

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 when-to-use conditions (whole evening or long window of 3+ hours), sample user phrasing, and the alternative (tv_concierge) for single decisions or streaming titles. Also scopes to TV/live Romanian EPG only.

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 cover readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: the deterministic scoring rules, the tie-break hierarchy, and the critical nuance that rating_signal only orders ties and never changes the score. It does not say what happens when no items satisfy the timeframe or when limit exceeds available results, which is the remaining behavioral gap.

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 capability is front-loaded in the first sentence, with scoring details after. The scorer/tie-break passage is dense and slightly long, but every clause conveys behavior an agent would otherwise guess wrong about, so little 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 an output schema present, return structure needn't be explained, and annotations cover the safety profile; the description also clarifies what tie_break and rating_signal in the output mean. Only empty-result and timeframe edge cases are unaddressed, so the definition is close to complete for a 4-param, zero-required 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 75% and timeframe, prefer and exclude_news all carry descriptions, so the schema does most of the work. The description only echoes limit ("up to N") and timeframe, adding nothing about acceptable timeframe syntax or how the prefer categories interact with the penalty rules. 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?

States a specific verb and resource: returns ranked program recommendations for a given timeframe. The scoring model described (films/documentaries/generalist channels, news penalised, imminent-start boost) makes clear this is a curated ranking tool, distinguishable from mood-based or couple-based siblings like tv_recommend_by_mood and tv_find_for_couple.

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

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

Gives concrete usage phrasing in two languages ("recommend me something for tonight", "ce e bun la TV diseară"), which anchors the intended intent. It stops short of naming when NOT to use it or pointing at the alternative siblings (tv_recommend_by_mood, tv_important_today, tv_tonight_card), so there is no explicit exclusion 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 cover safety (readOnly, idempotent, non-destructive). The description adds the detail that the search is 'in the guide,' implying data source and freshness context, but does not disclose other behavioral traits like rate limits, result pagination, or how no-results are handled.

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 front-loaded with purpose and examples, and is appropriately concise. The time references sentence is slightly redundant with the schema but does not bloat the description significantly.

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 described. However, the description is incomplete regarding the limit and exclude_news parameters, and does not clarify search behavior or edge cases for a tool with six optional 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 description coverage is 67%, and the description repeats the exact time reference list already present in the schema, adding no new meaning for any parameter. It also fails to document the two undocumented parameters (limit and exclude_news).

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) with multiple searchable fields. It clearly conveys the tool's scope, but does not explicitly differentiate itself from sibling tools 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 example queries that imply typical usage, but gives no explicit guidance on when to use this tool versus alternatives. The example 'what is on Antena 1 right now' overlaps with sibling tools, and the description does not clarify the distinction.

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 annotations (readOnly/idempotent/non-destructive), it discloses regeneration cadence at EPG refresh, the meaning of `date_is_today` and the resulting `freshness.stale`/`freshness.warning` flags, and that rendering becomes an interactive card only in MCP Apps hosts. That is exactly the kind of staleness and host-dependency behavior an agent cannot get 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?

Purpose is front-loaded and every clause carries real information, but the middle sentence is a single sprawling construction with deeply nested parentheticals (theater/cinema fallback chains) that slows parsing. Content earns its place; formatting could be tighter.

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?

Zero params, an output schema, and full annotations mean the description only needs to cover behavior — and it does: composition rules, refresh timing, staleness signaling, and host capability requirements. Nothing an agent needs to call this 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?

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description instead spends its space on output semantics, which is the right allocation 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?

The description states a concrete deliverable — a daily card with one importance-scored main decision plus one pick per vertical (TV, streaming, theater, cinema) — so an agent knows exactly what it returns. It does not, however, contrast itself with near-neighbours like tv_recommend_today or tv_important_today, which likely overlap in scope.

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 'what is worth watching tonight' framing implies the use case, and the staleness rule gives a calling condition, but there is no explicit when-to-use/when-not guidance and no named alternative among the 13 siblings. An agent must infer whether to call this or tv_recommend_today / tv_important_today.

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