Skip to main content
Glama
Dorico Maestro

Dorico Maestro

plugin_state

Destructive

Export a VST instrument slot’s saved state from a closed Dorico project or replace it from a .vstpreset, with validation and backup.

Instructions

Export or replace the saved state of a VST instrument slot in a closed project.

Returns:
    Result dictionary with the slot, the preset file and, for import, the backup.

Note:
    Sets what a plugin holds (programs, instruments on channels) without its
    window, which no assistant can operate. Import refuses a preset made for
    another plugin and a project Dorico has open, writes a backup next to the
    project first and tests the rewritten file. It needs ``confirm=True``. Whether
    the project is open comes from Dorico's application log; without one the import
    is refused unless ``dorico_closed=True``.

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": {
      "action": "<action>",
      "path": "<path>",
      "slot": "<slot>",
      "preset_path": "<preset_path>"
    },
    "name": "plugin_state"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesA saved .dorico project.
slotYesSlot as Dorico's window numbers it.
actionYesexport a slot's saved state as .vstpreset, or import one.
confirmNoTrue authorises a change that discards work or cannot be undone.
preset_pathYesThe .vstpreset file to write or read.
dorico_closedNoimport: True states that Dorico does not have the project open; needed only where Dorico's application log cannot be read.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.8

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is largely covered by structured data. The description nonetheless adds genuine value: a backup is written next to the project before rewriting, the rewritten file is tested, and the log-based open-project check is explained. That is solid context, but return format and failure modes remain only partly spelled out.

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-loads the purpose before the Returns/Note sections, and every clause is load-bearing. The Note paragraph is dense and slightly convoluted in its final sentence about the application log, and the Returns block partly duplicates the output schema.

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

Completeness4/5

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

For a destructive, six-parameter import/export tool the description covers the safety preconditions, the backup behavior, and the log-based open-project detection, which is what an agent needs to call it correctly. Since an output schema exists, the Returns section is redundant rather than compensating for a gap.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter, including the enum on action and the dorico_closed fallback, is already documented in the schema. The prose restates the log/dorico_closed relationship and confirm rather than adding new semantics, so baseline 3 applies.

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

Purpose4/5

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

States a concrete verb pair and resource: "Export or replace the saved state of a VST instrument slot in a closed project," with the scope qualifier "closed project" narrowing it usefully. It does not name a sibling (e.g. list_plugins) to contrast against, so it stops short of the top band.

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?

Gives real when-not conditions: import refuses a preset made for another plugin, refuses when Dorico has the project open, and requires confirm=True; dorico_closed only when the application log is unreadable. It lacks explicit routing to alternative tools, but the operational conditions are clear.

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