@jam-jam/convert-mcp

Get one notebook song

jj_get_song

Retrieve a notebook song by its stable ID and return its full canonical payload—sections, lines, chords, lyrics, key, and metadata—so it can be read and written back unchanged.

Instructions

Returns one song of the calling account's notebook in full: the summary fields AND song, the canonical pivot payload (sections, lines, chords with their offsets, lyrics, detectedKey, metadata). That payload is exactly what jj_create_song and jj_update_song accept, so reading then writing back is a copy, not a translation. An unknown id and an id belonging to another account both return the same not-found error.

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": {
      "songId": "<songId>"
    },
    "name": "jj_get_song"
  }
}

Input Schema

Name	Required	Description	Default
`songId`	Yes	Stable notebook song id (an "artist-title" slug), as returned by jj_list_songs.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.2Nov 13, 2026

TDQS

A4.4/5.0

Behavior4/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 well: it discloses the return shape (summary fields plus the canonical `song` payload with sections, lines, chords, lyrics, detectedKey, metadata) and the round-trip fidelity guarantee. It also discloses a non-obvious error behavior — unknown ids and ids from another account produce an identical not-found error — which is genuinely useful security/scoping context. It stops short of stating permissions or read-only guarantees explicitly.

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 sentences, front-loaded with the return contents and then the round-trip guarantee and error semantics. Every sentence contributes; the 'copy, not a translation' phrasing is slightly ornate but conveys a real behavioral property.

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?

There is no output schema, so the description must describe the return value, and it enumerates the payload contents in enough detail to act on. Error behavior and account scoping are covered, leaving nothing an agent needs before calling it.

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%, so the baseline is 3; the description adds meaning by tying invalid `songId` values to the uniform not-found error, clarifying that the agent cannot distinguish 'doesn't exist' from 'not yours'. The slug format and provenance are already in the schema, so nothing further is added there.

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?

States a specific verb and resource ('Returns one song of the calling account's notebook in full') and scopes it with 'one' versus the sibling list tool. The agent can tell this is a single-resource read without opening the schema.

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?

Implies the read-then-write workflow by noting the payload is exactly what jj_create_song and jj_update_song accept, which tells the agent when this tool is the right starting point. It does not explicitly name jj_list_songs as the way to obtain an id or state when not to use it, so it falls short of full when/when-not guidance.

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