Film and series profiles

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so credit goes to the added behavioral facts: results are either read completely (`complete`: true) or truncated to the first `depth` pages (`partial`: true), and depth scans cost one request per 36-title page. That is real operational context an agent cannot get from the annotations. The one flaw is the claim "top_rated sorts by IMDb score," which conflicts with the schema's note that top_rated is the Gamefa editors' score.

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?

Front-loaded with purpose, then usage examples, then constraints, then routing to siblings — a sensible order with no filler sentences. The style is telegraphic and a few clauses are compressed to the point of ambiguity (the depth/complete/partial sentence), which costs a point.

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 12-parameter browse tool with no output schema, the description covers the returned fields, the pagination envelope (complete vs partial, depth limits), the filter combination rule, and the follow-up tool for detail. Nothing an agent needs in order to call it correctly or interpret the result shape 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 coverage is 100%, so baseline is 3; the description earns a step above it by stating the filter exclusivity rule ("at most one of type, genre, person, company, country, language, year; query works alone"), which is not expressed anywhere in the schema and is essential for correct calls. Its top_rated/IMDb-score sentence directly contradicts the sort parameter's own description, which could mislead sort selection.

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?

Opens with a specific verb pair ("Browse or search") and the exact resource (Gamefa film/TV series profiles), then enumerates the fields returned. It actively separates itself from siblings: gf_film for cast/runtime detail, gf_terms for slug discovery. An agent can distinguish it from every listed sibling without opening another schema.

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 concrete natural-language queries that map to this tool ("top rated films", "Nolan films", "finding a slug") and names two explicit alternatives with the condition that selects them (gf_terms for slugs, gf_film once you have a slug). It also states the mutually exclusive usage rule that governs correct invocation.

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