SRG SSR Video – Episoden einer Sendung

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behaviors. The description adds useful behavioral details beyond these: episodes are delivered in descending chronological order and pagination is constrained to page_size 1–50. This clarifies response structure and limits, which is valuable and does not contradict 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 concise and well-structured with XML-like tags (use_case, important_notes, example) that separate purpose, behavioral notes, and an example. The primary sentence is front-loaded, and every element adds value—there is no fluff. It could arguably be more compact, but is appropriately sized for the information conveyed.

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 tool's moderate complexity (3 parameters plus pagination), the description covers the essential behavioral aspects (ordering, pagination), provides a usage context, and links to the prerequisite tool for show_id. The output schema exists, so return values are documented elsewhere. What is missing is any mention of authorization or rate limits, but these are unlikely critical for a read-only listing tool with annotations covering safety. Overall, it is complete enough for an agent to call 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 0% (only business_unit has a description in the schema), so the description must compensate. It does so by providing a concrete example (business_unit='srf', show_id='tagesschau') and noting that show_id comes from get_shows. It also specifies the page_size range (1–50). The page parameter is not explicitly explained, but its meaning is clear from the pagination context and default value in the schema. Overall, enough meaningful guidance is added for the key parameters.

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's action: 'Ruft die neuesten Episoden einer TV-Sendung ab' (retrieves the latest episodes of a TV show), and lists the returned fields (episode title, date, duration, video ID). It specifies the resource (TV show episodes) and verb, but does not explicitly contrast with the sibling audio_get_episodes. The tool name and title already convey the video domain, so differentiation is implicit rather than explicit.

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 a use case ('Recherche zu konkreten Sendungsausgaben' – research on specific show editions) and notes that a valid show_id comes from srgssr_video_get_shows, guiding the agent on a prerequisite. However, it does not explicitly state when to use this tool over alternatives (e.g., not for audio episodes) nor provide 'when-not' guidance. The context is helpful but not explicit.

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