Cutscene

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

Annotations only say non-readOnly, non-idempotent, non-destructive. The description adds the crucial behavior that the connector reads no file itself — the user places the file in the editor — and that the call returns the film's address plus user-facing localized wording. It does not explain what state change, if any, the call causes on the film, which is the remaining ambiguity for a non-idempotent tool.

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?

Three sentences, no filler, but the front-loading is poor: the first sentence opens with an object rather than the action, and the French quoted strings plus the ElevenLabs detail compete for attention before the core 'what this does' is settled. Readable, but it takes effort to extract the operation.

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 10-parameter, non-idempotent tool with no output schema, the description covers the division of labor with the user and the sibling voice-creation flow, which is the hardest part. It leaves open prerequisites (must the film be open in the editor?) and reversibility (relationship to `undo_film`), which an agent would need before calling.

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 the schema already carries the meaning of all ten parameters, including the voice/sound enum and the path-as-label behavior. The description mostly restates that split rather than adding new semantics (e.g. how `path` is validated when nothing is read, or how `on`/`beat`/`second` interact in practice). Baseline 3 applies.

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 identifies the resource (a sound file — either a voice-over or a sound) and the destination (the film), and the title states it plainly. It also distinguishes itself from the voice-creation path by naming `edit_film set_voice`. The inverted phrasing ('a sound file ... is put in the film by the user') makes the actual actor ambiguous at first read, but the operation is still identifiable.

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 alternative: a voice that does not yet exist is prepared with `edit_film set_voice` and then created by the user in the editor with their ElevenLabs account. That is a real routing rule. What is missing is the negative case — when this tool should not be called at all (e.g. file not on disk, film not open in the editor).

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

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 valuable context beyond those annotations: it says the result is one answer covering many checks and ends with `next`, an ordered action list.

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 informative but front-loads a rhetorical phrase and then packs roughly a dozen checks into one very long sentence. The usage instruction at the end is valuable, but the overall structure is not scannable.

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 read-only diagnostic tool with three fully documented parameters and no output schema, the description gives a thorough sense of what is checked and that the response ends with a `next` action list. It is close to complete, though it could name the analogous piece-level tool or clarify the return shape further.

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%, so the parameters (name, uhd, formats) are already fully documented in the schema. The description does not add further parameter-level meaning, which is acceptable when the schema does the heavy lifting.

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 this is a pre-export validation of a film, enumerating concrete checks and calling the film the resource. It does not explicitly differentiate itself from the sibling check_piece tool, so it falls short of a 5.

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 a clear usage instruction: run it before telling the user the film is done and ready to export. It does not name an alternative tool or state exclusions, so it is strong but not exhaustive.

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

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

Exceptional disclosure beyond annotations: runtime expectations ('up to a few minutes' locally, 3-4 minutes online), the asynchronous start-then-poll protocol, quota consumption per day, that a cached piece re-answers without spending a check, that a modified piece is reported as such, and that a failed check refunds the day's check. This fully explains why the tool is not read-only and not idempotent, matching the 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?

Information density is high and little is filler, but the text is a wall of run-on sentences with ornamental phrasing ('drawn by the real engine', 'words that may claim something', 'a bare ground or a jump'). The single most important operational fact — that online calls are asynchronous and must be re-polled — is buried mid-paragraph rather than front-loaded.

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?

