Skip to main content
Glama

owa_lyric_file

List, read, create, update, rename, revert, or delete Open Lyric song documents, leaving edits unsaved for user review and keeping backups for undo.

Instructions

Look at and change the user's songs (Open Lyric documents). list names what is there, info reads one, create makes a new one, update changes one, rename renames one, revert drops its unsaved edits (the editor's Discard, undoable here), delete moves one to the trash. For create and update, content is the Open Lyric document itself: Markdown with an ol:Config fence carrying Title and Structure (required); Artist, Copyright, Key, Tempo (120bpm) and Time (4/4) only when known, never a placeholder. Then one fence per section (ol:Verse 1, ```ol:Chorus). Refused, with why, if it does not parse. Nothing is lost: delete goes to the trash, create refuses a taken name, update -- like every edit -- stays UNSAVED (a * beside the name, Ctrl+Z undoes it) for the user to Save, and every change keeps a backup owa_undo puts back -- say so afterwards. Ask before changing what they did not ask about.

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>"
    },
    "name": "owa_lyric_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoThe name as it reads in the list, with no folder and no file extension. Not needed for `list`.
pageNo
actionYesWhat to do
contentNoRequired by `create` and `update`
newNameNoThe new name, for `rename` only
fontFamilyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2026.11.15

TDQS

A4.2/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: `delete` goes to the trash rather than destroying, `create` refuses a taken name, `update` leaves edits UNSAVED with a '*' indicator and Ctrl+Z, and every change keeps a backup restorable via owa_undo. It even discloses the refusal path when the document does not parse.

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 most important information is front-loaded: the action list comes first, then the content format, then the safety guarantees. It is a dense single block, though, and the content-format sentence is long enough that an agent must parse carefully to extract the fence syntax.

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 seven-action tool with no output schema and no annotations, the definition covers mutation semantics, error behavior, and undo/backup recovery well enough to call it safely. The remaining gap is the two undocumented parameters (`page`, `fontFamily`) and no hint of what `info` or `list` actually return.

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?

`content` is explained far beyond the schema's bare 'Required by create and update': the exact Markdown shape, the required ol:Config Title/Structure fence, optional Artist/Copyright/Key/Tempo/Time, the 'never a placeholder' rule, and one fence per section. Against 67% schema coverage that is strong, but `page` and `fontFamily` receive no explanation in either place.

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?

The description opens with a concrete verb+resource ('look at and change the user's songs') and then defines each of the seven enum actions individually, so an agent knows exactly what `revert` or `revert`-vs-`delete` means. It does not differentiate itself from the sibling tools owa_lyric_edit or owa_lyric_validate, which is the only thing keeping it off a 5.

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?

Each action carries an implicit use case (`list` names what is there, `info` reads one, `revert` drops unsaved edits) and there is explicit cautionary guidance: 'Ask before changing what they did not ask about' and 'say so afterwards' about the backup. What is missing is any routing advice between this tool and owa_lyric_edit, whose overlap is not addressed.

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