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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: it warns that few-vote titles are noisy and that min_votes filters them, and it explicitly instructs the agent to warn the user when low_votes:true is present. 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 tightly packed: it starts with the core purpose, then gives the canonical use case, clarifies the important min_votes noise issue, routes new-release queries to the right approach, and finishes with a clear non-use instruction. Every sentence earns its place; no filler or repetition.

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 tool with 11 optional parameters and no output schema, the description covers the major contexts: filter-based discovery, data-quality caveats, new-release handling, and sibling tool routing. It does not describe the return shape, but that is largely implied and the annotations carry the safety model. Slightly more could be said about pagination or language, but overall it is sufficiently complete for an agent to reason about when and how to use it.

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% and the parameter descriptions are already rich (e.g., min_votes explains the default and the brand-new-release adjustment). The tool description restates some of this and provides a usage example, but it does not add substantial new parameter meaning beyond the schema, so the baseline 3 is appropriate.

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 a specific verb and resource: 'Find movies or shows by filters: genre, year, minimum rating, minimum votes, sort order.' It immediately distinguishes the tool from siblings by explicitly stating 'Do NOT use for title search (use movies_search)' and pointing to movies_trending for hot content, so an agent can tell them apart without opening schemas.

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?

It gives an explicit when-to-use pattern: 'Use for "action movies after 2020 rated above 7" style questions.' It also gives conditional guidance for brand-new releases (sort newest with min_votes 0-50, or movies_trending) and an explicit exclusion for title search with the named alternative. This is unambiguous and actionable.

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