Skip to main content
Glama
Dorico Maestro

Dorico Maestro

add_rest

Inserts one rest of a specified duration at the caret in Dorico and advances the caret, leaving rest-input mode unchanged. Use goto_bar first to choose where the rest lands.

Instructions

Input one rest at the caret.

One rest at the current caret position, which then advances by that duration.
It switches rest input on, presses the rest key and switches rest input off
again, so rest mode is left as it was found. After ``goto_bar`` note input
stays on and the next call continues; otherwise it is entered and exited here.

Returns:
    Result dictionary with success, the duration entered, the undo flag and the
    resulting mode.

Note:
    Success means Dorico accepted the command (kOK), not that the rest is where
    it was wanted (docs/protocol.md, 'Command Acceptance vs Effect'). Check with
    get_status or by inspecting the score.

    For a passage, put rest events in a ScoreSpec and use write_score. Use
    goto_bar first to choose where a single rest lands.
    Do not read can_undo as evidence: entering note input alone already sets it.

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": "add_rest"
  }
}

Input Schema

NameRequiredDescriptionDefault
durationNoRhythmic duration, one of: whole, half, quarter, eighth, sixteenth, 32nd, 64th. Case-insensitive.quarter

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.2
    • addedInput schema / properties / duration / description
      Added value: +"Rhythmic duration, one of: whole, half, quarter, eighth, sixteenth, 32nd, 64th. Case-insensitive."
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent), the description discloses that rest input is switched on and then off so the prior mode is preserved, that note input persists after goto_bar, and that success means kOK command acceptance rather than the intended musical effect. It even warns that can_undo is not evidence, which is exactly the kind of caveat annotations cannot express.

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?

It is front-loaded with the core action and organized into clear paragraphs. Some redundancy exists: the one-line summary is immediately restated, and the 'Returns:' block partially duplicates the output schema, though it does add the resulting mode.

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 single-parameter mutation with an output schema, the description covers mode side effects, verification strategy (get_status or inspecting the score), and the batch alternative. Nothing an agent needs to call it correctly and interpret the result is missing.

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% and the duration enum values are documented in the schema, so the baseline is 3. The description adds meaning by stating that the caret 'advances by that duration' and by defaulting behavior to a single rest at the caret, which clarifies the effect of the parameter beyond its type.

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 opening line states a specific verb and resource ('Input one rest at the caret'), and the body scopes it to exactly one rest at the caret position. It is clearly separable from siblings that write passages (write_score) and from positioning tools (goto_bar).

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?

Explicit routing is given: 'For a passage, put rest events in a ScoreSpec and use write_score' and 'Use goto_bar first to choose where a single rest lands.' It also implies when this tool is the right choice (a single rest) versus the alternative, with no ambiguity left.

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