get_on_deck

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

With no annotations, the description carries the full burden and does well: it discloses ordering (most recently active first), a hard cap (at most 50 items across everything), deduplication (movie in HD and 4K is one entry), and the auth/scope of watch state (the connected Plex account). It stops short of stating the read-only nature or error behavior, which is a minor 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 purpose and the routing constraint are front-loaded and information-dense, with no filler. It is somewhat long, and the three quoted user-phrasings ('what haven't I finished?', etc.) restate the same routing point, which is mild 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?

For a 4-parameter, no-output-schema query tool this is complete: the description tells the agent what is returned (how far through each entry), how results are ordered, how they are capped, and when to route elsewhere, so nothing needed to call it 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?

Schema description coverage is 100%, so the baseline is 3; the description adds value by mapping filters to user intents ('Use title for which episode is next for <show>?') and clarifying what mediaType 'show' returns, beyond the schema's terse enum text.

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 ('answers what should I watch next from Plex's On Deck') and precisely defines the resource — partly played movies plus next/partial episode per followed show. It is clearly distinguishable from search_plex_library and other siblings by naming the alternative explicitly.

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 mappings ('Use title for which episode is next for <show>?', mediaType 'show' for next episode in each show) and an explicit when-NOT-to-use with the named alternative (search_plex_library with watched 'inProgress') for complete unfinished lists. Nothing is left to inference.

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