premiere-pro-mcp

Overview Schema Source Related Servers Discussions Admin

Audit Project Structure

audit_project_structure

Audit a Premiere Pro project panel against layout rules and report violations by node ID; optionally apply verified bin creation, moves, renames, and empty-bin cleanup from a plan token.

Instructions

Audit the Project panel against explicit layout rules (allowed root names, extension-to-bin placement, a sequences bin, maximum bin depth, empty bins, an explicit target_tree of bins with item node IDs, renames, remove_empty) and report violations by node ID. Read-only by default (inspect authority): walks up to 5000 items, reports truncation, and returns at most 200 proposed moves, 200 renames and 200 empty-bin removals plus a plan_token bound to the project, rules, and those exact operations. With apply: true (edit authority) it requires that plan_token, re-reads the project and refuses if the plan changed, the walk was truncated, or any target path is ambiguous (two bins with one name at a level). It then creates missing target bins, moves only the planned items (reading back each parent), deletes only remove_empty bins that are still empty (reading back the parent's children), then renames (reading back each name); target paths are resolved against the audited names, so renames run last. Outcome is verified only when every planned operation is verified, otherwise partial or failed with per-item details. Without target_tree, rename, or remove_empty it never deletes, renames, or moves bins; root-name, depth, and forbid_empty_bins findings are report-only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "rules": "<rules>"
    },
    "name": "audit_project_structure"
  }
}

Input Schema

Name	Required	Description
`apply`	No	false (default) audits without changing Premiere. true creates missing target bins and moves the planned items; requires plan_token and the edit capability.
`rules`	Yes	Layout rules; at least one must be set. Unknown keys are rejected.
`plan_token`	No	Required when apply is true: the planToken returned by the audit with the same rules. Apply refuses if the project's current plan no longer matches it.
`idempotency_key`	No	Optional client-chosen key (1-128 chars of A-Z a-z 0-9 . _ : -) for this intended edit. Pass a fresh key per edit and reuse it only when retrying that same edit, for example after a client-side timeout. A repeat with the same tool, key and arguments is not run again: while the first call is running it fails with IDEMPOTENCY_IN_PROGRESS (poll get_last_operations); after it finished it returns the original outcome marked replayed. A definite failure with nothing applied (receipt outcome not_applied) may be retried with the same key. Reusing a key with different arguments fails with IDEMPOTENCY_KEY_REUSED. Scoped to this MCP session (the stdio server process, or the HTTP server process when Streamable HTTP is stateless per request) and held in memory only (200 keys, 1 hour); it does not survive a restart or reconnect. Read-only invocations are never deduplicated.
`expected_cep_target`	No	Optional reviewed CEP sequence/clip identity and exact tick ranges. Checked before every generated command; UXP refuses this CEP-only guard.
`expected_project_path`	No	Optional absolute saved-project path. Every generated CEP command refuses before its body when the active project differs or is unsaved. UXP commands refuse this CEP-only guard; local-only tools do not inspect Premiere. Omit to keep existing behavior.

Output Schema

Name	Required	Description
`ok`	Yes	Whether the tool completed successfully.
`data`	No	Tool-specific result data when ok is true; on failure, diagnostic detail when the tool provides it.
`tool`	Yes	The registered MCP tool name.
`error`	No	Failure detail when ok is false.
`receipt`	No	Versioned common mutation receipt; success never implies rendered verification.
`idempotency`	No	Present when idempotency_key deduplicated this call: replayed is true when the original outcome was returned instead of running again.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.30.0Nov 14, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes far beyond the annotations: 5000-item walk cap with truncation reporting, 200-per-category operation caps, plan_token bound to project+rules+operations, plan-drift refusal, ambiguity refusal (two bins with one name), per-step readback verification, and renames-last ordering with target paths resolved against audited names. It also discloses final status semantics (verified/partial/failed with per-item details). The only tension is destructiveHint=false while apply can delete empty bins and move items, but deletion is confined to still-empty bins, so this reads as a scoped caveat rather than a contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Front-loaded with the verb and rule set, then read-only behavior, then apply semantics, then the no-op guarantees — a logical progression with essentially no filler. The cost is density: three very long sentences with deeply nested clauses that are hard to parse on one read.

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?

For a six-parameter tool with nested rule objects and an output schema, the description covers the decision-relevant surface: safe vs mutating mode, preconditions, limits, ordering, refusal cases, and result semantics. Return-value detail is correctly deferred to the output schema and parameter detail to the 100%-covered schema.

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?

Schema coverage is 100%, so 3 is the baseline, but the description adds meaning the schema does not: apply requires plan_token, caps of 200 proposed moves/renames/removals, plan_token bound to rules and exact operations, rename ordering relative to path resolution, and that root-name/depth/forbid_empty_bins findings remain report-only. expected_cep_target, expected_project_path and idempotency_key are left entirely to their schema text.

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+resource ('Audit the Project panel against explicit layout rules') and enumerates exactly which rules are checked (root names, extension bins, sequences bin, max depth, empty bins, target_tree) and what it returns (violations by node ID). An agent can distinguish it from siblings like get_project_structure or get_project_panel_metadata purely from this sentence.

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?

Clearly splits read-only default ('inspect authority') from apply:true ('edit authority') and states the precondition (a matching plan_token) and refusal conditions for apply. It also closes off the risky path explicitly: 'Without target_tree, rename, or remove_empty it never deletes, renames, or moves bins.' It does not name sibling audit/inspection tools as alternatives, so 4 rather than 5.

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

Deploy Server