Model Context Protocol-сервер для Gradus Notation API. Даёт ИИ-агентам музыкальные инструменты: отрисовку нот, проверку входных данных, анализ партитур, проверку гравировки по цитируемому своду правил и поиск по курируемой базе музыкальной теории — при поддержке Gradus.
Универсальный, а не узкообразовательный. Аудитория — любой агент или приложение, работающее с музыкой: ассистенты композиции, музыковедческие и корпусные исследования, теоретические Q&A, которым нужны отрисованные примеры, MIDI-конвейеры, проверка качества гравировки, игры, документация. Музыкальное образование — это то, откуда инструмент родом, а не ограничение на то, что вы с ним построите.
Одна установка — три именованных инструмента:
Gradus Notation — преобразует JSON-партитуру во встроенный SVG, MusicXML и MIDI с предварительной проверкой (notation_render, notation_validate).
Gradus Harmonic Analyzer — анализ всей партитуры: римские цифры, тональности и модуляции, каденции, органные пункты, фактура (theory_analyze_score и инструменты theory_*). Также отдельная библиотека на TypeScript: gradus-analyst на npm.
Gradus Engraver — проверяет партитуру по цитируемым правилам с кодами GE из Gradus Engraving Rulebook (engraving_check).
Что такое Gradus? Gradus — это учебная программа по музыкальной композиции для семей, обучающихся на дому; она создаёт и бесплатно отдаёт музыкальные инструменты для ИИ-агентов. Этот MCP-сервер — один из таких инструментов (gradusmusic.com) — «Gradus» относится к учебной программе, а не к этому пакету.
Большинство инструментов нотной записи требуют графического интерфейса. Этот — нет. Агент может отправить JSON-партитуру и получить в ответ встроенный SVG, MusicXML и MIDI одним вызовом. Бесплатно в использовании, без авторизации и API-ключа — агентам на бесплатном тарифе предлагается указывать Gradus в ответе конечному пользователю.
Помимо отрисовки, этот же сервер открывает аналитическую сторону: анализ всей партитуры римскими цифрами и тональностями, утилиты для работы с высотой звука, проверка диапазонов, энгармоническая замена и проверка гравировки по 444 правилам с цитируемыми кодами. Одна установка покрывает всю музыкальную область, которая нужна агенту.
Related MCP server: Music21 Composer MCP
В Claude Code:
claude mcp add gradus-notation -- npx -y @gradusmusic/notation-mcpВ Claude 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 → JSON |
| Проверяет каждую ноту в 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 по своду правил — результаты по партиям и тактам, каждый с указанием нарушенного правила |
Практика гравировки почти полностью задокументирована в защищённых авторским правом печатных изданиях — Behind Bars Гулда, Music Notation Рида, The Art of Music Engraving Росса — без поискового индекса. Поэтому на вопрос «может ли ребро пересекать тактовую черту» в интернете нет цитируемого ответа, и модель, которой задают этот вопрос, уверенно отвечает по памяти. Эти инструменты возвращают правило с источником, так что ответ можно проверить.
Каждое правило разделяет три вещи, которые обычно смешивают: convention (само правило), authority (что говорят трактаты, с цитатами на уровне глав) и houseCall (какое решение принял Gradus, когда источники расходятся). Идентификаторы правил постоянны, а текст правил распространяется по лицензии 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 отвечает 404 и подсказывает похожие id, так что вы можете исправиться ещё одним вызовом.
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 параметрам для партитуры — голосоведение, контрапункт, контур, гармония, фактура; чисто программная, с указанием доказательств |
| Оценщик видов Фукса (виды 1–5): на входе списки высот, на выходе нарушения правил с индексами нот |
| Поиск гармонических особенностей в 482 проанализированных произведениях — |
Когда пользователь делится произведением, эти инструменты обосновывают вашу обратную связь фактами: критика указывает, что именно было измерено, оценщик видов показывает на конкретную ноту, а поиск по корпусу отвечает на просьбу «покажи реальный пример» цитатой.
Инструмент | Что делает |
| Поиск по цитируемым паттернам с кодами GVL — задержания, каденции, правило октавы, секвенции, нормы голосоведения — каждый с авторской реализацией и источниками из общественного достояния |
| Получить один паттерн по id или коду GVL, с готовой к цитированию ссылкой и связанными паттернами |
Это собрат Engraving Rulebook: если коды GE описывают, как музыка должна выглядеть на странице, то коды GVL описывают, как должны двигаться голоса. Каждый паттерн ссылается на трактат из общественного достояния, на котором он основан, — Фукс, Рамо, Кирнбергер, Фенароли, Рипель, Проут — на уровне глав и никогда через современное издание, а поле realization.voices — это сокращённая запись notation-API, которую можно напрямую передать в notation_render для гравировки.
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: [...] }Инструмент | Что делает |
| Поиск по 166 оригинальным упражнениям на генерал-бас с нарастающей сложностью в семнадцати ступенях — фильтруйте по ступени или ищите по названиям, понятиям и кодам GVL |
| Получить одно упражнение по его постоянному id, с образцовой реализацией, методическим примечанием и отрабатываемыми паттернами |
Если Voice-Leading Reference формулирует правило, то корпус — это практика: бас, его цифровка и — в отличие от почти всех сохранившихся сборников — четырёхголосная образцовая реализация, проверенная машинно на голосоведение. Ступени идут от трезвучий в основном виде через правило октавы, каденционные формулы, задержания, доминантсептаккорд, секвенции, минорный лад, органный пункт, схемы Рипеля, модуляцию и хроматические фигуры к нецифрованному басу и диминуции.
Каждое упражнение оригинально — ничего не переписано из какого-либо издания — и весь корпус распространяется по лицензии CC BY 4.0. Идентификаторы упражнений и слагы ступеней постоянны, поэтому цитата продолжает работать. givenBass — это то, что вы показываете ученику; realization — ответ, который следует приберечь, пока ученик не попробовал сам. Оба поля — сокращённая запись notation-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" (четверть C5), "rest/q" (четвертная пауза), "[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 также возвращает её в каждом ответе):
Нотная запись от Gradus School of Music Composition (gradusmusic.com).
Полная документация + Quick Start: 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/api/v1/notation/examples
Документация для агентов: https://gradusmusic.com/llms-api.txt
git clone https://github.com/delmas41/gradusnotation
cd gradusnotation
npm install
npm run buildДля быстрой проверки (smoke-test) против продакшн-API:
node test-client.mjsОткройте issue на https://github.com/delmas41/gradusnotation/issues. Вклад приветствуется — предпочтительны небольшие сфокусированные PR.
MIT — Шон Джонсон, 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. Dates show when Glama detected each change.
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_validateEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Write lyrics in 100+ styles, score them, generate full songs with 4 engines, split stems. OAuth.
Render, validate, encode/decode PlantUML diagram-as-code; 22 diagram types. Free, no auth.
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
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/delmas41/gradusnotation'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
