imdb_title_public_facts_analysis

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

No annotations are present, so the description fully carries the burden. It discloses the partial-fetch behavior (missing sections reported in `missing_sections` with `partial=true`), the error condition when no section can be fetched, and the caveat that this is not viewing advice. This goes well beyond basic read/write expectations.

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 four sentences long, front-loaded with the purpose, then adding behavioral details. Each sentence provides distinct information without filler. The phrase 'This endpoint is not viewing advice' is compact but somewhat cryptic, slightly reducing clarity.

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?

Given the tool's complexity (six independent sources, partial-failure handling) and no output schema, the description explains return semantics, missing_sections, the partial flag, and error behavior. It names the six sections but does not elaborate on what 'summary metrics' specifically contain, leaving some ambiguity.

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 descriptions cover both parameters (id and url). The description adds a critical constraint absent from the schema: 'Pass exactly one of `id` or `url`.' This clarifies they are alternative identifiers, adding meaning beyond the bare schema descriptions.

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 clearly states the tool returns 'derived public-page summary metrics' for six named IMDb sections (trivia, goofs, quotes, keywords, filming locations, company credits). This specific verb+resource+scope distinguishes it from sibling per-section tools like imdb_title_trivia or imdb_title_goofs.

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?

The description provides clear usage context: pass exactly one of `id` or `url`, and check `partial` for complete analysis. It warns 'This endpoint is not viewing advice', which is an exclusion. However, it does not explicitly name alternative tools or compare when to use this aggregate vs the individual IMDb section tools.

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