@jam-jam/convert-mcp

List my notebook songs

jj_list_songs

List songs in the calling account's private Jam Jam notebook page by page, oldest update first, using cursor pagination and optional updatedSince filtering for incremental exports.

Instructions

Lists the songs in the calling account's PRIVATE Jam Jam notebook, page by page, oldest update first. fields="summary" (default) gives id, title, artist, key, capo, bpm, playlistIds and updatedAt; fields="full" adds the complete pivot payload (chords, lyrics, sections) and lowers the page cap to 25. Use the returned nextCursor to get the next page, and stop when it is null. Consumes one unit of the daily READ quota (2000/day free, 20000 Premium), never a conversion.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "jj_list_songs"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Page size, default 30, hard cap 100 (25 when fields="full").
`cursor`	No	Opaque cursor from a previous call's `nextCursor`. Replay it verbatim; never build one.
`fields`	No	"summary" (default) or "full" to include the complete song payload.
`updatedSince`	No	ISO 8601 date. Returns only objects STRICTLY newer (updatedAt > updatedSince). Keep the largest updatedAt you received and pass it back next time for an incremental export.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.2Nov 13, 2026

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so: it discloses ordering, page-size caps that vary by fields mode, the cursor termination condition, and the exact quota cost (one READ unit, 2000/day free, 20000 Premium, 'never a conversion'). An agent knows the cost profile and paging behavior before calling.

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 dense sentences with no filler: scope and ordering first, then fields/mode effects, then the paging loop and quota cost. Every clause carries decision-relevant information, including the quota detail.

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, and the description compensates by describing the returned fields per mode and the nextCursor page contract. Combined with the quota statement and incremental-sync hint, an agent has everything needed to call and page this tool correctly.

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, but the description adds meaning the schema does not: it enumerates the fields returned under fields="summary" (id, title, artist, key, capo, bpm, playlistIds, updatedAt) and what "full" adds (chords, lyrics, sections) plus the lowered page cap. That is genuine return-shape information rather than a restatement of parameter descriptions.

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 names a specific verb and resource ('Lists the songs'), pins the scope to 'the calling account's PRIVATE Jam Jam notebook,' and states ordering ('oldest update first'). 'PRIVATE' and 'calling account' implicitly separate it from sibling jj_list_profile_songs, but no sibling is named explicitly, so it stops short of 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?

It gives a concrete call pattern: use nextCursor for the next page and stop when it is null, plus the updatedSince incremental-export pattern (keep the largest updatedAt and pass it back). There is no explicit statement of when to prefer a different listing tool, so the tool-selection guidance is implied rather than spelled out.

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