@jam-jam/convert-mcp

Convert a local file

jj_convert_file

Converts local files by uploading a path or base64 content to the Jam Jam API, waiting for completion, and returning embedded text for small text formats or a file path for binary outputs.

Instructions

Uploads a local file (path, or base64 content) to the Jam Jam API, waits for the conversion to finish, and returns the result: embedded text for small text formats (ChordPro, .lrc, .lab...), or a local file path for binary formats (PDF, MIDI, MP4...). Call jj_list_formats first to find valid "output" ids for your input. Consumes one unit of the conversion quota (6/week free, 500/month Premium, see jj_check_usage), which is a different counter from notebook reads and writes.

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": {
      "output": "<output>"
    },
    "name": "jj_convert_file"
  }
}

Input Schema

Name	Required	Description
`path`	No	Absolute or relative local path to the file to convert. Mutually exclusive with contentBase64.
`output`	Yes	Output format id from jj_list_formats (e.g. "pdf-songbook", "midi", "songbook").
`deliver`	No	"download" (default) returns the artifact; "carnet" saves it to the caller's Jam Jam notebook instead (requires an account).
`options`	No	Extra per-format options, see jj_list_formats for the target format.
`filename`	No	File name (with extension). Required with contentBase64; defaults to the basename of "path".
`maxWaitMs`	No	Maximum time to wait for the job to finish, in milliseconds (default 120000, hard cap 600000). If exceeded, the job keeps running server-side; poll it with jj_get_job.
`inputFormat`	No	Input format id from jj_list_formats (e.g. "pdf-songbook", "audio-file"). Omit to let the server detect it.
`contentBase64`	No	Base64-encoded file content. Mutually exclusive with path. Requires "filename".

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.2Nov 13, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the burden well: it discloses the blocking upload-and-wait behavior, the two possible return shapes (embedded text vs. local file path), that exceeding maxWaitMs leaves the job running server-side, and the exact quota cost (1 unit; 6/week free, 500/month Premium) tracked separately from notebook operations. It omits failure modes such as invalid output ids or oversized uploads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and its return contract, then prerequisites, then cost. Every sentence carries operational information with no filler.

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 an 8-parameter tool with nested options, no output schema, and no annotations, the description covers the essential unknowns: what is returned in each case, how long it blocks, what happens on timeout, and what it costs. Remaining gaps (error behavior, size limits) are secondary but non-trivial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including path/contentBase64 exclusivity, output ids, deliver, and maxWaitMs limits is already documented in the schema. The description adds only the quota framing rather than new per-parameter meaning, so the baseline of 3 applies.

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?

Names a concrete verb and resource ("Uploads a local file ... to the Jam Jam API, waits for the conversion to finish, and returns the result") and scopes the input as a local file path or base64 content, which implicitly separates it from the text-oriented jj_convert_text sibling. It stops short of naming that sibling explicitly, so the differentiation is inferable rather than stated.

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?

Gives an explicit prerequisite ("Call jj_list_formats first to find valid output ids") and routes overflow handling to jj_get_job via the maxWaitMs note in the schema. It does not state when to prefer jj_convert_text over this tool, so a full when/when-not comparison is absent.

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