{"id":"chord-check","title":"Chord check: identify, spell, key membership, transpose","description":"Names a chord from its notes, spells a chord symbol into notes, tests whether a chord is diatonic to a key, or transposes a chord symbol, using pitch-class arithmetic over a fixed table of 21 chord qualities, for agents handling lead sheets and music metadata. Rule-based and labelled: when several readings are equally valid (C E G A is C6 or Am7/C) or no quality in the table matches, it returns unknown with the candidates instead of choosing. Does NOT use harmonic context, analyse progressions, infer keys, or know quality names outside its table.","roi":"Stops an agent asserting a chord name or key the notes do not support.","audience":"business","package":"creative-games-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/chord-check","path":"/api/v1/chord-check","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["identify","spell","key-membership","transpose"]},"notes":{"type":"array","items":{"type":"string","maxLength":6,"description":"Note name such as C, Eb, F#, Bbb, C##, optionally with octave (C4). Bass is the lowest note when every note has an octave, else the first."},"maxItems":8,"minItems":2,"description":"For identify: 2 to 8 notes."},"chord":{"type":"string","maxLength":24,"description":"Chord symbol, root A-G with optional #/b, quality suffix, optional /bass: Cmaj7, F#m7b5, Bb/D."},"key":{"type":"object","additionalProperties":false,"required":["tonic"],"description":"For key-membership.","properties":{"tonic":{"type":"string","maxLength":3,"description":"Key tonic, e.g. A or Eb."},"mode":{"type":"string","enum":["major","minor","harmonic-minor"],"description":"Default major. minor is natural minor."}}},"semitones":{"type":"integer","description":"For transpose: semitones up (negative down).","minimum":-48,"maximum":48},"prefer":{"type":"string","enum":["sharps","flats"],"description":"Accidentals for a natural root when transposing. Default sharps; a root written with # or b keeps its kind."},"expectChord":{"type":"string","maxLength":24,"description":"Optional claimed chord symbol to verify (identify, transpose)."},"expectNotes":{"type":"array","items":{"type":"string","maxLength":4,"description":"A claimed note name."},"maxItems":8,"description":"Optional claimed notes in order, to verify (spell)."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"operation":{"type":"string"},"chord":{"type":"string","maxLength":200,"description":"Normalised chord symbol."},"readings":{"type":"array","items":{"type":"object","properties":{"root":{"type":"string"},"quality":{"type":"string"},"symbol":{"type":"string"},"bass":{"type":"string"},"rootPosition":{"type":"boolean"},"rootPc":{"type":"integer"},"bassPc":{"type":"integer"}}}},"notes":{"type":"array","items":{"type":"string"},"description":"Spelled chord tones, bass first when it is not a chord tone."},"pitchClasses":{"type":"array","items":{"type":"integer"},"description":"Sorted pitch classes, C = 0."},"diatonic":{"type":"boolean"},"outOfKey":{"type":"array","items":{"type":"string"}},"degree":{"type":"integer","description":"Scale degree of the chord root when it is in the scale."},"scale":{"type":"array","items":{"type":"string"}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"operation":{"type":"string"},"chord":{"type":"string","maxLength":200,"description":"Normalised chord symbol."},"readings":{"type":"array","items":{"type":"object","properties":{"root":{"type":"string"},"quality":{"type":"string"},"symbol":{"type":"string"},"bass":{"type":"string"},"rootPosition":{"type":"boolean"},"rootPc":{"type":"integer"},"bassPc":{"type":"integer"}}}},"notes":{"type":"array","items":{"type":"string"},"description":"Spelled chord tones, bass first when it is not a chord tone."},"pitchClasses":{"type":"array","items":{"type":"integer"},"description":"Sorted pitch classes, C = 0."},"diatonic":{"type":"boolean"},"outOfKey":{"type":"array","items":{"type":"string"}},"degree":{"type":"integer","description":"Scale degree of the chord root when it is in the scale."},"scale":{"type":"array","items":{"type":"string"}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"operation":"spell","chord":"Ebmaj7","expectNotes":["Eb","G","Bb","D"]},"openapiOperation":{"operationId":"chord_check","summary":"Chord check: identify, spell, key membership, transpose","description":"Names a chord from its notes, spells a chord symbol into notes, tests whether a chord is diatonic to a key, or transposes a chord symbol, using pitch-class arithmetic over a fixed table of 21 chord qualities, for agents handling lead sheets and music metadata. Rule-based and labelled: when several readings are equally valid (C E G A is C6 or Am7/C) or no quality in the table matches, it returns unknown with the candidates instead of choosing. Does NOT use harmonic context, analyse progressions, infer keys, or know quality names outside its table.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"business","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/chord-check","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["identify","spell","key-membership","transpose"]},"notes":{"type":"array","items":{"type":"string","maxLength":6,"description":"Note name such as C, Eb, F#, Bbb, C##, optionally with octave (C4). Bass is the lowest note when every note has an octave, else the first."},"maxItems":8,"minItems":2,"description":"For identify: 2 to 8 notes."},"chord":{"type":"string","maxLength":24,"description":"Chord symbol, root A-G with optional #/b, quality suffix, optional /bass: Cmaj7, F#m7b5, Bb/D."},"key":{"type":"object","additionalProperties":false,"required":["tonic"],"description":"For key-membership.","properties":{"tonic":{"type":"string","maxLength":3,"description":"Key tonic, e.g. A or Eb."},"mode":{"type":"string","enum":["major","minor","harmonic-minor"],"description":"Default major. minor is natural minor."}}},"semitones":{"type":"integer","description":"For transpose: semitones up (negative down).","minimum":-48,"maximum":48},"prefer":{"type":"string","enum":["sharps","flats"],"description":"Accidentals for a natural root when transposing. Default sharps; a root written with # or b keeps its kind."},"expectChord":{"type":"string","maxLength":24,"description":"Optional claimed chord symbol to verify (identify, transpose)."},"expectNotes":{"type":"array","items":{"type":"string","maxLength":4,"description":"A claimed note name."},"maxItems":8,"description":"Optional claimed notes in order, to verify (spell)."}}},"example":{"operation":"spell","chord":"Ebmaj7","expectNotes":["Eb","G","Bb","D"]}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"operation":{"type":"string"},"chord":{"type":"string","maxLength":200,"description":"Normalised chord symbol."},"readings":{"type":"array","items":{"type":"object","properties":{"root":{"type":"string"},"quality":{"type":"string"},"symbol":{"type":"string"},"bass":{"type":"string"},"rootPosition":{"type":"boolean"},"rootPc":{"type":"integer"},"bassPc":{"type":"integer"}}}},"notes":{"type":"array","items":{"type":"string"},"description":"Spelled chord tones, bass first when it is not a chord tone."},"pitchClasses":{"type":"array","items":{"type":"integer"},"description":"Sorted pitch classes, C = 0."},"diatonic":{"type":"boolean"},"outOfKey":{"type":"array","items":{"type":"string"}},"degree":{"type":"integer","description":"Scale degree of the chord root when it is in the scale."},"scale":{"type":"array","items":{"type":"string"}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/chord-check/","docsJson":"https://agents.writerslogic.com/docs/chord-check.json","sample":"https://agents.writerslogic.com/api/v1/samples/chord-check","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}