list_media_anticipated

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 behavioral detail about pagination (defaults, clamping) which is useful, but otherwise does not disclose additional behaviors like result ordering or filtering semantics beyond what the parameters suggest. 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 compact, starts with a clear one-line purpose, and lists parameters in an organized format. The repeated 'Query parameter' entries are slightly redundant but do not bloat the text significantly. The extended watchnow explanation is verbose but valuable.

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?

Despite the output schema covering returns, the description lacks overall context: it never defines what 'anticipated' means, states whether both movies and shows are included, or explains how this tool relates to the movie/show-specific siblings. An agent is left without enough information to confidently choose this tool in an ambiguous situation.

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?

With 0% schema description coverage, the description must compensate for parameters. It provides meaningful detail for watchnow (enum-like values) and limit (defaults/capping), but most other parameters are only labeled 'Query parameter,' adding no insight beyond their names. Since many names are self-explanatory, this is adequate but not thorough.

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 opens with 'Get anticipated media,' a clear verb+resource statement that is not tautological. It conveys the core function but does not explicitly differentiate from sibling tools like list_movies_anticipated or list_shows_anticipated, relying on the name 'media' to imply both.

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 tool versus alternatives. The description only lists parameters and the endpoint, providing no conditions, exclusions, or references to sibling tools. An agent would have to infer that general media listings differ from movie/show-specific ones.

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