Skip to main content
Glama

Fit a melody to a music box

fit_melody_to_box
Read-only

Adjusts a melody so it can be played on a music box and lists every change. Strategies: "transpose" (shift the whole melody to the key that fits best), "nearest_note" (move each unplayable note to the closest playable one), "transpose_then_nearest" (default: both). Optionally snaps notes to a grid. Returns the new melody and its validation.

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": {
      "box": "<box>",
      "bpm": "<bpm>",
      "notes": "<notes>"
    },
    "name": "fit_melody_to_box"
  }
}

Input Schema

NameRequiredDescriptionDefault
boxYesMusic box type: "15", "20", "30" (notes) or "freestyle" (digital only). See list_music_boxes.
bpmYesTempo in beats per minute (30-300).
notesYesNotes in any order, at most 2000. Only onsets matter: music boxes have no note durations.
strategyNo
target_boxNoBox to fit into. Defaults to the melody's box.
quantize_beatsNoSnap every note to this grid in beats (e.g. 0.5 = eighth notes).
illegal_threshold_ticksNoMinimum gap between two identical notes, in ticks (default 384 = 2 beats).

Output Schema

NameRequiredDescriptionDefault
melodyYes
changesYes
summaryYes
semitonesYes
validationYes
composer_linkNoOpens the composer with the fitted melody loaded, without saving.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / composer_link
      Added value: +{
      +  "description": "Opens the composer with the fitted melody loaded, without saving.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds behavioral context beyond that: it lists every change made, reports the new melody and its validation, and describes what each strategy mutates. Consistent with a non-destructive read/compute operation.

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?

Three compact sentences, front-loaded with the core action, then strategies, then the optional grid snap and return value. No filler, though the strategy sentence is dense.

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?

An output schema exists, so return values needn't be spelled out, yet the description briefly notes it returns the new melody and validation. With 7 params, 3 required, and high schema coverage, an agent has what it needs, though the box-vs-target_box relationship and strategy tradeoffs could be clearer.

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?

The schema omits a description on the 'strategy' enum, so the description carries it: it defines transpose, nearest_note and transpose_then_nearest (default). It also explains quantize snapping. This adds real meaning beyond the 86% schema coverage baseline.

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 specific verb and resource: 'adjusts a melody so it can be played on a music box and lists every change.' This clearly distinguishes it from a plain validation tool, though it never names the sibling validate_melody or any other near-neighbor.

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

Usage Guidelines3/5

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

Implies its use case (fitting a melody that isn't playable) and explains the three strategies plus which is default, but never states when to use this instead of validate_melody or render_audio. Guidance is implied rather than explicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources