davinci-mcp

Overview Schema Source Related Servers Discussions Admin

Audio (write)

audio_write

Destructive

Modify audio state in DaVinci Resolve by applying Fairlight presets, normalizing levels or files, and setting mappings, properties, or voice isolation, with read-back verification.

Instructions

Change audio state; may overwrite current values. Every change is read back from Resolve (receipt.verified=false means it did not take). op.action (params; * = required):

apply_fairlight_preset(name*): Apply a Fairlight preset to the current timeline.
normalize_audio_level(items*, options): Normalize the audio level of timeline items (21.1, Studio).
normalize_file(path, clip, target_lufs, true_peak_dbtp, lra, sample_rate, output, import_to_pool): Two-pass loudnorm of a file into a new file (job); optional Media Pool import. [job]
set_audio_mapping(clip, item, mapping*): Write the audio mapping of a clip, or the source channel mapping of an item (21.1).
set_audio_properties(item*, properties*): Set audio properties of a timeline item (volume, pan, voice isolation, leveler).
set_voice_isolation(item, track, enabled*, amount): Enable/disable voice isolation on an item or audio track (active timeline only). Calls known in advance (a sequence, the same change on several items): ONE batch_run.

Input Schema

Name	Required	Description
`op`	Yes	{action, ...params}. Parameters per action: see the description or this server's describe_action tool.
`dry_run`	No	true: return the planned effect, change nothing.
`snapshot`	No	true: back up the timeline/project first; omitted: server policy.

Output Schema

Name	Required	Description	Default
`job`	No
`plan`	No
`status`	Yes
`receipt`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.4Nov 1, 2026
- addedInput schema / properties / dry_run / description
```
Added value: +"true: return the planned effect, change nothing."
```
- addedInput schema / properties / snapshot / description
```
Added value: +"true: back up the timeline/project first; omitted: server policy."
```
First observedv0.1.0Nov 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the destructiveHint/non-idempotent annotations by stating that changes may overwrite current values, that every change is read back from Resolve, and how to interpret receipt.verified=false. It also flags version/edition requirements ('21.1', 'Studio') and marks job-based actions with [job], which are real behavioral constraints 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the mutation and verification caveats, then presents actions as a scannable bulleted list with required params marked. No filler sentences; the batch_run note is a single purposeful line at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be explained, and the description still covers the receipt.verified semantics that matter for judging success. dry_run/snapshot are documented in the schema, and the only mild gap is not pointing job-based actions at job_wait/job_status, which is discoverable from the sibling list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Top-level schema coverage is 100%, but the action-specific params live under an open nested object, so the description does real work by listing each action's parameters and marking required ones with '*'. Some entries stay thin (e.g. the `options` object for normalize_audio_level, and units/ranges for target_lufs and true_peak_dbtp are left to inference).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Change audio state') and then enumerates all six concrete actions with their parameters, so the agent knows exactly what surface is covered. It is clearly distinguishable from the audio_read sibling and from timeline_write/item_write by naming audio-specific operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes multi-change workloads to batch_run ('Calls known in advance... ONE batch_run') and scopes set_voice_isolation to the active timeline only. It doesn't spell out when to prefer audio_write over item_write/timeline_write for overlapping properties, nor preconditions like project/timeline state.

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