add_captions

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

With no annotations, the description carries the full load and does add real behavioral context: the result is a genuine Premiere caption track that is editable/stylable in the Text panel, SRT-exportable, and burnable, plus RTL support. It omits what happens if a caption track already exists, whether the operation is additive or replacing, and failure modes.

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?

Four short sentences, front-loaded with the core action, and the capability notes are placed after. Slightly list-like at the end 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?

No annotations and no output schema, so the description must cover both safety profile and result; it covers the result qualitatively but leaves preconditions (active sequence, existing caption tracks) and the format enum semantics undocumented.

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 only 33% and the description does not compensate: the format enum values (cea608, teletext, op42, etc.) are never explained, and the 'timed text' phrasing only loosely reinforces that start/end are times. The name and captions array are documented in the schema, so baseline-ish credit is fair.

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 — 'Create a caption (subtitle) track on the active sequence from timed text' — and qualifies the source of the data. It only implicitly differentiates from siblings like import_captions and add_text_captions by the 'from timed text' phrase rather than naming 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?

The phrase 'from timed text' hints that this is for programmatically supplied caption data rather than an imported file, but the description never says when to pick this over import_captions or add_text_captions, nor that an active sequence must exist first.

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