list_discover_movies_upcoming

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint and query parameter labels; it does not disclose pagination behavior, default language, or other runtime characteristics beyond what the schema and annotations already convey.

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 and front-loaded with the core purpose ('Upcoming movies'). The endpoint and Args section are structured and easy to scan, though the Args list is largely redundant with the input schema.

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 simple read-only endpoint with an output schema and strong annotations, the description is minimally adequate. However, it lacks usage guidance and parameter semantics, so an agent would need to infer when and how to call it confidently among sibling discover tools.

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 needed to explain what page and language mean. It only labels them as 'Query parameter,' adding location but not semantics such as 1-based page numbering, language code format, or defaults. This is insufficient compensation for the schema 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 states the resource ('Upcoming movies') and the exact endpoint, making it clear this returns upcoming movies. It doesn't use a verb like 'list,' but the GET endpoint conveys the action. The name and endpoint distinguish it from siblings such as list_discover_movies and list_discover_tv_upcoming, though the description itself does little to explain that 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?

No guidance is given on when to use this tool versus list_discover_movies, list_discover_tv_upcoming, or list_discover_trending. The description provides no use-case context, exclusions, or alternative routing. It is essentially a stub with no selection guidance.

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