timeline_create_subtitles_from_audio

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 reveals the method (speech-to-text), the output (subtitle track items), the version requirement, and the return value. It does not mention potential side effects like overwriting existing subtitles, failure behavior, or whether it is non-destructive, leaving some ambiguity.

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 tightly written in three sentences plus a return value line. It front-loads the main action, includes only essential details (feature, requirement, return), and has no fluff or redundancy.

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 parameterless tool with an output schema, the description covers the action, method, version prerequisite, and return value. It is largely complete, though it could additionally mention failure behavior or side effects like duplicate subtitle track creation on repeated runs.

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 has zero parameters, and the schema is empty with 100% coverage. Per calibration guidance, the baseline for 0 params is 4. The description adds context by specifying the input source ('audio in the current timeline') and the tool's mechanism, which is sufficient for the agent.

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 tool's function: 'Auto-generate subtitles from audio in the current timeline.' It uses a specific verb ('generate'), identifies the resource ('subtitles from audio' in the timeline), and distinguishes itself from sibling tools like clip_transcribe_audio by explicitly mentioning it creates subtitle track items in the timeline.

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 clear context by noting it uses Resolve's built-in speech-to-text and requires DaVinci Resolve 18.5 or later, which helps the agent understand when the tool is applicable. However, it does not explicitly list alternatives or state when not to use it, so it stops short of full guidance.

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