Burn styled captions onto a clip

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the karaoke style highlights the active word, but it does not disclose side effects (e.g., whether it overwrites the clip), reversibility, output format, or any prerequisites. For a mutation tool, this is a significant 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?

The description is two sentences with zero redundancy, front-loading the main purpose and then adding one key behavioral detail about the karaoke style. Every word earns its place, and the structure is clean and 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 tool with 9 parameters, no output schema, and no annotations, the description is too sparse. It doesn't explain the role of most parameters, doesn't mention that it appears to be job-based (given the required job_id), and doesn't clarify what happens to the clip after styling. The description leaves too much for the 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 description coverage is only 33%, and the description adds little beyond that. It mentions the karaoke style behavior, but that's already captured by the highlight_color parameter description and the style enum. Other parameters like position, font_name, font_size, and uppercase are left unexplained, and the description does not compensate for the low schema coverage.

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 uses the specific verb 're-style' and the resource 'captions of one clip', making it clear the tool modifies existing captions rather than adding new ones. The parenthetical 'clips already ship with default captions' clarifies scope and distinguishes it from any caption-adding tool among the 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?

The description implies when to use the tool (when you want to change the style of existing captions) by noting that clips already have captions, but it doesn't explicitly state when not to use it or name alternative tools like recut_clip or process_video. The guidance is implicit, not explicit.

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