Skip to main content
Glama
Dorico Maestro

Dorico Maestro

save

Destructive

Write the open project over its existing file and wait until saving finishes, returning the path and confirming the file reads as a complete zip.

Instructions

Save the open project over its file and wait until the file is complete.

Returns:
    Result dictionary with ``file`` (path, bytes, ``complete``) once Dorico has
    finished writing and the file reads as a whole zip.

Note:
    Dorico answers kOK before it writes: a 22 MB project was measured still being
    written seconds later, and a copy taken then was a broken zip. So this waits
    for Dorico's own finishing line in its application log, takes the path from
    the log, and tests the zip. ``Notify=true`` sends no completion message
    (Dorico Elements 6.2.40).

    A project that has never been saved opens a Save As dialog here; use
    project_file(action='save_as') for that. This overwrites the .dorico file in
    place, and Dorico may also copy the previous version into its backup folder.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "save"
  }
}

Input Schema

NameRequiredDescriptionDefault
timeoutNoSeconds to wait for the file to be written.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.8
    • addedInput schema / properties / timeout
      Added value: +{
      +  "default": 120,
      +  "description": "Seconds to wait for the file to be written.",
      +  "maximum": 600,
      +  "minimum": 1,
      +  "title": "Timeout",
      +  "type": "number"
      +}
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only flatly declare destructive=true and non-idempotent; the description supplies the actual mechanics: Dorico acks before writing, a 22 MB project was still being written seconds later, so it waits for the application-log finishing line, reads the path from the log, and validates the zip. It also discloses that the previous version may be copied into Dorico's backup folder and that Notify=true suppresses the completion message, which is real behavior no annotation conveys.

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?

The core action and its blocking semantics are front-loaded, then Returns and Note sections are cleanly delineated. The 22 MB anecdote is illustrative rather than strictly necessary, and the paragraph is on the long side, but every remaining sentence (log wait, zip check, Save As fallback, overwrite, backup) carries information an agent needs.

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 complexity-heavy, race-condition-prone mutation with an output schema already covering the return shape, the description covers the dangerous parts thoroughly. The one omission is that it never warns the call can block for up to the timeout ceiling (default 120s, max 600s), which matters for an agent sequencing other calls.

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?

There is a single parameter (timeout) and the schema documents it fully at 100% coverage, including default 120 and max 600, so the baseline is 3. The description never mentions the timeout at all, so it adds no meaning beyond the schema and leaves the agent unaware of the blocking-duration bound from prose alone.

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?

The first sentence gives a specific verb and resource plus a non-obvious behavioral scope: save the open project over its file AND block until the write is genuinely complete. This distinguishes it from a naive 'save' and from the save-as path, which is named explicitly later.

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

Usage Guidelines5/5

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

It states the exclusion condition ('a project that has never been saved opens a Save As dialog here') and names the correct alternative, project_file(action='save_as'). It also clarifies the overwrite-in-place semantics, so an agent knows when this is the right call and when it is not.

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