With no output schema, the description carries the burden of describing returns and does so at a high level ('answers what is wrong in sentences, with a picture of it at work'), plus the status strings an agent will see while a check runs and after a failure. A more explicit statement of the verdict payload shape would close the remaining gap, but an agent can call this correctly from what is given.

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, and the description earns above that by unpacking 'again: true' with real semantics the schema only hints at: it starts a new check even when cached, stale, or failed, it costs one of the day's checks, and it must not be used while a run for that version is in flight. The 'id' parameter is left to the schema, which already points to search_library { mine: true }.

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 a specific verb and resource ('Pass one of the user's pieces through every gate the pieces of the library pass') and enumerates the actual checks: shader compiles, weight, scene robustness, no dark/light flashing, brand colours, four content formats. It is clear what the tool does despite the metaphorical framing, though it never names check_film or explains the piece-vs-film boundary for an agent choosing between them.

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 concrete operational guidance for the repeat-call workflow: online the first call returns immediately, call again a few minutes later for the verdict, and a cached verdict reappears for an unchanged piece. It also states the one exclusion for 'again' ('never while one of this version runs'). It stops short of saying when to run a check at all (e.g. after create_piece/edit_film) or why to prefer this over preview_film.

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

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

With no output schema, the description carries the return-value burden well: it discloses that the answer contains the film id with its prj_ prefix that "every other tool takes", plus the editor address, and that the film appears in « Mes films ». It also clarifies that a copy is independent of its source and that site scraping reports what was found and what was not, telling the agent to ask the user for the rest.

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 the verb and the three modes, and every clause carries information. The nested parentheticals (especially the one inside the `from` explanation) make it denser than it needs to be, but nothing is padding.

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 13-parameter, nested-object tool with no output schema, the description covers the creation modes, brand routing, side effects and the return payload adequately. It leaves the many styling parameters (colors, fonts, radius) entirely to the schema, which is acceptable given the 100% coverage.

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 100% schema description coverage, the schema already documents all 13 params, so the baseline is 3. The description adds genuine motivation beyond that: why to use `from` (a variant without touching the original) and why templates are recommended (cut, with transitions, music and sounds).

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?

States a specific verb and resource ("Start a film on the user's account") and enumerates the three creation modes: template, empty, or copy of an existing film. An agent can distinguish it from siblings like edit_film or create_piece without opening the 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?

Recommends the template route explicitly, explains why one would use the copy route ("to try a variant without touching the original"), and routes brand setup to set_brand ("Give the brand here or later with set_brand"). It names alternatives but does not state any when-not-to-use condition.

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

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

The annotations mark the tool as destructive, and the description adds substantial behavioral context: validation/refusal, drawing checks, storage location, overwrite effects on films, and brand-color checks. It does not contradict the annotations and greatly reduces ambiguity beyond them.

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 purpose is front-loaded, but the prose is long, run-on, and occasionally confusing, especially where it says "one of two ways" despite several modes existing. The complexity justifies some length, but the structure could be tighter and clearer.

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 complex multi-mode creation tool with a rich schema and destructive annotation, the description covers validation, storage, overwrite behavior, and post-creation workflow. It omits the file-import mode from prose and relies on the schema for that path, so it is mostly but not fully complete.

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% and already very detailed. The description adds useful semantics for from film/shot (what is and is not copied), recipe structure, and overwrite consequences, though it adds little for the file-import parameter beyond the schema.

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 opening "Make a piece of the user's own" names a specific verb and resource, and the body distinguishes the from-film/from-piece/recipe modes and points to show_piece, check_piece, and preview_film. Despite the confusing "one of two ways" phrasing, an agent can identify the tool's role and distinguish it from siblings.

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 explains the conditions for each creation mode and names alternatives for viewing, validating, and previewing in film colors. It does not discuss the file-import mode in prose, but the schema covers it, and the overall routing guidance is strong.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower, but the description pays it off by disclosing the crucial nuance that the film is not erased — it moves to the bin with its earlier versions and stays restorable via restore_film. It also flags the confirmation contract and that the response carries a retention window, which the agent cannot infer from any structured field.

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?

Three short sentences, front-loaded with the action and then the confirmation requirement, with no filler. The phrasing "the user's word first" is slightly colloquial where "explicit user consent" would be unambiguous, but nothing is wasted.

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?

There is no output schema, and the description compensates by telling the agent what the response contains (the retention period) and how to undo the action. Combined with the confirmation contract, nothing an agent needs to call this safely 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% and the schema already explains both name (prj_… id, see list_films) and confirm (must be true, say so only after the user agreed). The description's "needs confirm: true, and the user's word first" re-states the schema rather than adding syntax or format detail, so baseline 3 applies.

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?

"Take a film off the user's account" states a specific verb (remove) and a specific resource (film), and the sibling delete_piece is implicitly ruled out by naming the resource explicitly. The mention of restore_film as the inverse further pins down what class of operation this is.

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 gives real preconditions (confirm: true, and the user's agreement must come first) and names restore_film as the alternative path that reverses it. It stops short of explicit "when not to use" guidance such as preferring edit_film or rename_film for non-removal changes.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description goes further by stating the erasure is permanent and that films already using the piece keep it and keep working — the exact blast-radius information an agent needs. It also encodes the consent requirement as a behavioral rule, not just a field constraint.

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?

Three short sentences, front-loaded with the action and its consequences, with the sibling pointer in parentheses. Dense and mostly waste-free, though the parenthetical reference is slightly cryptic for an agent unfamiliar with the UI name.

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 2-parameter destructive tool with rich annotations, the definition covers scope, prerequisites, and downstream effects on dependent films. The only gap is what a successful call returns (no output schema exists), which leaves the agent to infer the response.

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% and both parameters are already documented, including the confirm precondition. The description largely restates the confirm requirement and adds only the implicit scoping of id to the user's own pieces, so the baseline 3 applies.

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?

States a specific verb and resource ('Take one of the user's own pieces off their account') and scopes it to 'Mes pièces' / mine=true, which separates it from delete_film and community-facing siblings. An agent can identify the target set without opening the 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 the discovery path for obtaining an id (search_library { mine: true }) and a hard precondition: confirm: true only after the user has agreed. It does not spell out when-not cases (e.g., piece used by a film the user may still want), but the gating condition is clear.

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

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

The description discloses important behavior beyond the annotations: changes are applied in order and atomically ('if one is refused nothing is written'), and the answer reports which change failed and why. It also states that undo_film restores the film to its prior state, which is valuable reversibility information for a non-idempotent mutation tool.

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 front-loaded with the core semantics: apply changes in order, all together, with atomic failure reporting. The operation list is useful but somewhat long and partial, and it slightly repeats schema-level op names, keeping it from being maximally concise.

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 complex nested-schema mutation tool, the description supplies the essential transaction and recovery model, common operation examples, and pointers to relevant siblings. It still lacks explicit differentiation from overlapping sibling tools such as set_brand or rename_film, and does not describe a successful response, though no output schema exists.

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%, so the detailed per-op schema already carries parameter meaning. The description adds only the reminder that shots are named by position and enumerates some common ops, both of which are substantially covered by the schema itself.

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 gives a specific verb and resource: 'Apply changes to a film'. It also clarifies scope with 'in order and all together', so the agent knows this is a batch mutation tool. It mentions undo_film and open_in_editor as related tools, but does not fully differentiate from overlapping sibling mutations such as set_brand or rename_film.

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?

Usage is implied through typical operations and the note that pictures are added via open_in_editor, plus undo_film for reversal. However, there is no explicit when-to-use guidance against alternatives like create_film, set_brand, or rename_film, so the agent must infer the boundaries.

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

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

Beyond the structural hints (read-only), the description adds crucial behavioral context about the return value, such as including 'its version, the end mark the plan adds, what is still to complete,' and details the specific handling of the 'since' parameter.

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 dense, managing several pieces of information—scope, comparison to siblings, parameter function, and return content—within a tight space, though the prose is slightly narrative.

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 lack of an output schema, the description provides a very complete picture of the returned data, listing the entire film, version, completion status, and missing pictures.

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?

While schema coverage is 100%, the description adds semantic value by specifying that the 'since' parameter should be answered with 'unchanged' when the state is still, clarifying its role as a state-check mechanism.

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 tool clearly defines its function as drawing a film specifically for 'Cutscene's window.' It successfully distinguishes itself from the broader 'read' functionality by explicitly suggesting the alternative, get_film.

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 explicit rules for usage, stating it is 'For Cutscene's window only' and directing the agent to prefer get_film for general reading.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real value by disclosing the shape of the short form (leading *, `examples` key alignment) and the expected volume of sounds ('often several dozen'), which pre-empts surprise. It says nothing about failure behavior for an unknown or malformed prj_ id, so it stays at 3.

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?

It is compact and front-loads the default short-form content before the flag variants. However the opening sentence is overstuffed with parenthetical asides ('a leading * marks an example nobody wrote yet') that are hard to parse on first read.

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?

With no output schema, the description carries the burden of describing return values, and it does so only partially: it names the sections but not the film's own attributes or the error case for a bad id. Adequate for a read-only three-parameter tool, but not complete.

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 the baseline is 3, but the description earns a point by explaining what the flags select in terms of result content: sounds yields each sound 'with its moment and the id set_sound takes', full yields 'the whole document'. That cross-references a sibling tool in a way the schema alone does not.

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 concretely states what a read returns: shots in order, their words, transitions, music, manually placed sounds, plus how many the shots bring. That is a specific verb+resource rather than a restatement of the title. It does not differentiate this tool from the many near-siblings (show_film, preview_film, film_for_view, check_film, get_piece), which keeps it at 4 rather than 5.

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 two conditional clauses ('With sounds: true', 'With full: true') describe how to widen the response, not when to choose this tool over show_film, preview_film, film_for_view or check_film. There is no exclusion or alternative-selection guidance at all.

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

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

Annotations establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is already covered. The description adds substantial value by explaining the shape of the returned piece data, including settings choices, example words, and anatomy, though it does not discuss failure modes or permission requirements.

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 front-loads the core purpose with 'Everything about one piece,' but it then becomes a long, dense sentence with nested parentheticals. Every clause carries information, yet the structure is difficult to parse and could be broken into clearer sentences.

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?

With no output schema, the description does useful work by describing the returned piece anatomy in detail. It still leaves ambiguity about when this tool should be used instead of similar read-oriented siblings, but for invoking the tool correctly with the given schema it is largely complete.

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%, so parameter meaning is already well documented. The description does not add much about how id, lang, or example should be combined beyond what the schema and enum descriptions already say, making the baseline 3 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 clearly scopes the tool to one piece and enumerates what information is returned: purpose, duration, settings, elements, example words, and anatomy. It does not explicitly distinguish get_piece from overlapping siblings like show_piece, piece_for_view, or check_piece, so it falls short of a 5.

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 closing instruction 'Read it before filling a shot' gives a concrete usage context. However, it provides no explicit when-not guidance and does not explain when to choose this tool over show_piece, piece_for_view, or check_piece.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the result is sorted by most recent change first and each entry contains an id and a title. It does not say whether all films are returned or whether results are capped.

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?

A single tight sentence with no filler; the resource, ordering, and returned fields are all front-loaded. Every clause carries information an agent needs.

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?

With no output schema, the description correctly shoulders the burden of describing return values and ordering, which it does. The only missing piece is any statement about result size, pagination, or empty-account behavior.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description usefully documents the shape of the id field (prj_…) that downstream tools expect.

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 names the exact resource (the user's account films, « Mes films ») and the returned fields (id and title), so an agent can tell it apart from single-film siblings like get_film or show_film. It stops short of explicitly naming an alternative, so it is clear but not fully sibling-differentiated.

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 parenthetical '(prj_…, what every other tool takes)' implies the intended workflow — fetch ids before calling other tools — but the tool never states when to use it versus get_film, search_library, list_montages or list_versions. Usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds value by disclosing the return content (ordered shots plus duration), which the agent would otherwise not know since there is no output schema. It does not mention ordering of the template list itself or whether templates are built-in versus user-authored.

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?

Two sentences, no filler, with the resource definition front-loaded before the follow-up action. The colon-fragment opener ("The templates: ...") is slightly loose but reads efficiently.

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 one-optional-parameter, read-only listing tool with rich annotations and no output schema, the description covers what is returned and the next workflow step. Only the absence of sibling differentiation and list ordering keeps it from being fully complete.

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% and the single `lang` parameter is fully described in the schema, including its enum and default. The description never mentions language selection, so it adds nothing beyond the schema — baseline 3 applies.

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 definition identifies the resource concretely ("templates: films that are already cut" with examples like launch, feature drop, demo, teaser) and the payload returned ("their shots in order and their length"). The verb 'list' is carried only by the title, and it never contrasts itself with list_films or list_versions, so an agent must infer the 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?

It gives a clear downstream use: "Start a film from one with create_film, then change what needs changing," which tells the agent why and when to call this before create_film. It stops short of explicit exclusions (e.g., when to use list_films instead), so it is strong but not complete routing guidance.

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

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

With annotations already declaring read-only, idempotent, non-destructive behavior, the description adds substantial non-obvious context: versions are ordered most-recent-first, retention is capped at the 20 most recent, and each entry carries a timestamp, length, and shot count. The retention cap in particular is behavioral information an agent could not infer from annotations or schema.

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?

One dense sentence with front-loaded ordering and scope information, followed by return-field content. Every clause carries information, though the colon-chained structure is slightly run-on compared to a cleaner two-sentence split.

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?

No output schema exists, but the description compensates by enumerating the return fields (id, written moment, length, shot count). The 20-version cap is disclosed. It does not address pagination or behavior beyond the cap, which is a minor residual gap for a read-only list tool.

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?

There is a single parameter whose schema description is at 100% coverage, already documenting the prj_… id format and pointing to list_films. The description adds no additional parameter detail, which is acceptable given the schema does the work, so the baseline 3 applies.

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 first clause names the resource and scope precisely: 'The earlier versions of a film, most recent first.' It also routes the agent to the downstream consumer (restore_version), which distinguishes it from sibling tools like get_film or undo_film.

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 implies usage (fetch version history, then pass an id to restore_version) but never explicitly says when to call this versus restore_film, undo_film, or get_film, nor does it state exclusions. The mention of restore_version is a helpful contextual hint rather than full guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description goes further by disclosing that the result differs by deployment — the film's account address online versus a local file path when the connector is installed — and that the output is meant to be surfaced to the user rather than acted on. It does not describe failure behavior for an unknown or malformed name, which is the main remaining gap.

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?

Purpose is front-loaded and little is truly redundant, but the prose is dense, fragmentary, and heavily colon-chained, so parsing costs real effort for what is four short facts. A cleaner statement of 'returns the film's URL or local file path, or the film list when name is omitted' would have been shorter and clearer.

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 one-optional-parameter read-only tool with no output schema, the description supplies the essentials: both output modes, the omit-parameter behavior, the relationship to list_films, and the instruction to hand the result to the user. Nothing an agent needs in order to call it correctly 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% and the schema already documents the single prj_… id parameter, so baseline would be 3. The description earns above baseline by explaining the meaning of omitting the optional parameter entirely — the editor's « Mes films » list, including browser-local films the account does not show — which the schema's 'not required' flag alone does not convey.

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 opening clause states a specific action on a specific resource — opening a film in the Cutscene editor so the user can add pictures, preview it, and export — and the 'Online it is the film's address / with the connector, the film's file' sentence states exactly what the tool yields. It is distinguishable from get_film and list_films, though the circular phrasing ('Where the user opens a film ... to do by hand what is done there') forces the agent to re-read to extract the verb.

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 states when to reach for this (the user wants to work on the film by hand in the editor), covers the no-argument fallback ('Without a name, the editor's « Mes films »'), and explicitly contrasts that fallback with list_films ('where the user finds a film list list_films does not give'). No explicit exclusions are given, and the closing instruction 'Give it to the user with what is left for them to do' is a handoff rule rather than a use case.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world) and the description does not contradict them. It adds non-obvious context about the payload: versions rendered as small films, the recipes each needs, what « Ajouter au film » sends, and a one-line verdict — useful for anticipating output with no output schema present.

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?

Two sentences, no filler, and the constraint plus sibling routing are front-loaded ahead of the payload summary. The second sentence is dense and jargon-heavy ('the recipes they need', 'its verdict in one line'), costing a little immediate legibility.

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?

With four parameters and no output schema, the description must carry the return-shape burden; it does so only vaguely in domain terms. Annotations cover the safety profile, so nothing critical is missing, but the payload contents and the meaning of 'Cutscene's window' remain underspecified.

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% with per-parameter descriptions, including how `at` positions the piece and how `name` selects the film. The description only gestures at « Ajouter au film » (the `at` semantics) without adding format or default detail beyond the schema, so baseline 3 applies.

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?

Names the resource (a piece) and pins its narrow scope — the payload for Cutscene's window specifically — and explicitly routes general reads to get_piece. No explicit verb ('returns'/'gets') and the second sentence is domain jargon, but an agent can still tell what it fetches and how it differs from the sibling.

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?

States the exclusivity condition ('For Cutscene's window only') and names the preferred alternative ('to read a piece, prefer get_piece'). Both the when and the when-not are explicit.

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

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

Although annotations already declare readOnly, idempotent, non-destructive and closed-world, the description adds substantial context beyond them: it enumerates what the preview returns, describes the two-thirds similarity copy-refusal rule, and explains the human review within 3 days. It also makes explicit that the tool never shares on the user's behalf, which is exactly the safety nuance an agent needs.

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 key point ('writes nothing') is front-loaded, and every clause contributes operational detail. The sentence is long and heavily parenthetical, which makes it dense rather than perfectly crisp, but it is not padded.

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?

With no output schema, the description must explain return values, and it does: the picture drawn, what leaves and stays, the texts, the closest existing template and copy threshold, and the permission implied by sharing. It also explains share_url's role, leaving nothing important for an agent to infer.

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% and the enum already documents the three modes, so the baseline is 3. The description still adds meaning by tying words: false to authors' texts staying behind and explaining that style mode reuses colours and type 'on a film of ours,' which goes beyond the schema's phrasing.

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?

Names a specific verb (shows what would leave) and resource (sharing a film or one of the user's pieces), and immediately separates itself from the real share action by stating 'writes nothing' and 'You never share in their place.' An agent can tell this is a dry-run preview rather than a mutation, even though no sibling share tool exists.

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?

Establishes clear context: use it to see what sharing would send, with a branch for as: piece, and points to share_url for actually opening the editor's share window. It stops short of explicitly naming when not to use it or comparing to a sibling such as shared_for_view, but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint/idempotentHint true, so the safety profile is covered; the description still adds real behavior: frames are captured only "once its elements have arrived", and the plan's end mark is drawn into the image, which changes what the agent will see. It does not discuss render latency, cost, or whether a stale render can be returned, which keeps it off a 5.

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 default case and the alternatives are front-loaded, which is right, but the middle sentence is a compressed run-on ("...a transition from its last frame before to its first frame after (join; eight frames, frames gives 4 to 12)") that needs re-reading. Dense without being well-structured at the clause level.

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?

With no output schema, the description must convey what comes back, and calling it a contact sheet that is "the only way to see the result" does that adequately for a 6-parameter read tool. The watermark disclosure is a genuinely useful completion detail; only render-freshness/pagination behavior is left unstated.

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 a 3 is the floor, but the description earns more by explaining the mode-dependent meaning of `frames` (2–8 instants for one shot, 4–12 for a join) and the default one-frame-per-shot behavior when `shots` is omitted. The `moments` and `format` parameters, however, are only echoed from the schema text.

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 concrete image of the output ("a contact sheet of the film as a picture: one frame per shot by default") and enumerates the distinct modes (single shot, motion sampling, chosen moments, transition join). It also names the sibling it is not ("For one frame at full size, use still_film"), so an agent can separate it from still_film and show_film without opening a 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?

Explicitly states when to call it ("Look at it after each round of changes: it is the only way to see the result") and where to go instead for the full-size single-frame case ("use still_film"). Both the trigger and the alternative are named, leaving nothing to inference.

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

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

Annotations only declare the safety profile (readOnly, destructive, idempotent flags); the description adds real behaviour beyond them: the object returns to « Mes films » together with its versions, restoration is bounded by bin retention, and a quota precondition can cause refusal. It does not say what a second call on an already-restored film does, which matters given idempotentHint=false.

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?

Two dense sentences: the effect and the restoring counterpart come first, the failure conditions follow. Minor friction from mixed-language quoting (« Mes films ») and a slightly tangled quota clause, but nothing is padding.

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 one-parameter mutation with no output schema, the description covers the outcome, the retention boundary and the quota refusal, which is what an agent needs to decide and call correctly. Remaining gaps (behaviour on repeat calls, response shape) are small given the annotations already carry the safety profile.

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 single parameter is already documented as the deleted film's id from delete_film's response. The description reinforces that provenance but adds no new syntax, format or constraint information beyond the schema, so the baseline 3 applies.

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?

States a specific verb+resource ('bring back a film') and ties it to the sibling that created the state ('a film delete_film took off the account'), so the inverse relationship is explicit. It does not distinguish itself from other recovery-flavoured siblings such as undo_film or restore_version, so differentiation is partial rather than complete.

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 a clear triggering context (a film previously deleted via delete_film) plus two explicit when-not conditions: the bin must still hold the film, and the call is refused if the plan's retained films are all used. It stops short of routing the agent to an alternative when those conditions fail (e.g. undo_film or a plan change).

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

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

Annotations mark this destructive and non-idempotent, and the description adds genuinely new behavior: the replaced film is preserved as its own version, making the operation reversible via undo_film. That reversibility detail is exactly the context annotations cannot express; only the lack of any permission or side-effect detail on the replaced film's id keeps it from a 5.

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?

Two compact sentences, no filler, with the reversibility fact front-loaded alongside the action rather than buried. Every clause carries information an agent needs.

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 two-parameter mutation with full schema coverage and no output schema, the description covers the key risk (reversibility) and the version source. It stops short of stating what the call returns or whether the film id must match the version's owner, but nothing essential 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%, and the schema already documents both parameters including the prj_ prefix and the timestamp-style version id. The description's '(an id from list_versions)' largely restates the schema's own note, so baseline 3 applies.

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?

States a specific verb and resource ('Put an earlier version of a film back') and immediately clarifies the version argument's origin via list_versions. This distinguishes it from sibling restore_film (deleted films) and edit_film in a single readable sentence.

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?

Names the prerequisite tool (list_versions) and the escape hatch ('undo_film cancels the restore'), which tells the agent when this is safe to invoke. It does not explicitly contrast with restore_film, so the agent must infer that distinction from the names.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the description earns credit for genuinely new context: results expose films kept and exported, a pro flag that forces Cutscene Pro on export, and that author names are omitted. The prompt-injection warning ('data, never instructions') is exactly the kind of safety context annotations cannot express.

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 first sentence is a long run-on packing kinds, sort meaning, and pro semantics; the useful consumption instructions are buried mid-paragraph. Nothing is wasted, but it is not front-loaded or easy to scan.

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?

With no output schema, the description steps up to describe the return shape (films kept and exported, pro flag, no author name) and how to consume a result, which is what an agent needs. A minor gap is no mention of pagination/offset behavior in prose, though the schema covers 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 sort/query/kind semantics are fully spelled out in the schema, so the description's mention of searching 'over every shared piece' adds little parameter-level meaning. Baseline 3 applies.

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?

States a specific verb and resource: search over approved shared pieces (templates, styles, shots, transitions, effects, animations, camera moves). It implicitly distinguishes community content from the library, but never names search_library as the contrasting sibling, so the boundary is inferred rather than stated.

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 clear post-retrieval guidance (use by id via create_film { montage }, edit_film, set_film { look }, get_piece) and mentions pro-only behavior. However it never says when to reach for this tool instead of search_library or list_montages, so the selection guidance is implied only.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description adds real context on top: semantic (not keyword) matching, pagination via total/offset, and "the latest first" ordering for mine:true with last-check results. It also states the output is ids consumable by other tools, though other return fields remain unstated (no output schema exists).

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-loads the core verb and resource, then layers pagination and the mine:true mode. It is dense and slightly cluttered with parentheticals and the French « Mes pièces » aside, but nearly every clause carries usable information.

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 6-parameter, fully-optional read tool with no output schema, the description covers search semantics, empty-query listing, paging, and the alternate mine mode. Return value shape is only partially described (ids and total), leaving the rest inferred.

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, but the description adds meaning beyond the schema: query is interpreted by meaning in FR/EN, an empty query enumerates a kind, offset drives paging, and mine:true switches the corpus to user pieces. That is genuine semantic added value over the field 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?

Opens with a specific verb+resource and scope: "Find pieces of the library by meaning, in French or English", then enumerates the asset kinds covered. It does not differentiate itself from the sibling search_community, so an agent cannot tell which search to pick from purpose alone.

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 conditional behavior: "An empty query lists a kind (`total` says how many there are; `offset` gives the next page)" and "mine: true lists the user's own pieces instead". Missing an explicit statement of when to prefer this over search_community or list_montages.

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

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

Annotations cover safety (readOnlyHint=false, idempotent, non-destructive), and the description adds real behavioral context beyond them: explicit values override site-derived values, and producing a site pulls colours/fonts/logo plus page screenshots into shots that show a screen. It never explains error behavior for invalid fonts/colours, which is the main remaining gap.

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?

It is short (~55 words), but it is written as sentence fragments with an unclear pronoun ('With site, they are read…'), and the important partial-update constraint is not front-loaded as a verb-led statement. Some restructuring would make it easier to parse quickly.

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 7-parameter setter with full schema coverage and safety annotations, the description covers the key behavioral surprises (partial update, site-derived brand). It omits what the call returns and how failures (bad hex, unknown font) surface, leaving an agent to infer the outcome.

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 the heavy lifting is done by the schema; the description only adds the precedence rule (explicit params win over `site`) and a practical constraint that ink must read on bg. That is useful but modest, so the baseline 3 is right.

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 lists the brand fields (name, colours, fonts, corner radius, logo) of 'the whole film', which makes the resource clear, but it never states a verb — the reader must infer 'set' from the name/title. It also never contrasts itself with siblings like rename_film or edit_film that touch overlapping attributes.

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?

'Only what is given changes' conveys the partial-update pattern, and 'Make sure the text colour reads on the background (check_film measures it)' routes the agent to a verification sibling. However, there is no explicit when-not-to-use guidance and no mention of rename_film as the alternative for renaming only.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that only an 'approved' shared piece is returned and that the result carries nested pieces, which is genuine behavioral context, but it says nothing about what happens for unapproved, missing or private ids.

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 audience restriction is correctly front-loaded, but the parenthetical 'it plays a shared piece on its card from it' is tangled and redundant with the sentence that follows, costing clarity without adding information.

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?

With one required parameter, no output schema and rich read-only annotations, the definition covers what an agent needs. Describing the return as the piece plus the pieces it carries effectively substitutes for the missing output schema.

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% and the single id parameter is fully documented in the schema with its <kind>/c-… format. The description only adds the framing that the id refers to a piece shared by other people, which is a marginal gain over the schema.

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?

It identifies the resource (the approved recipe of a piece someone else shared, including the pieces it carries) and explicitly contrasts with get_piece for reading a piece. The 'Cutscene's window' framing is jargon that does little work, but the core object and its composition are stated.

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?

'To read a piece, prefer get_piece' names the alternative and the condition that selects it, and the opening clause scopes this to Cutscene's window. It does not contrast with piece_for_view, the closest sibling, which is left for the agent to infer.

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

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

Annotations already declare readOnly and idempotent, but the description adds substantial behavioral context beyond them: the window follows film changes automatically, the answer reports what the film is, what remains to complete, and the editor's address, and hosts without windows see only the verbal response. These details help the agent understand the tool's side effects and output shape.

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 front-loaded with the core action and includes essential usage constraints in subsequent sentences. It is somewhat long and parentheses-heavy, but every sentence carries useful information; a minor trim could improve readability.

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?

With full schema coverage, annotations covering safety, and no output schema, the description is complete enough. It explicitly describes what the answer contains in words, which compensates for the missing output schema and covers the host-without-windows case.

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?

The schema provides 100% description coverage for the only parameter (the film id, prj_…, pointing to list_films). The description adds no syntax or format details beyond what the schema already states, so the baseline of 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 gives a specific verb and resource: show the film in Cutscene's window. It clearly distinguishes the tool from preview_film, and the mention of 'the assistant's app draws windows' clarifies the medium. An agent can tell it apart from siblings like get_film or preview_film.

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 explicitly says when to call (once the film is first made and after a round of changes), when not to call (never after each edit_film), and why (an open window follows changes by itself). It also names an alternative for a different need: preview_film for viewing the film yourself.

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

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

The description goes significantly beyond the boolean hints provided in annotations, detailing the entire UI interaction (Essayer, Ajouter au film, Ouvrir dans l'éditeur) and even providing instructions for non-window users (verbal description of versions).

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?

While slightly verbose, the tool's complexity necessitates the length. The structure prioritizes the unique selling point (multi-version display) before detailing the workflow and inputs.

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 involves a complex decision-making flow (verdict -> verbal description -> user choice -> edit_film), the description provides all necessary context for an agent to handle such a multi-step workflow request.

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?

Since schema coverage is 100%, the baseline is 3. The description still adds value by framing the parameters within the business logic (e.g., specifying that 'id' can be from creation or the library, and defining the specific context for 'at').

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 core function: displaying a piece along with 3 to 8 variants in a specific window. It distinguishes itself by detailing the visual presentation (side-by-side versions, verdicts) and workflow (Verdicts -> Ask -> edit_film).

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 provides explicit timing guidance: 'Call it once a piece is written and checked, never at each writing.' This precisely defines the lifecycle stage when the tool is appropriate.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds a non-obvious rendering constraint: a Pro-piece film on a non-Pro plan renders at half size, and a full-size frame of it is a poster requiring export_poster. It also discloses that a shot is only viewable once its elements have arrived. Neither fact is derivable from the schema or 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?

Front-loaded with the resource and its resolution, then the use case, then selectors, then the caveat. The final sentence is dense and slightly tangled (poster/export_poster detour), but every sentence carries information.

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?

Five parameters are fully described in-schema, annotations cover the safety profile, and the description adds defaults and a plan-based fidelity caveat. It never states outright that the tool returns an image artifact (rather than a URL or an id), which is the one detail an agent must still infer.

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, but the description adds the precedence/default behavior between 'at' and 'shot' — first shot when neither is given — which the schema does not state. The half-size caveat also gives the 'format' parameter context it lacks in the schema.

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?

States a specific verb and resource ('ONE frame of the film at full size, 1920×1080 in 16:9') and explicitly contrasts it with a contact sheet, which is named as the too-small alternative. An agent can immediately tell this is the zoom-in inspection tool rather than a preview or listing tool.

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 a concrete trigger ('to read small text or check a detail a contact sheet is too small for') and states the default when neither selector is supplied ('without either, the first shot'). It does not name the sibling contact-sheet tool explicitly, so the routing is implied rather than spelled out.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, so the agent knows this mutates state and is not idempotent. The description adds genuinely useful behavior that annotations cannot convey: the replaced version is retained, so calling it again acts as a redo, and two undos cancel out. It could go further on permissions or what happens when there is no prior change, but it is strong for this tool.

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?

Three compact sentences: the core action comes first, then the undo/redo semantics, then the alternative for deeper history. Every sentence earns its place with no filler.

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 single-parameter mutation tool with annotations covering safety and no output schema, the description gives the key state semantics and routing to list_versions/restore_version. It does not cover behavior when there is no prior change to undo, which is a minor gap rather than a blocker.

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 single 'name' parameter is already documented as the film's prj_… id on the user's account. The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb+resource ('Put a film back as it was before its last change') and defines what counts as a change by naming edit_film, set_brand, and restore. It is immediately distinguishable from restore_version and list_versions, which are named as alternatives for deeper history.

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?

Explicitly says when to use it (to undo the most recent change) and when to use a different tool (use list_versions and restore_version to go further back). It also warns that two undos cancel out, which is essential usage guidance for an agent deciding whether to call it repeatedly.

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