@jam-jam/convert-mcp

Add a song to my notebook

jj_create_song

Adds a song using a standard payload to a private notebook. Files converted songs or edits existing entries without creating duplicates.

Instructions

Adds a song to the calling account's PRIVATE notebook. song is the canonical pivot payload: exactly the object returned by jj_get_song (song) or by a conversion whose output is "songbook", so converting then filing is a copy with no transformation. The id is DERIVED, never random: song.id if given, otherwise an "artist-title" slug. That means posting the same song twice REPLACES it instead of creating a duplicate, and it is also how you rewrite a song wholesale (read it with jj_get_song, edit the payload, post it back with its id). Adding NEVER publishes anything on the public profile. Consumes one unit of the daily WRITE quota (200/day free, 5000 Premium).

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": {
      "song": "<song>"
    },
    "name": "jj_create_song"
  }
}

Input Schema

Name	Required	Description
`song`	Yes	Canonical pivot payload. `title` is required and non-empty; `artist`, `sections[].lines[].lyrics`, `sections[].lines[].chords[] = { offset, chord }`, `detectedKey { tonic, scale }` and `metadata { capo, bpm }` are the usual fields. Validated by the same gate as a .jamsong import in the app; hard cap 512 KB.
`publish`	No	NOT ACCEPTED HERE, and passing it is an error rather than a no-op. Adding a song and publishing it on a public profile are two different decisions: publish afterwards with jj_update_song, once the person has said which rights declaration applies.
`playlistIds`	No	COMPLETE target state of playlist membership, not a delta: the song joins the playlists listed and LEAVES every other one. [] removes it from all of them. Omit to leave memberships untouched.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.2Nov 13, 2026

TDQS

A4.7/5.0

Behavior5/5

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

No annotations are supplied, and the description carries the full burden well: it discloses private-by-default scope, that nothing is published, derived-id replace semantics (no duplicates), the 512 KB cap and import-gate validation, and a concrete write-quota cost (200/day free, 5000 Premium). It also flags that passing `publish` is an error rather than a silent no-op, which is exactly the kind of trap an agent needs disclosed.

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?

Purpose is front-loaded and every sentence carries information, but the prose is dense and heavily capitalized, packing four distinct behaviors into one long sentence about ids that takes a second pass to parse. Slightly more structure or line-separation would improve scanability without losing content.

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 mutation tool with no annotations and a nested payload, it covers scope, safety, quota, idempotency, and payload constraints thoroughly. The one gap is that no output schema exists and the description never says what a successful call returns, so an agent must guess whether the created song or its derived id comes back.

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 schema already documents all three parameters including the publish rejection and playlistIds target-state semantics. The description adds genuine meaning the schema does not spell out in prose: how the id is derived (song.id or an "artist-title" slug) and why that makes posting idempotent. That is meaningfully above the baseline for a fully documented schema, though the playlist behavior is largely a restatement.

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 ("Adds a song to the calling account's PRIVATE notebook") and immediately distinguishes this path from public publishing and from the update path. An agent can tell this apart from jj_update_song and jj_create_playlist without opening a schema.

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?

Gives explicit routing: it is the filing step after a conversion whose output is "songbook"; rewriting is done by reading with jj_get_song, editing, and posting back with the id; publishing is deferred to jj_update_song once rights are declared. That covers when to use it and which sibling to use instead for the adjacent decision.

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