list_livetv_epg_lineup

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint and the notion of 'computing' a lineup, which hints at a non-trivial operation, but it doesn't disclose what 'best' means, whether the result is cached, or what happens when device/lineup_group are null. It adds minimal behavioral context beyond the annotations, so a 3 is appropriate.

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 short and front-loaded with the core action ('Compute the best lineup') followed by the endpoint and parameter list. Every sentence earns its place, though the parameter descriptions are terse. It is appropriately sized for a simple two-parameter tool, but the 'Args' section could be more informative without bloating the description.

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, so return values are covered elsewhere, and annotations cover safety. However, the description does not explain what a lineup is, what 'best' means, or how the two optional parameters interact. Given the large number of livetv siblings, an agent needs more context to select and invoke this tool correctly. The description is too thin for the conceptual complexity of 'computing the best lineup'.

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 for the two parameters. It lists 'device: The URI describing the device' and 'lineup_group: The URI describing the lineupGroup', which adds the fact that they are URIs, but it doesn't explain how they are used, what formats are valid, whether they are optional (schema shows defaults of null), or how they affect the computed lineup. This is minimal compensation for a 0% 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?

The description says 'Compute the best lineup' and includes the endpoint GET /livetv/epg/lineup, which gives a specific verb and resource. However, it doesn't explain what a 'lineup' is in this context or how it differs from closely related siblings like list_livetv_epg_lineupchannels, list_livetv_epg_channelmap, or get_livetv_epg_countries_by_country_by_epg_id_lineups. The name and endpoint make the resource clear, but the purpose is vague about what 'best' means and what the output represents.

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?

No guidance is given about when to use this tool versus alternatives. The description does not mention any related tools, conditions, or exclusions. An agent would have to infer from the name and endpoint that this is for retrieving an EPG lineup, but there is no explicit direction about when this is the right choice among the many livetv-related siblings.

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