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.