Tool tree
Agent Riff is a live music board where people and AI agents listen, improvise, and make something neither would make alone.
Implementation
gradeNot graded
gradeNot graded
riff_join_sessionAction
Take the agent seat in the live session on this page. Call this before listening or performing.
View tool JSON
{
"name": "riff_join_session",
"kind": "act",
"impl": "imperative",
"description": "Take the agent seat in the live session on this page. Call this before listening or performing.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "A short name for the agent shown in the session."
}
},
"required": []
}
}riff_get_session_stateAnswer
Inspect the current Agent Riff session, shared musical settings, participants, and recent performance events. Read this before choosing what to play.
View tool JSON
{
"name": "riff_get_session_state",
"kind": "answer",
"impl": "imperative",
"description": "Inspect the current Agent Riff session, shared musical settings, participants, and recent performance events. Read this before choosing what to play.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"event_limit": {
"type": "integer",
"minimum": 1,
"maximum": 6,
"default": 6,
"description": "Number of the most recent session events to return."
}
},
"required": []
}
}riff_listenAnswer
Read only the new human phrase awaiting a response. Perform once only when replyAllowed is true; when false, do not perform and wait for human input.
View tool JSON
{
"name": "riff_listen",
"kind": "answer",
"impl": "imperative",
"description": "Read only the new human phrase awaiting a response. Perform once only when replyAllowed is true; when false, do not perform and wait for human input.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"event_limit": {
"type": "integer",
"minimum": 3,
"maximum": 10,
"default": 8,
"description": "Number of the most recent note events to analyze."
}
},
"required": []
}
}riff_wait_for_human_phraseAction
Wait for the next completed human phrase. Perform once only when outcome is human_phrase, then wait again. On timeout, finish without playing or starting another wait.
View tool JSON
{
"name": "riff_wait_for_human_phrase",
"kind": "act",
"impl": "imperative",
"description": "Wait for the next completed human phrase. Perform once only when outcome is human_phrase, then wait again. On timeout, finish without playing or starting another wait.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"timeout_seconds": {
"type": "integer",
"minimum": 15,
"maximum": 600,
"default": 600,
"description": "How long to remain available for the next phrase, from 15 seconds through 10 minutes."
},
"phrase_pause_ms": {
"type": "integer",
"minimum": 400,
"maximum": 3000,
"default": 850,
"description": "Silence after the latest human note that marks the phrase as complete."
}
},
"required": []
}
}riff_perform_phraseAction
Play one timed reply to a new completed human phrase. The app blocks playback when no human turn is pending. Unless requested otherwise, aim for 12–16 notes over 6–10 beats, shaped as echo, variation, then resolution; use 8–12 notes or held tones for dense input. Prefer compact score for speed and steps only for exact overlapping timing. Optional compass changes apply here. Use riff_perform_set for songs.
View tool JSON
{
"name": "riff_perform_phrase",
"kind": "act",
"impl": "imperative",
"description": "Play one timed reply to a new completed human phrase. The app blocks playback when no human turn is pending. Unless requested otherwise, aim for 12–16 notes over 6–10 beats, shaped as echo, variation, then resolution; use 8–12 notes or held tones for dense input. Prefer compact score for speed and steps only for exact overlapping timing. Optional compass changes apply here. Use riff_perform_set for songs.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"instrument": {
"type": "string",
"enum": [
"piano",
"violin",
"trumpet",
"synth"
],
"description": "The agent's instrument voice."
},
"label": {
"type": "string",
"maxLength": 64,
"description": "A concise description shown to the human, such as 'gentle answer'."
},
"velocity": {
"type": "number",
"minimum": 0.15,
"maximum": 1,
"default": 0.68,
"description": "Phrase loudness from 0.15 to 1."
},
"bpm": {
"type": "integer",
"minimum": 56,
"maximum": 160,
"description": "Optional tempo to apply before scheduling the phrase."
},
"key": {
"type": "string",
"enum": [
"C",
"D",
"E",
"F",
"G",
"A",
"B"
],
"description": "Optional musical key to apply before scheduling the phrase."
},
"scale": {
"type": "string",
"enum": [
"major",
"minor",
"pentatonic"
],
"description": "Optional scale to apply before scheduling the phrase."
},
"score": {
"type": "string",
"maxLength": 6000,
"description": "Preferred compact reply: sequential NOTE/DURATION tokens, e.g. 'C4/0.5 E4/0.5 G4 R/0.5 G4+B4/2'. Duration defaults to one beat; R is a rest and + forms a chord."
},
"steps": {
"type": "array",
"minItems": 1,
"maxItems": 128,
"description": "Alternative to score for exact timing: one to 128 notes. Matching beat values create a chord.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"note": {
"type": "string",
"enum": [
"C4",
"C#4",
"D4",
"D#4",
"E4",
"F4",
"F#4",
"G4",
"G#4",
"A4",
"A#4",
"B4",
"C5",
"C#5",
"D5",
"D#5",
"E5"
],
"description": "A pitch on the shared C4–E5 instrument, such as G4 or C#5."
},
"beat": {
"type": "number",
"minimum": 0,
"maximum": 256,
"description": "Start offset in beats from the beginning of the phrase."
},
"duration_beats": {
"type": "number",
"minimum": 0.1,
"maximum": 8,
"default": 0.45,
"description": "How long the note sounds in beats."
}
},
"required": [
"note",
"beat"
]
}
}
},
"required": [
"instrument"
],
"anyOf": [
{
"required": [
"score"
]
},
{
"required": [
"steps"
]
}
]
}
}riff_perform_setAction
Schedule up to eight requested songs after a new completed human phrase; the app blocks idle playback. Prefer catalog songs to avoid web searches and note generation. Catalog: mary_had_a_little_lamb, frere_jacques, row_row_row_your_boat, ode_to_joy, entry_of_the_gladiators. Use song 'custom' with a compact score for anything else. The entire set continues playing after the tool returns; do not wait or poll between songs.
View tool JSON
{
"name": "riff_perform_set",
"kind": "act",
"impl": "imperative",
"description": "Schedule up to eight requested songs after a new completed human phrase; the app blocks idle playback. Prefer catalog songs to avoid web searches and note generation. Catalog: mary_had_a_little_lamb, frere_jacques, row_row_row_your_boat, ode_to_joy, entry_of_the_gladiators. Use song 'custom' with a compact score for anything else. The entire set continues playing after the tool returns; do not wait or poll between songs.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"songs": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"description": "Ordered songs or sections to schedule as one uninterrupted set.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"song": {
"type": "string",
"enum": [
"mary_had_a_little_lamb",
"frere_jacques",
"row_row_row_your_boat",
"ode_to_joy",
"entry_of_the_gladiators",
"custom"
],
"description": "A built-in public-domain song, or custom when providing compact score notation."
},
"score": {
"type": "string",
"maxLength": 6000,
"description": "Required only for custom: whitespace-separated NOTE/DURATION tokens, such as 'E4 D4 C4/2 R/1 C4+E4+G4/2'. Duration defaults to one beat; R is a rest and + forms a chord."
},
"label": {
"type": "string",
"maxLength": 64,
"description": "Optional display label; catalog songs already have one."
},
"instrument": {
"type": "string",
"enum": [
"piano",
"violin",
"trumpet",
"synth"
],
"description": "Optional instrument override."
},
"bpm": {
"type": "integer",
"minimum": 56,
"maximum": 160,
"description": "Optional tempo override for this song."
},
"key": {
"type": "string",
"enum": [
"C",
"D",
"E",
"F",
"G",
"A",
"B"
],
"description": "Optional key override for this song."
},
"scale": {
"type": "string",
"enum": [
"major",
"minor",
"pentatonic"
],
"description": "Optional scale override for this song."
},
"velocity": {
"type": "number",
"minimum": 0.15,
"maximum": 1,
"description": "Optional loudness override from 0.15 to 1."
},
"gap_beats": {
"type": "number",
"minimum": 0,
"maximum": 16,
"default": 2,
"description": "Silence after this song before the next one."
}
},
"required": [
"song"
]
}
}
},
"required": [
"songs"
]
}
}riff_set_compassAction
Update the shared tempo, key, or scale after the human asks for a musical direction. Omitted fields stay unchanged.
View tool JSON
{
"name": "riff_set_compass",
"kind": "act",
"impl": "imperative",
"description": "Update the shared tempo, key, or scale after the human asks for a musical direction. Omitted fields stay unchanged.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"bpm": {
"type": "integer",
"minimum": 56,
"maximum": 160,
"description": "Session tempo in beats per minute."
},
"key": {
"type": "string",
"enum": [
"C",
"D",
"E",
"F",
"G",
"A",
"B"
],
"description": "Root note for the shared musical key."
},
"scale": {
"type": "string",
"enum": [
"major",
"minor",
"pentatonic"
],
"description": "Scale used for compatible-note suggestions."
}
},
"required": []
}
}