Channel Schedule

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

No annotations are provided, so the description carries the full burden, yet it discloses nothing about read-only behavior, pagination, rate limits, or whether the guide is limited to a fixed window. The output schema covers return shape, but the behavioral profile of the call remains undocumented.

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 short sentences with no filler, and the resource definition is front-loaded ahead of the format note. It reads slightly like a schema annotation rather than a tool description, 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?

An output schema exists, so return values need not be explained, and the date format gap is closed. Still, an agent lacks routing guidance against three plausible sibling tools and has no way to know how to obtain a valid stream_id, which leaves the definition only minimally viable.

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%, so the description must compensate. It does so well for the hardest parameter, fully spelling out accepted date tokens ('today'/'yesterday'/'tomorrow' or YYYY-MM-DD in local time), but says nothing about stream_id's source or what include_descriptions toggles — two of three parameters remain opaque.

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?

"A channel's guide for one day" names a specific resource and scope (single channel, single day), which is more informative than restating the title. However, it never states a verb (retrieve/list) and does not differentiate this from siblings like search_programmes or programme_details, leaving the agent to infer the distinction.

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?

There is no guidance on when to use this versus search_programmes or programme_details, and no stated prerequisite such as where stream_id comes from. The only conditional content is about the date argument, which belongs to parameter semantics rather than usage routing.

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