Gradus Notation API용 Model Context Protocol 서버입니다. AI 에이전트에 음악 도구를 제공합니다: 악보 렌더링, 입력 검증, 악보 분석, 인용 가능한 규칙집에 따른 조판(engraving) 검사, 그리고 선별된 음악이론 지식베이스 검색 — Gradus가 후원합니다.
교육 전용이 아니라 범용입니다. 음악을 다루는 모든 에이전트나 애플리케이션이 대상입니다 — 작곡 보조, 음악학 및 코퍼스 연구, 렌더링된 예시를 원하는 이론 Q&A, MIDI 파이프라인, 조판 품질 검사, 게임, 문서화 등. 음악 교육은 이 도구가 탄생한 배경일 뿐, 이를 바탕으로 무엇을 만들지 제한하지 않습니다.
설치 한 번, 세 가지 명명된 도구:
Gradus Notation — JSON 악보를 인라인 SVG, MusicXML, MIDI로 렌더링하며 사전 검증 기능 포함 (notation_render, notation_validate).
Gradus Harmonic Analyzer — 전체 악보 분석: 로마숫자, 조성 및 전조, 종지, 페달 포인트, 질감 (theory_analyze_score 및 theory_* 도구). 독립형 TypeScript 라이브러리로도 제공: npm의 gradus-analyst.
Gradus Engraver — 악보를 Gradus Engraving Rulebook의 인용 가능한 GE 코드 규칙에 따라 검사합니다 (engraving_check).
Gradus란 무엇인가? Gradus는 홈스쿨 가정을 위한 음악 작곡 커리큘럼입니다. AI 에이전트용 무료 음악 도구를 만들고 무료로 제공합니다. 이 MCP 서버는 그 도구 중 하나입니다 (gradusmusic.com) — "Gradus"는 커리큘럼을 가리키며, 이 패키지를 가리키는 것이 아닙니다.
대부분의 음악 기보 도구는 GUI가 필요합니다. 이 도구는 그렇지 않습니다. 에이전트는 JSON 악보를 제출하고 단 한 번의 호출로 인라인 SVG, MusicXML, MIDI를 받을 수 있습니다. 무료로 사용 가능하며, 인증도 API 키도 필요 없습니다 — 무료 티어의 에이전트는 최종 사용자에게 응답할 때 Gradus를 출처로 표기하면 됩니다.
렌더링 외에도 동일한 서버가 분석 기능을 제공합니다: 전체 악보의 로마숫자 및 조성 분석, 음높이 유틸리티, 음역 검증, 이명동음 재표기, 그리고 인용 가능한 규칙 코드가 있는 444개 규칙 조판 검사기. 에이전트가 필요로 하는 전체 음악 표면을 설치 한 번으로 충당합니다.
Related MCP server: Music21 Composer MCP
Claude Code에서:
claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcpClaude Desktop에서는 MCP 설정에 추가하세요:
{
"mcpServers": {
"gradus-notation": {
"command": "npx",
"args": ["-y", "@gradusmusic/notation-mcp"]
}
}
}도구 | 기능 |
| JSON 악보 → SVG + MusicXML + MIDI를 한 번의 호출로 |
| 입력 형태 사전 검증 (렌더링보다 저렴) |
| 기보 생성 전 음악이론 청크 조회 |
| 표준 입력 예시 (캐시 및 재사용) |
| 입력 형태용 JSON Schema (캐시 및 재사용) |
네이티브 TypeScript MaestroAnalyzer 엔진 기반의 네 가지 새 도구 — music21 의존성 없음, Python 없음, 추가 서버 없음.
도구 | 기능 |
| MusicXML 파싱 → 전체 화성 분석 + GKB 지식 청크를 한 번의 호출로 |
| MusicXML 문자열 파싱 → maestroAnalyst |
| Score의 모든 음표를 해당 악기의 실용 음역과 대조 검사 |
| 조성 맥락에서 음높이의 선호 이명동음 표기 제안 |
| 순수 함수 음높이 연산: |
일반적인 워크플로:
# Full analysis + GKB knowledge in one call
theory_analyze_score({ xml: "..." })
→ { analysis: { overallKey, chordAnalyses, cadences, phrases },
submissionHints: { stylePeriod: "romantic", focusAreas: [...] },
knowledge: { topics: ["augmented-sixth-chords", "modulation"], chunks: [...] } }
# Step-by-step
theory_parse_xml({ xml: "..." }) → Score JSON
theory_validate_ranges(score) → [{ measure, beat, pitch, severity }, ...]
theory_respell({ keyContext: "F major", pitches: ["F#4", "Bb3"] })
→ [{ input: "F#4", output: "Gb4", changed: true }]
theory_pitch_utils({ op: "interval_name", semitones: 7 }) → { interval: "P5" }도구 | 기능 |
| 텍스트, 영역, 심각도 또는 검사 방식으로 423개의 출처 있는 음악 조판 규칙 검색 |
| 영구 ID로 규칙 하나 조회 — 인용 준비된 출처 및 관련 규칙 포함 |
| MusicXML 악보를 규칙집에 따라 검사 — 위반한 규칙을 각각 인용하는 파트별·마디별 결과 |
조판 관행은 거의 전적으로 저작권이 있는 인쇄물에만 문서화되어 있습니다 — Gould의 Behind Bars, Read의 Music Notation, Ross의 The Art of Music Engraving — 검색 가능한 색인이 전혀 없습니다. 그래서 "빔이 마디선을 가로지를 수 있는가"에 대한 인용 가능한 답이 온라인에 없고, 그 질문을 받은 모델은 기억에 의존해 자신 있게 답합니다. 이 도구들은 규칙을 출처와 함께 반환하므로 답을 검증할 수 있습니다.
각 규칙은 보통 뒤섞여 있는 세 가지를 분리합니다: convention(규칙), authority(논문들이 말하는 바, 장(chapter) 수준에서 인용), houseCall(출처들이 의견이 갈릴 때 Gradus가 채택한 입장). 규칙 ID는
영구적이며 규칙 텍스트는 CC BY 4.0입니다 — citation 필드를 인용하세요.
# Look up before you generate
engraving_rules({ q: "stem direction", tier: "static-model" })
→ { rulebook: { version, license, domains }, count, rules: [{ id, name, convention, authority, ... }] }
# Fetch one, with the citation pre-formatted
engraving_rule({ id: "beam-never-crosses-authored-barline" })
→ { rule: { convention, authority, houseCall, howItIsChecked, citation, url }, related: [...] }잘못된 ID는 비용이 저렴합니다: API가 유사한 ID와 함께 404로 응답하므로 한 번 더 호출로 수정할 수 있습니다.
engraving_check는 루프를 완성합니다: 기보 생성, 검사, 발견 사항 수정.
가능하면 로컬 파일 경로를 전달하세요 — 서버가 파일을 직접 읽으므로
악보가 base64로 모델의 컨텍스트를 거칠 필요가 없습니다:
engraving_check({ path: "/tmp/my-piece.musicxml" })
→ { coverage: { parts, measures, notesChecked, unchecked: [...] },
findings: [{ ruleId, severity, part, measure,
rule: { code: "GE-226", url, citation } }],
summary: { errors, warnings, suggestions } }빈 결과 목록을 신뢰하기 전에 coverage.unchecked를 읽으세요 — 검사기가
검증할 수 없었던 모든 항목이 조용히 통과되는 대신 그곳에 명시됩니다.
도구 | 기능 |
| 악보에 대한 32차원 제작 점수표 — 성부 진행, 대위법, 윤곽, 화성, 질감; 순수 프로그램적이며 근거 인용 |
| Fux 종(種) 채점기 (종 1–5): 음높이 목록 입력, 음표 인덱스 기준 규칙 위반 출력 |
| 482개 분석된 작품에서 화성적 특징 검색 — |
사용자가 곡을 공유할 때, 이 도구들은 피드백을 근거에 기반하게 합니다: 비평은 측정한 내용을 인용하고, 종 채점기는 정확한 음표를 지적하며, 코퍼스 검색은 "실제 예시를 보여줘"라는 질문에 인용으로 답합니다.
도구 | 기능 |
| 인용 가능한 GVL 코드 패턴 검색 — 보류음, 종지, 옥타브 규칙, 시퀀스, 성부 진행 규범 — 각각 저자가 작성한 실현과 퍼블릭 도메인 출처 포함 |
| ID 또는 GVL 코드로 패턴 하나 조회 — 인용 준비된 출처 및 관련 패턴 포함 |
Engraving Rulebook의 자매편: GE 코드가 음악이 페이지에서 어떻게 보여야 하는지를 다룬다면,
GVL 코드는 성부가 어떻게 움직여야 하는지를 다룹니다. 모든 패턴은 기반이 되는
퍼블릭 도메인 논문 — Fux, Rameau, Kirnberger, Fenaroli, Riepel, Prout — 을
현대 판본을 통하지 않고 장(chapter) 수준에서 인용하며, realization.voices 필드는
notation_render에 바로 전달하여 조판할 수 있는 기보 API 약식 표기입니다.
voice_leading_patterns({ q: "suspension", family: "suspensions" })
→ { reference: { version, license, families }, count,
patterns: [{ code: "GVL-001", id: "suspension-4-3", statement, realization, sources, ... }] }
voice_leading_pattern({ id: "GVL-001" })
→ { pattern: { statement, realization, commonFaults, sources, citation, url }, related: [...] }도구 | 기능 |
| 17개 단계에 걸친 166개의 원본 등급별 숫자 저음 연습문제 검색 — 단계별 필터링, 또는 제목·개념·GVL 코드 검색 |
| 영구 ID로 연습문제 하나 조회 — 모델 실현, 교육 노트, 훈련하는 패턴 포함 |
Voice-Leading Reference가 규칙을 명시하는 곳에서, 코퍼스는 연습입니다: 베이스, 숫자, 그리고 — 거의 모든 현존 컬렉션과 달리 — 성부 진행이 기계적으로 검증된 4성부 모델 실현. 단계는 자리바꿈 3화음부터 옥타브 규칙, 종지 공식, 보류음, 딸림7화음, 시퀀스, 단조, 페달 포인트, Riepel 도식, 전조와 반음계적 숫자, 무숫자 베이스와 축소법까지 이어집니다.
모든 연습문제는 원본입니다 — 어떤 판본에서도 전사되지 않았으며 —
전체 코퍼스는 CC BY 4.0입니다. 연습문제 ID와 단계 슬러그는 영구적이므로
인용이 계속 유효합니다. givenBass는 학생에게 보여줄 내용이고,
realization은 학생이 시도할 때까지 숨겨둘 답입니다. 둘 다
기보 API 약식 표기이므로 어느 쪽이든 바로 notation_render로 전달할 수 있습니다.
figured_bass_exercises({ stage: "suspensions", fields: "id,title,teaches" })
→ { corpus: { version, license, stages }, count: 12,
exercises: [{ id: "bass-225", title: "Suspension 4–3", teaches, ... }] }
figured_bass_exercise({ id: "bass-225" })
→ { exercise: { givenBass, realization, solutionNote, keyboard, citation, url },
drills: [{ code: "GVL-001", name: "The 4–3 suspension", url }],
neighbours: { prev, next } }음높이는 과학적 표기법을 사용합니다: C4, F#5, Bb3. 길이는 문자 코드를 사용합니다: w h q 8 16 32 64이며 점음표는 선택적 .로 표시합니다. 음표는 다음과 같을 수 있습니다:
약식: "C5/q" (4분음표 C5), "rest/q" (4분쉼표), "[C4,E4,G4]/q" (화음)
객체 형태: { pitch: "C5", duration: "q", dynamic: "f", articulations: ["accent"] }
마디선은 박자표에서 추론됩니다 — 음표를 시간 순서대로 작성하면 API가 마디선을 가로지르는 모든 것을 분할하고 이음줄로 연결합니다.
{
"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/q","A4/q","B4/q","C5/q","C5/w"]
}]
}환경 변수 | 기본값 | 용도 |
|
| 자체 호스팅 또는 로컬 개발 API용 재정의 |
|
|
|
무료 사용은 최종 사용자에게 기보를 표시할 때 Gradus를 출처로 표기하는 조건으로 제공됩니다. 권장 문구 (API도 모든 응답에서 이를 반환합니다):
Notation rendered by Gradus School of Music Composition (gradusmusic.com).
전체 문서 + 빠른 시작: https://gradusmusic.com/notation-api
OpenAPI 3.1 스펙: https://gradusmusic.com/api-spec.yaml
입력 형식용 JSON Schema: https://gradusmusic.com/api/v1/notation/schema
에이전트 중심 문서: https://gradusmusic.com/llms-api.txt
git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run build프로덕션 API에 대한 스모크 테스트:
node test-client.mjshttps://github.com/delmas41/gradusnotation/issues에서 이슈를 열어주세요. 기여 환영합니다 — 작고 집중된 PR을 선호합니다.
MIT — Sean Johnson, Gradus School of Music Composition. LICENSE 참조.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| topics | No | Topic tags in kebab-case. Matched semantically via Voyage 3 Large embeddings plus a topic-overlap boost; exact-match is not required, so close synonyms work. Examples: ["voice-leading","deceptive-cadence"], ["chromatic-mediants"], ["sonata-form","second-theme"], ["figured-bass","6-4-2-chord"], ["fugue","stretto"], ["modulation","pivot-chord"]. | |
| step | No | Curriculum step number (1-49). Fallback when you do not know the topic tag. Maps to the Gradus 10-stage curriculum: Stage I 1-7 (single voice, intervals, scales), II 8-13 (counterpoint, all 5 species), III 14-16 (harmony, third voice), IV 17-18 (form, modulation), V 19-20 (fugue), VI 21-25 (classical style, sonata), VII 26-30 (Romantic harmony, augmented sixths), VIII 31-33 (Impressionist), IX 34-36 (20th century), X 37-40 (advanced). | |
| limit | No | Maximum chunks to return. Default 8 is right for most queries; raise for broad surveys, lower for tight context budgets. | |
| maxTokens | No | Token budget for the combined chunk content. Default 1500 fits comfortably in most agent context windows. The endpoint greedy-selects highest-similarity chunks within this budget. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite lacking annotations, the description thoroughly discloses behavioral traits: output JSON structure, sourceType enums, error on empty inputs, empty chunk behavior, and typical latency (200-700 ms). It covers all necessary operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with labeled sections (WHEN TO USE, WHEN NOT TO USE, INPUT, OUTPUT, EXAMPLE INPUT, TYPICAL LATENCY). Every sentence adds value, and the purpose is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description fully explains the output format, including chunk objects with fields, sourceType list, empty chunks behavior, and attribution. It leaves no critical gaps for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant context beyond the schema. It explains topics as kebab-case tags with semantic matching via Voyage, step as a fallback, and provides usage guidance for limit and maxTokens defaults (8 and 1500) with rationale.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches the Gradus music-theory knowledge base for authoritative source material, listing specific corpus contents. It also distinguishes itself from sibling tools by directly referencing notation_render and notation_examples for score notation, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'WHEN TO USE' and 'WHEN NOT TO USE' sections, detailing scenarios such as looking up theory facts before generating notation, and excluding generic music vocabulary, non-theory queries, and score notation. It also suggests alternative tools for out-of-scope tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch canonical example inputs (single melody, two-voice counterpoint, chord progression, mixed rhythms with dynamics, string quartet snippet, tied notes across bar lines). Cache the result client-side; the response shape is stable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses that the response should be cached client-side and that the shape is stable, which is valuable behavioral context for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded content. The first sentence lists examples clearly, and the second adds caching and stability info. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters or output schema, the description is sufficiently complete. It tells what the tool fetches and describes response characteristics, covering all necessary information for a simple fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description adds meaning by enumerating example categories, going beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches canonical example inputs and lists specific examples like single melody and chord progression. It distinguishes from siblings such as knowledge_search, notation_render, notation_schema, and notation_validate by focusing on examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by listing examples, but the description lacks explicit guidance on when to use this tool versus other notation tools. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render music notation from a JSON score. Returns inline SVG, MusicXML, and MIDI in one call. Use scientific pitches ("C4", "F#5", "Bb3") and duration codes (w h q 8 16 32 64 with optional dots). Bar lines are inferred from the time signature; notes that cross bar lines are split and tied automatically. Call notation_validate first if you are unsure your input is well-formed — validate is cheaper than render.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title rendered above the score. | |
| composer | No | ||
| tempo | No | ||
| timeSignature | No | ||
| keySignature | No | e.g. "C major", "G minor", "F# major". | C major |
| instruments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It explains that bar lines are inferred from time signature and notes crossing bar lines are split and tied automatically. It also describes the pitch and duration format expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently conveys purpose, output, input formats, behavior, and usage advice. It is front-loaded with the main action and each sentence adds value, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the lack of an output schema, the description provides good coverage of input formats and behavior. However, it does not explain all parameters (e.g., title, composer, tempo) in detail, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, but the description adds significant meaning: it explains scientific pitch notation ('C4', 'F#5'), duration codes (w, h, q, etc.), and the structure of notes (shortcut strings vs. objects). However, parameters like title, composer, and tempo are not elaborated beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Render music notation from a JSON score.' It specifies the output formats (SVG, MusicXML, MIDI) and distinguishes itself from sibling tools like notation_validate by advising to validate first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells users when to use notation_validate instead ('if you are unsure your input is well-formed — validate is cheaper than render'). It also explains that bar lines are inferred and notes are automatically split, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the JSON Schema for the notation_render input shape. Cache the result client-side; this is stable across the v1 API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses stable API result and suggests client-side caching, adding value. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with main action. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a zero-parameter tool. Describes purpose and behavior. Could mention return format, but not essential given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. Description adds no parameter info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches the JSON Schema for notation_render input shape, specifying verb and resource. It distinguishes from siblings like notation_render (rendering) and notation_validate (validation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context (fetch schema for notation_render) and advises caching due to stability. Does not explicitly exclude alternatives but given sibling tools, purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pre-flight validate an input shape without rendering. Returns errors with concrete fix suggestions when input is malformed. Cheaper than notation_render — use this when iterating on input shape.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| composer | No | ||
| tempo | No | ||
| timeSignature | No | ||
| keySignature | No | ||
| instruments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of disclosing behavior. It mentions it returns errors with fix suggestions and is cheaper, but does not explicitly state that the tool is read-only, idempotent, or free of side effects—common expectations for a validation tool but not confirmed. More explicit behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states purpose and output; the second gives usage guidance. No repetition or filler. Essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description covers purpose and usage but omits detail on error types, fix suggestion format, input limitations, or edge cases. It provides a minimal but functional level of completeness, with room for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 6 parameters with 0% description coverage; the description adds no parameter-specific meaning. While parameter names (title, composer, tempo, etc.) are self-explanatory, the description fails to clarify constraints, relationships, or how parameters influence validation. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool validates an input shape without rendering, distinguishing it from the sibling notation_render. It uses specific verbs ('validate') and identifies the resource ('input shape'), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: 'Cheaper than notation_render — use this when iterating on input shape.' It tells the agent when to use (during iteration) and implies an alternative (notation_render for actual rendering).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
knowledge_search4 fields changedInput schema / properties / limit / descriptionAdded value: +"Maximum chunks to return. Default 8 is right for most queries; raise for broad surveys, lower for tight context budgets."Input schema / properties / maxTokens / descriptionAdded value: +"Token budget for the combined chunk content. Default 1500 fits comfortably in most agent context windows. The endpoint greedy-selects highest-similarity chunks within this budget."Input schema / properties / step / descriptionPrevious value: -"Curriculum step number (1-49) as a fallback if you do not know the topic tag."New value: +"Curriculum step number (1-49). Fallback when you do not know the topic tag. Maps to the Gradus 10-stage curriculum: Stage I 1-7 (single voice, intervals, scales), II 8-13 (counterpoint, all 5 species), III 14-16 (harmony, third voice), IV 17-18 (form, modulation), V 19-20 (fugue), VI 21-25 (classical style, sonata), VII 26-30 (Romantic harmony, augmented sixths), VIII 31-33 (Impressionist), IX 34-36 (20th century), X 37-40 (advanced)."Input schema / properties / topics / descriptionPrevious value: -"Topic tags in kebab-case. Examples: [\"voice-leading\",\"deceptive-cadence\"], [\"chromatic-mediants\"], [\"sonata-form\",\"second-theme\"]."New value: +"Topic tags in kebab-case. Matched semantically via Voyage 3 Large embeddings plus a topic-overlap boost; exact-match is not required, so close synonyms work. Examples: [\"voice-leading\",\"deceptive-cadence\"], [\"chromatic-mediants\"], [\"sonata-form\",\"second-theme\"], [\"figured-bass\",\"6-4-2-chord\"], [\"fugue\",\"stretto\"], [\"modulation\",\"pivot-chord\"]."v0.1.1knowledge_searchnotation_examplesnotation_rendernotation_schemanotation_validateScored across 5 tools
Each tool has a clearly distinct purpose: knowledge_search for theory facts, notation_examples for example inputs, notation_render for rendering, notation_schema for schema retrieval, and notation_validate for input validation. There is no functional overlap.
Tools use a mix of noun_verb (knowledge_search, notation_render, notation_validate) and noun_noun (notation_examples, notation_schema) patterns. Additionally, one tool deviates from the 'notation_' prefix ('knowledge_search'), reducing consistency.
With 5 tools, the server is reasonably scoped for its purpose of music notation rendering and theory knowledge retrieval. It covers core functionality without being overly minimal or excessive.
The tool set covers search, retrieval of examples, input validation, schema access, and rendering. Minor potential gaps (e.g., no tool to list available examples or manage rendered outputs) are not critical for the stated domain.
Turn recordings, videos and sheet music into playable, editable scores. Transcribe audio or video (files or links) to sheet music, read sheet-music photos and PDFs, convert MIDI, MusicXML and ABC, edit notes in conversation with previews and undo, and export PDF, MIDI, MusicXML, guitar TAB, jianpu and audio. Hosted remote server with OAuth sign-in; one instrument, voice or solo piano is free.
Write lyrics in 100+ styles, score them, generate full songs with 4 engines, split stems. OAuth.
Render video and run AI media tasks from a single declarative JSON request.
Deterministic music theory for agents: analyze, voice, reharmonize, conduct — computed, not guessed
