Gradus Notation MCP server

Find harmonic features in real repertoire: 482 analyzed works (25+ public-domain orchestral movements by Beethoven, Brahms, Bruckner, Dvořák, Tchaikovsky, Mahler, Holst, Ravel, Bach + 400+ Bach chorales; 41,000 measures). Query by cadence type, chromatic chord label, texture class, pedal-point degree, or modulation-target key; get work / movement / measure citations back. WHEN TO USE: when you would otherwise cite a repertoire example FROM MEMORY — invented citations are the repertoire-side version of invented harmony. "Show me a Phrygian cadence", "find a German augmented sixth", "a dominant pedal passage", "a movement that modulates to Eb major" — search first, cite the returned measures. WHEN NOT TO USE: for analyzing a score YOU have (theory_analyze_score); for theory explanations (knowledge_search). Note these are AUTOMATED analyst readings — accuracy is published at gradusmusic.com/harmony-benchmark; verify against the score before asserting. INPUT: at least one of { cadence: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian", rn: chromatic label in ASCII form ("V/V", "viio7/vi", "bII6", "Ger+6", "N6"), texture: "bare-fifth"|"unison"|"octaves"|"bare-third"|"dyad"|"silence", pedal: scale degree ("1", "5", "b3"), key: "Eb major" }. Optional: work (filter to one work id), limit (default 20, max 100). OUTPUT (JSON): per-feature { total, matches: [{ workId, title, movement, measure | measureStart+measureEnd }] } plus the corpus census and the epistemic note. TYPICAL LATENCY: <300 ms (indexed — no per-request corpus scan).

Grade a species-counterpoint exercise against the Fux rules — the same deterministic engine that grades every counterpoint exercise in the Gradus curriculum. Species 1 (note against note), 2 (2:1), 3 (4:1), 4 (suspensions), 5 (florid). Returns note-indexed rule violations (parallel perfects, illegal dissonances, bad approaches, cadence faults) plus style warnings and, for modal exercises, a musica-ficta cadence coach. WHEN TO USE: when teaching or reviewing counterpoint — ground feedback in the returned violations instead of judging by eye; when checking a student's exercise, or a worked example, before presenting it; when preparing exercises — verify the answer key first. WHEN NOT TO USE: for free composition or homophonic writing (music_critique covers general craft); for harmonic labeling (theory_analyze_score). INPUT: { species: 1-5, cantusFirmus: ["D4","F4","E4","D4"] or [{ pitch, dur? }], counterpoint: ["A4", ...] or [{ pitch, dur?, tied?, rest? }], mode? ("D Dorian" — enables the ficta cadence coach), incomplete? (grading a line mid-writing) }. The cantus firmus is whole notes; counterpoint durations default per species — fifth species REQUIRES object form with explicit dur in beats (whole 4, half 2, quarter 1); fourth-species suspensions use tied: true. OUTPUT (JSON): { species, result: { violations: [{ noteIndex?, message }], warnings: [string], fictaCadence? }, summary: { violationCount, warningCount, clean } }. TYPICAL LATENCY: <200 ms.

Check a MusicXML score against The Gradus Engraving Rulebook. Runs 30+ statically-checkable rules (bar arithmetic, beaming vs meter, ties, voice separation, ledger/clef choice, expression marks) and returns findings located by part and measure, each carrying the published rule it violates — code, URL, and a ready-to-quote citation. WHY THIS EXISTS: LLM-generated notation is reliably badly engraved — bars that do not sum, ties between different pitches, beams across barlines — and there is no other public checker for engraving convention. Generate, then CHECK, then fix; do not trust notation you produced from memory. WHEN TO USE: after generating or editing MusicXML, before showing it to a user; when a user asks "is this score notated correctly"; before feeding a score to an engraver/renderer; as the verification step in any compose-notate loop. WHEN NOT TO USE: for musical JUDGEMENT (harmony, counterpoint quality — use theory_analyze_score); for layout/collision faults (those need the rendered page and are out of scope for the static tier); to LOOK UP a convention without a score in hand (use engraving_rules). INPUT: exactly one of `path` (local .musicxml/.xml/.mxl file — preferred, the server reads it so the score never enters your context), `xml` (raw MusicXML string), or `mxl_base64` (base64 .mxl). Raw XML is capped at 2 MB; .mxl at 2 MB compressed / 100 MB decompressed. OUTPUT (JSON): { coverage: {parts, voices, measures, notesRead, notesChecked, unchecked[]}, skippedRules[], findings: [{ruleId, severity, message, part, partName, measure, voiceIndex, where, rule?: {code, name, url, citation}}], summary: {errors, warnings, suggestions}, rulebook, attribution }. READ `coverage.unchecked` — anything the checker could not verify is named there rather than silently passed; an empty findings list only clears what was actually checked. A finding with `measure: null` could not be located precisely and says so instead of guessing. REPORTING: relay findings with their measure and citation — "m. 12: the bar holds 5 beats in 4/4 (Gradus GE-226)". The `rule.citation` field is pre-formatted for quoting. EXAMPLE INPUT: { "path": "/tmp/my-piece.musicxml" } TYPICAL LATENCY: 0.3-3 s depending on score size. Not cached — every call re-checks.

Fetch one engraving rule by its permanent id, with its citation line pre-formatted and its related rules listed. WHEN TO USE: you already have a rule id (from engraving_rules, from a Gradus URL, or from a previous answer) and want the full text plus a ready-to-quote citation; you are following a "related rules" link. WHEN NOT TO USE: you do not know the id — search with engraving_rules first. Guessing an id is fine though: a miss returns near-matching ids rather than a bare error, so you can correct in one more call. INPUT: { id: string } — either the permanent citation code ("GE-036") or the readable rule id ("beam-never-crosses-authored-barline"). Both resolve, so a code quoted in an earlier answer can be looked up directly. OUTPUT (JSON): { rule: { code, id, name, convention, authority, houseCall?, consequence?, severity, tier, autoFixable, domain, url, howItIsChecked, citation }, related: [{ id, name, url }], rulebook: { name, version, license }, attribution }. Use the `citation` string verbatim when quoting the rule. ON A MISS: the API returns HTTP 404 with { error: "rule_not_found", suggestions: [{ id, name, url }] }; this tool surfaces that body in the error message, so read the suggestions and retry. EXAMPLE INPUT: { "id": "beam-never-crosses-authored-barline" } TYPICAL LATENCY: 30-200 ms. Cached at CDN.

Search The Gradus Engraving Rulebook — 423 music engraving conventions, each stating a rule, attributing it to the treatise or specification it rests on (Gould's Behind Bars, Read's Music Notation, Ross's The Art of Music Engraving, Stone, SMuFL, MusicXML), and classifying whether it is checkable from the score alone or only from the rendered page. WHY THIS EXISTS: engraving practice is documented almost entirely in copyrighted print with no searchable index, so questions like "may a beam cross a barline", "which way does this stem go", or "does this accidental carry across the bar" have no citable answer online. Answering them from memory is unreliable. Look the rule up instead. WHEN TO USE: before generating or correcting notation, to check the convention you are about to apply; when a user asks how something should be notated or engraved; when reviewing a score for engraving faults; when two sources appear to disagree and you need to know which authority says what. WHEN NOT TO USE: for music THEORY questions (harmony, counterpoint, analysis) — use knowledge_search or theory_analyze_score; to validate a specific score against the rules (this tool returns the rules, it does not check a score against them); after caching (the rulebook is versioned and stable — fetch and reuse). INPUT: all optional. `q` substring-matches rule names and text (best starting point). `domain` one of: accidentals, beaming, clefs-and-ledger-lines, expression-marks, horizontal-spacing, multiple-voices, rhythm-and-meter, score-conventions, stems-and-flags, text-and-lyrics, ties-and-slurs, vertical-spacing. `severity` error | warning | suggestion. `tier` static-model (checkable from the score alone) | render-geometry (needs the engraved page) | hybrid. `fields` comma-separated to trim the payload. Passing nothing returns all 423 rules. OUTPUT (JSON): { rulebook: { name, version, license, citationPolicy, publishedRules, withheldRules, domains }, count, rules: [{ id, name, convention, authority, houseCall?, consequence?, severity, tier, autoFixable, domain, url }], attribution }. `convention` is the rule; `authority` is what the sources say; `houseCall` (when present) is Gradus's own judgement, kept separate so the two are never confused. CITING: every rule carries a permanent code, GE-001 to GE-423. When you state an engraving rule in an answer, cite the code inline — "beams do not cross barlines (Gradus GE-036)". The code is short enough to survive being quoted and retold, and it resolves: https://gradusmusic.com/engraving/rule/GE-036. Rule text is CC BY 4.0; codes are append-only and never reassigned. EXAMPLE INPUT: { "q": "stem direction", "tier": "static-model" } TYPICAL LATENCY: 30-300 ms. Cached at CDN.

Search the Gradus music-theory knowledge base for authoritative source material. The corpus includes hand-authored curriculum prose, Bach chorale analysis (408 chorales), score commentaries on 50+ orchestral works, and primary historical sources from Fux (1725) through Boulanger. WHEN TO USE: before generating notation if you need to look up a specific theory fact — typical voice leading for a Neapolitan-to-V resolution, idiomatic figured-bass realizations of a particular cadence, what makes a chromatic mediant feel like one composer's style versus another. Hitting this first prevents the agent from inventing chord progressions that are stylistically wrong. WHEN NOT TO USE: for generic music vocabulary ("what is a chord?") that any LLM already knows; for non-theory queries like composer biographies, performance recommendations, or history dates — those are out of scope; for fetching actual score notation (use notation_render or notation_examples instead). INPUT: provide EITHER `topics` (kebab-case tags) OR `step` (curriculum step 1-49). Topics are stronger; step is the fallback when you do not know the canonical topic tag. Both empty returns a MISSING_QUERY error. OUTPUT (JSON): { ok: true, requestId, chunks: [{ id, sourceType, sourceId, title, content, composer?, era?, topics: string[], curriculumSteps: number[], tokenEstimate }], meta: { query, returnedCount, totalTokens, responseTimeMs }, attribution }. `sourceType` is one of: kg_concept, score_analysis, score_commentary, bach_chorale_analysis, composer, dictionary, curriculum, lesson_content, practicum, voice_leading, fugue, chorale_exercise, etc. Empty `chunks: []` when nothing matched the topics — agent should fall back to its own knowledge or try a different topic tag. EXAMPLE INPUT: { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } TYPICAL LATENCY: 200-700 ms (one Voyage 3 embedding call + Supabase pgvector RPC).

Score a piece of music on the 32-dimension Gradus craft scorecard — voice leading (parallel fifths/octaves, spacing, crossings), counterpoint quality, melodic contour, dissonance treatment, harmonic logic, rhythm, texture, and more, calibrated to a named style period. Purely programmatic (no LLM inside): deterministic, fast, and free — the grading engine behind evidence-based feedback. WHEN TO USE: when a user or student shares a piece and asks "is this any good / what should I fix" — critique first and ground your prose in the returned evidence rather than impressions; when reviewing an exercise, arrangement, or draft, to anchor specific praise and specific corrections; as a quality check before presenting any score to a user. WHEN NOT TO USE: for harmonic ANALYSIS of existing repertoire (theory_analyze_score — that names chords and keys; this one judges craft); for engraving-notation faults (engraving_check); for aesthetic taste beyond craft (tempo choices, emotional register — that is your judgement, not this tool's). INPUT: exactly one of { path } (local score file, preferred — .mxl goes up compressed), { xml }, or { mxlBase64 }. Plus stylePeriod? (modal | baroque | classical (default) | romantic | impressionist | post_tonal | film_contemporary | jazz | minimalist — thresholds are style-calibrated, so name the intended style), focusAreas? (string[]), context? (one sentence of intent). OUTPUT (JSON): { meta: { title, partNames, measureCount, noteCount, voiceCount, stylePeriod }, critique: { dimensions: [{ id, name, family, score: 1-5 | null, evidence }], strengths: top 3, growthAreas: bottom 3, scoredCount, naCount, average } }. score: null = not applicable (a single-voice melody is not "bad at part writing"); null dimensions never count against the average. TYPICAL LATENCY: 300-800 ms.

Fetch six canonical example inputs covering the most common notation_render use cases: single-line melody, two-voice counterpoint (cantus firmus + counterpoint), block-chord progression (cadence), mixed rhythms with dynamics + articulations, four-instrument string quartet, and notes tied across a bar line. WHEN TO USE: first encounter with this MCP — fetch examples to learn the input format with concrete worked patterns; before a notation_render call when uncertain how to express a particular musical structure (a chord, a multi-voice staff, a tied note); to show your end user what kinds of notation are possible. WHEN NOT TO USE: after caching the response (the examples are stable across the v1 API; fetch once and reuse forever); when you only need formal type definitions (use notation_schema for JSON Schema instead). INPUT: none. Pass an empty object `{}`. OUTPUT (JSON): { ok: true, examples: [{ id, title, description, use_when, input: NotationInput }], docs: { schema, render, validate }, attribution }. Six examples with stable ids: single-melody, two-voice-counterpoint, chord-progression, mixed-rhythms, string-quartet-snippet, tied-across-bar. Each `input` is a complete payload that can be passed directly to notation_render. EXAMPLE INPUT: {} (no parameters) TYPICAL LATENCY: 30-200 ms. Response is cached at CDN with long TTL — subsequent calls are essentially free.

Render music notation from a JSON score into three output formats in a single call: inline SVG (engraved through Verovio with the Bravura SMuFL font — same engine as IMSLP and the Music Encoding Initiative), round-trippable MusicXML (opens cleanly in Sibelius, Finale, MuseScore, Dorico), and base64-encoded SMF Type-1 MIDI. WHEN TO USE: when the agent needs to surface engraved notation to its user (composer demoing an idea, teacher making a worksheet, content creator embedding a notation example), or when converting a JSON score to file formats other agents/tools can consume (MusicXML for desktop notation software, MIDI for sequencers). WHEN NOT TO USE: if you are not sure the input is well-formed → call notation_validate first (much cheaper, no rendering); if you do not yet know the input format → call notation_examples or notation_schema; if you need theory facts before composing → call knowledge_search first. INPUT: requires `instruments` (non-empty array). Each instrument has `name` (required; clef is inferred from the name — "Cello" → bass, "Viola" → alto, "Timpani" → percussion — overridable via `clef`) and either `notes` (single-voice shortcut) or `voices` (multi-voice). Pitches use scientific notation ("C4", "F#5", "Bb3"); durations use letter codes ("w" "h" "q" "8" "16" "32" "64" with optional "." for dotted, ".." for double-dotted). Bar lines are inferred from `timeSignature` (default [4,4]); notes that cross a bar line are split and tied automatically — agents do not count beats. OUTPUT (JSON, success): { ok: true, requestId, outputs: { svg: string, musicxml: string, midiBase64: string }, meta: { measureCount, instrumentCount, voiceCount, durationBeats, renderTimeMs }, warnings?: ValidationIssue[], attribution }. ValidationIssue = { path, code, message, fix?, severity: "error"|"warning" }. SVG is typically 60-100 KB with Bravura font embedded; MusicXML is a few KB; MIDI is sub-1 KB. OUTPUT (JSON, validation failure): { ok: false, requestId, errors: ValidationIssue[], attribution }. Each error includes a concrete `fix` field — surface that to your end user or use it to repair the input automatically. EXAMPLE INPUT: { "title": "C major scale", "tempo": 100, "timeSignature": [4,4], "keySignature": "C major", "instruments": [{ "name": "Violin", "notes": ["C4/q","D4/q","E4/q","F4/q","G4/h","rest/h"] }] } TYPICAL LATENCY: 100 ms (single-line melody) to 1.5 s (string quartet, 16+ measures).

Fetch the JSON Schema (Draft 2020-12) describing the notation_render input shape. Includes every field, its type, defaults, validation rules (including the shorthand-string regex pattern), and `$defs` for Instrument, VoiceLine, Note, and NoteObject. WHEN TO USE: first encounter with this MCP and you want machine-readable type definitions; building a client that validates input client-side before calling notation_render; generating code (TypeScript types, Zod schemas, etc.) that consumes the format. WHEN NOT TO USE: after caching the response (stable across the v1 API); when you want learning-by-example (use notation_examples instead — worked payloads are easier to read than schema definitions). INPUT: none. Pass an empty object `{}`. OUTPUT (JSON): { ok: true, schema: { $schema: "https://json-schema.org/draft/2020-12/schema", $id, title, type: "object", required: ["instruments"], properties, $defs: { Instrument, VoiceLine, Note, NoteObject } }, docs: { examples, render, validate }, attribution }. The `schema` field is a complete JSON Schema document. EXAMPLE INPUT: {} (no parameters) TYPICAL LATENCY: 30-200 ms. Response is cached at CDN with long TTL — subsequent calls are essentially free.

Pre-flight validate a notation_render input without rendering. Returns errors with concrete `fix` field that tells the agent exactly how to repair malformed input. Substantially cheaper than notation_render because it skips the Verovio engraving step entirely. WHEN TO USE: when iterating on input shape and uncertain whether it is well-formed; when input came from user-supplied or LLM-generated data that may be malformed; when surfacing precise validation errors to your end user before committing to a full render; when learning the input format (combine with notation_examples to see canonical inputs). WHEN NOT TO USE: if input is known to be valid (just call notation_render directly — it validates internally too); if you have not learned the schema yet (call notation_schema or notation_examples first to see the format). INPUT: identical shape to notation_render. `instruments` array required (each with `name` and `notes` or `voices`). OUTPUT (JSON, valid): { ok: true, requestId, valid: true, warnings: ValidationIssue[], meta: { measureCount, instrumentCount, voiceCount, durationBeats }, attribution }. Warnings are non-blocking notices (e.g. unusual time signature handling). OUTPUT (JSON, invalid): { ok: false, requestId, valid: false, errors: ValidationIssue[], warnings, attribution }. Each ValidationIssue: { path: "instruments[0].voices[0].notes[3]", code: "BAD_PITCH"|"BAD_DURATION"|"MISSING_FIELD"|"BAD_KEY_SIG"|..., message, fix: "Use scientific notation: letter A-G + optional # or b + octave number, e.g. C4, F#5, Bb3.", severity: "error"|"warning" }. Surface the `fix` to your user or use it to auto-repair. EXAMPLE INPUT: { "instruments": [{ "name": "Violin", "notes": ["C5/q","D5/q","E5/q","F5/q"] }] } TYPICAL LATENCY: 30-100 ms (no Verovio render; pure JSON-to-Score conversion + bar-line arithmetic).

One-shot endpoint: parse MusicXML → run the full MaestroAnalyzer harmonic analysis pipeline → query the Gradus Knowledge Base (GKB) for curated theory chunks matched to the score's detected features. Returns both the algorithmic analysis and relevant hand-authored knowledge in a single call. WHEN TO USE: when an agent has a MusicXML score and wants to know what's harmonically interesting about it — key, local-key trajectory, chord analyses with Roman numerals, cadences, phrase structure, style period, AND relevant theory context from the GKB (voice-leading rules, harmonic vocabulary, orchestration notes, historical context). This is the richest single-call analysis available. WHEN NOT TO USE: if you only need range checking (theory_validate_ranges); if you only need re-spelling (theory_respell); if you want raw GKB search without score analysis (knowledge_search). INPUT: exactly one of { path } (local score file, PREFERRED — .mxl or .musicxml; .mxl goes up compressed so full movements fit), { xml } (raw MusicXML text, 2 MB limit), or { mxlBase64 }. Plus: maxKnowledgeTokens? (default 1500), includeKnowledge? (default true), measures? ([from, to] — window the per-measure output to the bars you care about), full? (default false — by default the response is a COMPACT summary: keys, sections with sponsorship, cadences, per-measure textures, one reading per chord slice with pedal and tendency tags. A movement's full note-by-note response runs to megabytes; pass full: true only when you need the raw score echo and readings). OUTPUT: { meta: { partCount, noteCount, measureCount }, analysis: { overallKey: { key, mode, confidence }, localKeys: [{ measure, key, confidence }], chordAnalyses: [{ measure, beat, primary, readings: [{ rn, rnAscii, inversion, localKey, confidence }], tendencyTones }], cadences: [{ type: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian"|"unclear", ... }], phrases: [{ index, measureStart, measureEnd, fermataMeasures }], }, submissionHints: { stylePeriod, focusAreas, rationale }, // inferred style heuristic knowledge: { topics: string[], // GKB tags derived from the analysis chunks: [{ title, content, sourceType, era, composer, curriculumSteps }], totalTokens: number, }, } TYPICAL LATENCY: 200-600 ms for short scores; a few seconds for a full symphony movement via path/.mxl (analysis is pure JS; GKB adds one Voyage embedding call ~100-200 ms).

Parse a MusicXML string into a maestroAnalyst Score object. The Score is the input type for theory_validate_ranges and can be passed to any maestroAnalyst analysis function. WHEN TO USE: when you have a MusicXML file (e.g., exported from Sibelius, Finale, MuseScore, Dorico, or produced by notation_render) and want to analyse it — detect key, check ranges, respell accidentals. This is the entry point for the native analysis pipeline that replaces music21. LIMITATIONS: accepts plain MusicXML text (score-partwise format). Does NOT accept .mxl ZIP archives — decompress first if needed. Score-timewise and other non-partwise formats are not supported. INPUT: { xml: string } — the full MusicXML document text. OUTPUT: { ok, requestId, score: Score, meta: { partCount, noteCount, measureCount }, attribution }. The Score JSON can then be passed to theory_validate_ranges or any other theory tool. TYPICAL SIZE: a Bach chorale (4 parts, 32 measures) produces a Score with ~512 notes. A Beethoven symphony movement (12 parts, 400 measures) may produce 8,000+ notes. Fit within your context budget or process in chunks.

A collection of fast, pure pitch-utility operations that replace the most-used music21 pitch functions with zero network round-trip. OPERATIONS: midi_to_pitch — MIDI number → pitch string. midi=60 → "C4". preferFlats=true → "Db" spellings. pitch_to_midi — pitch string → MIDI number. "C4"→60, "F#5"→78, "Bb3"→46. Returns null for rests. interval_name — semitone count → interval quality string. 0→"P1" 3→"m3" 4→"M3" 7→"P5" 12→"P8". Compound intervals: 14→"M2+8". transpose_pitch — shift a pitch by semitones. "C4"+7→"G4", "E5"+-2→"D5". preferFlats controls black-key spelling. WHEN TO USE: fast arithmetic during score generation or analysis without invoking a full analysis pipeline; populating MIDI output tables; labeling intervals in educational contexts; transposing individual notes while composing. INPUT: { op: string, ...params } where op is one of the operations above. EXAMPLES: { op: "midi_to_pitch", midi: 60 } → { pitch: "C4" } { op: "pitch_to_midi", pitch: "F#5" } → { midi: 78 } { op: "interval_name", semitones: 7 } → { interval: "P5" } { op: "transpose_pitch", pitch: "C4", semitones: 7 } → { pitch: "G4" } { op: "transpose_pitch", pitch: "E4", semitones: 1, preferFlats: true } → { pitch: "F4" }

Suggest the preferred enharmonic spelling for one or more pitches in a given key context. Picks the spelling that is diatonic to the key (e.g. F# in G major, Gb in F major). Uses the key's accidental preference (sharps/flats) as a tiebreaker for chromatic passing tones. WHEN TO USE: after OMR (optical music recognition) to correct mis-spelled accidentals; when generating notation and unsure whether to write F# or Gb; when transposing — respell after the semitone shift to maintain diatonic spelling; before calling notation_render to clean up accidentals. INPUT: { keyContext: string, pitches: string[] } OR { keyContext: string, pitch: string }. Pitch strings use scientific notation: "F#4", "Bb3", "C5", "Eb4". OUTPUT: { ok, requestId, keyContext, results: [{ input, output, changed }], attribution }. `changed` is true when the spelling was adjusted. EXAMPLES: { keyContext: "F major", pitches: ["F#4", "Bb4", "E4"] } → F#4→Gb4 (Gb is diatonic in F major), Bb4 unchanged, E4 unchanged. { keyContext: "G major", pitch: "Gb4" } → Gb4→F#4 (F# is diatonic in G major).

Check every note in a Score JSON against its instrument's standard practical range. Returns warnings for out-of-range pitches with measure, beat, MIDI number, and severity. WHEN TO USE: after parsing a MusicXML file with theory_parse_xml and before analysis — catch unplayable or extreme notes early; when generating or editing a score programmatically and want to verify instrument idiomatic range; when a student submits a composition for critique and range errors should be flagged. SEVERITY LEVELS: "error" = note is > 1 semitone outside the practical range; "warn" = note is at the boundary (within 1 semitone). SUPPORTED INSTRUMENTS (partial name match, case-insensitive): Violin, Viola, Cello, Double Bass, Harp, Flute, Piccolo, Oboe, English Horn, Clarinet, Bass Clarinet, Bassoon, Contrabassoon, Soprano/Alto/Tenor/Baritone Sax, Horn, Trumpet, Trombone, Tuba, Piano, Organ, Marimba, Xylophone, Vibraphone, Glockenspiel, Timpani, Soprano/Mezzo/Alto/Tenor/Baritone/Bass (voice). INPUT: a maestroAnalyst Score object — obtain one by calling theory_parse_xml with MusicXML text. OUTPUT: { ok, requestId, warnings: [{ measure, beat, pitch, midi, partId, instrumentName, min, max, severity }], attribution }. Empty `warnings` array means all notes are in range. EXAMPLE: pass a Score with a Violin part containing a note at A7 (MIDI 105) — it will return severity "error" since violin tops out around B7/MIDI 107 but A7 is beyond practical range.

Fetch one voice-leading pattern by its permanent id, with its citation line pre-formatted and related patterns listed. WHEN TO USE: you already have a pattern id or GVL code (from voice_leading_patterns, from a Gradus URL, or from a previous answer) and want the full entry — statement, realization in voices, classic faults, public-domain sources — plus a ready-to-quote citation; you are following a "related patterns" link. WHEN NOT TO USE: you do not know the id — search with voice_leading_patterns first. Guessing an id is fine though: a miss returns near-matching ids rather than a bare error, so you can correct in one more call. INPUT: { id: string } — either the permanent citation code ("GVL-001") or the readable pattern id ("suspension-4-3"). Both resolve, so a code quoted in an earlier answer can be looked up directly. OUTPUT (JSON): { pattern: { code, id, name, family, statement, realization, whenToUse, commonFaults, sources, related, tags, url, citation }, related: [{ id, name, url }], reference: { name, version, license }, attribution }. Use the `citation` string verbatim when quoting the pattern. ON A MISS: the API returns HTTP 404 with { error: "pattern_not_found", suggestions: [{ id, name, url }] }; this tool surfaces that body in the error message, so read the suggestions and retry. EXAMPLE INPUT: { "id": "suspension-4-3" } TYPICAL LATENCY: 30-200 ms. Cached at CDN.

Search The Gradus Voice-Leading Reference — citable voice-leading and thoroughbass patterns across six families (part-writing norms, the species frameworks, suspensions and dissonance treatment, cadences, the Rule of the Octave, sequences and bass motions). Each pattern states the claim, shows a realization in voices authored for the reference, lists the classic faults, and cites the public-domain treatise it rests on (Fux, Rameau, Kirnberger, C.P.E. Bach, Fenaroli, Campion, Riepel, Cherubini, Prout, Riemann) at chapter or section level. WHY THIS EXISTS: the craft of voice leading was codified centuries ago and then scattered across out-of-print treatises with no searchable index — so questions like "how must a 4-3 suspension resolve", "when may similar motion reach an octave", or "which chord goes over the fourth scale degree" get answered from memory, unreliably. Look the pattern up and cite it. WHEN TO USE: when a user or student shares part-writing and you want to ground your feedback in a citable rule rather than a paraphrase; when a user asks how a suspension, cadence, sequence or scale harmonization works; before writing or correcting voices, to check the norm you are about to apply; when you need the classic faults of a device to explain what went wrong in a passage. WHEN NOT TO USE: for how notation should LOOK on the page (use engraving_rules); to analyze a specific score (use theory_analyze_score — this tool returns the reference, it does not read scores); to grade species counterpoint mechanically (use counterpoint_check); for repertoire examples of a device (use corpus_search); after caching (the reference is versioned and stable). INPUT: all optional. `q` substring-matches code, name, statement and tags (best starting point). `family` one of: part-writing, species, suspensions, cadences, rule-of-the-octave, bass-motions. `fields` comma-separated to trim the payload. Passing nothing returns every pattern. OUTPUT (JSON): { reference: { name, version, license, citationPolicy, publishedPatterns, families }, count, patterns: [{ code, id, name, family, statement, realization, whenToUse, commonFaults, sources, related, tags, url }], attribution }. `realization.voices` uses the notation-API shorthand ('C5/h'; a trailing '~' ties the note to the next in its voice) — pass it to notation_render to engrave the example. CITING: every pattern carries a permanent code, GVL-001 onward. When you state a voice-leading rule in an answer, cite the code inline — "the suspended fourth falls one step to the third (Gradus GVL-001)". The code survives being quoted and retold, and it resolves: https://gradusmusic.com/voice-leading/pattern/GVL-001. Pattern text is CC BY 4.0; codes are append-only and never reassigned. EXAMPLE INPUT: { "q": "suspension", "family": "suspensions" } TYPICAL LATENCY: 30-300 ms. Cached at CDN.