goldseam

Playlist Run

playlist_run

Play a person's held courses through a checklist's stored playlist and get their progress line by line. Give checklist_id and held, the whole list each time. Five held courses are landed per call: a course taken at the playlist's school lands as itself, a course from another school lands as the receiving course the school's known transfer rules name, a course with no known mapping is unresolved, and a failing or withdrawn grade (F, U, NC, W) does not land. An answer that is not done carries continue: send continue back unchanged, with the same checklist_id and held, until the answer says done. Slots, areas and the open elective are settled on the last call, whose answer gives the summary, every line with its state and the held course that met it, what the person still needs, what did not count and why, the playlist's id, status and source, and a run_token. If no active, validated playlist is held for the checklist, the answer says so and names playlist_open as the next call; a run is never made against the harvested checklist. Pass first_run true when the playlist was assembled in this same conversation, immediately before the run. The person's courses are never stored: they come in each call and go back in continue, which you keep. Only the run's line states, counts and timings are recorded, after the answer.

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": {
      "checklist_id": "<checklist_id>",
      "held": "<held>"
    },
    "name": "playlist_run"
  }
}

Input Schema

Name	Required	Description
`held`	Yes	The courses the person holds, as many as there are, the whole list on every call, in the form checklist_map accepts: each { unitid or school, code, title, credits, grade, term }
`continue`	No	From the previous answer: its continue, sent back unchanged. Leave it out on the first call
`first_run`	No	First call only: true when the playlist was assembled in this same conversation, immediately before the run; otherwise the run is recorded as a hit
`checklist_id`	Yes	The checklist, by its checklist_id from a CourseShelf answer

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 10, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=false; the description adds the real behavioral core — chunking at five held courses per call, the continue-loop protocol, transfer-rule resolution vs. unresolved, failing grades not landing, and the fact that run states/counts/timings are recorded after the answer. That recording detail is what explains readOnly=false, so the description and annotations reinforce each other rather than repeat.

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 the long middle sentence is dense with distinct rules (same-school, transfer-mapped, unresolved, failing grades), each earning its place. It loses a point for repetition: the 'whole list each time / same checklist_id and held / courses never stored' idea is stated three times in different sentences.

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?

With no output schema, the description carries the return contract and does so thoroughly: the final answer's summary, every line with its state and the held course that met it, what is still needed, what did not count and why, playlist id/status/source, and run_token. It also discloses the persistence boundary (courses never stored; only line states, counts and timings recorded), which an agent needs before invoking a non-read-only tool.

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 earns a point by explaining the cross-call protocol rather than field-by-field meaning — held must be the whole list on every call, and continue must be echoed back unchanged alongside the same checklist_id and held. Most of this restates schema text, but the loop semantics are clearer when stated together.

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 — 'Play a person's held courses through a checklist's stored playlist' — plus the output shape ('progress line by line'), which no sibling name alone conveys. The scope ('the whole list each time', five courses landed per call) further distinguishes it from a simple playlist_read.

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?

Explicit preconditions and a named fallback: if no active, validated playlist is held, the answer names playlist_open as the next call, and 'a run is never made against the harvested checklist' rules out a misuse. It also gives the first_run condition ('true when the playlist was assembled in this same conversation, immediately before the run'), so the agent knows when to set it.

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

All goldseam tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.