Provides Discord webhook integration for real-time notifications on CI/CD pipeline status, pull requests, and releases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@music21-mcp-server analyze the key of Bach chorale BWV 66.6"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Professional music analysis with 4 different interfaces - MCP server, HTTP API, CLI tools, and Python library. Built on the powerful music21 library with protocol-independent architecture for maximum reliability.
Based on 2025 research showing MCP has 40-50% production success rate, this project provides multiple pathways to the same powerful music21 analysis functionality:
📡 MCP Server - For Claude Desktop integration (when it works)
🌐 HTTP API - For web applications (reliable backup)
💻 CLI Tools - For automation (always works)
🐍 Python Library - For direct programming access
Related MCP server: MusicBrainz MCP Server
Import & Export: MusicXML, MIDI, ABC, Lilypond, music21 corpus
Key Analysis: Multiple algorithms (Krumhansl, Aarden, Bellman-Budge)
Harmony Analysis: Roman numerals, chord progressions, cadence detection
Voice Leading: Parallel motion detection, voice crossing analysis
Pattern Recognition: Melodic, rhythmic, and harmonic patterns
Harmonization: Bach chorale and jazz style harmonization
Counterpoint: Species counterpoint generation (1-5)
Style Imitation: Learn and generate music in composer styles
Score Manipulation: Transposition, time stretching, orchestration
# Install the package
pip install music21-mcp-server
# Start the server
music21-mcp # MCP server for Claude Desktop
music21-http # REST API at localhost:8000
music21-cli # Interactive CLI
music21-analysis mcp # Unified launcher (positional arg)# Clone repository
git clone https://github.com/brightlikethelight/music21-mcp-server.git
cd music21-mcp-server
# Install with UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
# Or with pip
pip install .
# Configure music21 corpus
python -m music21.configurepython -m music21_mcp.launcher# Start MCP server
python -m music21_mcp.launcher mcp
# Configure Claude Desktop with:
# ~/.config/claude-desktop/config.json
{
"mcpServers": {
"music21-analysis": {
"command": "python",
"args": ["-m", "music21_mcp.server_minimal"],
"env": {
"PYTHONPATH": "/path/to/music21-mcp-server/src"
}
}
}
}# Start HTTP API server
python -m music21_mcp.launcher http
# Opens: http://localhost:8000
# API docs: http://localhost:8000/docs
# Example usage:
curl -X POST "http://localhost:8000/scores/import" \
-H "Content-Type: application/json" \
-d '{"score_id": "chorale", "source": "bach/bwv66.6", "source_type": "corpus"}'
curl -X POST "http://localhost:8000/analysis/key" \
-H "Content-Type: application/json" \
-d '{"score_id": "chorale"}'# Show CLI status
python -m music21_mcp.launcher cli status
# Import and analyze a Bach chorale
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale
python -m music21_mcp.launcher cli harmony chorale roman
# List all tools
python -m music21_mcp.launcher cli toolsfrom music21_mcp import create_sync_analyzer
# Create analyzer
analyzer = create_sync_analyzer()
# Import and analyze
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
key_result = analyzer.analyze_key("chorale")
harmony_result = analyzer.analyze_harmony("chorale", "roman")
print(f"Key: {key_result}")
print(f"Harmony: {harmony_result}")
# Quick comprehensive analysis
analysis = analyzer.quick_analysis("chorale")# Run all tests
python -m pytest tests/ -v
# Run with coverage threshold
python -m pytest tests/ --cov=src/music21_mcp --cov-fail-under=82# Install development dependencies
uv sync --dev
# Set up pre-commit hooks
pre-commit install
# Run linting
ruff check src/
ruff format src/
# Type checking
mypy src/Core Value Layer:
├── services.py # Music21 analysis service (protocol-independent)
└── tools/ # 13 music analysis tools
Protocol Adapter Layer:
├── adapters/mcp_adapter.py # MCP protocol isolation
├── adapters/http_adapter.py # HTTP/REST API
├── adapters/cli_adapter.py # Command-line interface
└── adapters/python_adapter.py # Direct Python access
Unified Entry Point:
└── launcher.py # Single entry point for all interfacesCore Value First: Music21 analysis isolated from protocol concerns
Protocol Apocalypse Survival: Works even when MCP fails (30-40% of time)
Multiple Escape Hatches: Always have a working interface
Reality-Based: Built for today's MCP ecosystem, not enterprise dreams
Interface | Success Rate | Best For |
MCP | 40-50% | AI assistant integration |
HTTP | 95%+ | Web applications |
CLI | 99%+ | Automation & scripting |
Python | 99%+ | Direct programming |
docs/architecture.md - System architecture overview
docs/getting-started.md - Quick start guide
examples/ - Working code examples
API Docs: http://localhost:8000/docs (when HTTP server running)
.github/webhook-config.md - Complete Discord webhook setup guide
docs/webhook-integration.md - Advanced webhook configuration
scripts/test-webhook.sh - Test webhook connectivity
scripts/setup-webhook.sh - Automated webhook setup
# Server host and port (used by HTTP adapter and launcher)
export MUSIC21_MCP_HOST=127.0.0.1
export MUSIC21_MCP_PORT=8000
# Operation timeouts (seconds)
export MUSIC21_MCP_TIMEOUT=30 # General async operation timeout
export MUSIC21_TOOL_TIMEOUT=30 # Per-tool execution timeout
export MUSIC21_CHORD_ANALYSIS_TIMEOUT=60 # Chord analysis timeout
export MUSIC21_BATCH_TIMEOUT=30 # Batch processing timeout
# CORS origins for HTTP adapter (comma-separated)
export MUSIC21_CORS_ORIGINS="http://localhost:*"# Configure corpus path (one-time setup)
python -m music21.configureimport_score - Import from corpus, files, URLs
list_scores - List all imported scores
get_score_info - Detailed score information
export_score - Export to MIDI, MusicXML, etc.
delete_score - Remove scores from storage
analyze_key - Key signature analysis
analyze_chords - Chord progression analysis
analyze_harmony - Roman numeral/functional harmony
analyze_voice_leading - Voice leading quality analysis
recognize_patterns - Melodic/rhythmic patterns
harmonize_melody - Automatic harmonization
generate_counterpoint - Counterpoint generation
imitate_style - Style imitation and generation
# CLI approach
python -m music21_mcp.launcher cli import chorale bach/bwv66.6 corpus
python -m music21_mcp.launcher cli key-analysis chorale
# Python approach
analyzer = create_sync_analyzer()
analyzer.import_score("chorale", "bach/bwv66.6", "corpus")
print(analyzer.analyze_key("chorale"))# For Claude Desktop
python -m music21_mcp.launcher mcp
# For web development
python -m music21_mcp.launcher http
# For command-line work
python -m music21_mcp.launcher cli statusThe previous enterprise version has been simplified for reliability:
✅ Kept: All music21 analysis functionality
✅ Added: HTTP API, CLI, Python library interfaces
❌ Removed: Docker, K8s, complex auth, monitoring (too unstable for MCP ecosystem)
🔄 Changed: Focus on core value delivery through multiple interfaces
Get real-time notifications for CI/CD pipeline status, pull requests, and releases:
We welcome contributions! Please see our Contributing Guide for details on:
Development setup and requirements
Code style guidelines (Ruff, MyPy)
Testing requirements (maintain >82% coverage)
Pull request process
Branch protection rules
Quick start:
Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Run tests: pytest tests/ --cov=src/music21_mcp --cov-fail-under=82
Commit changes: git commit -m 'feat: Add amazing feature'
Push branch: git push origin feature/amazing-feature
Submit pull request
MIT License - see LICENSE file for details.
Built on the excellent music21 library
Uses FastMCP for MCP protocol support
Inspired by the need for reliable music analysis tools
Choose the interface that works for you. All provide the same powerful music21 analysis capabilities! 🎵
Analyze chord progressions in a score
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'analyze', implying a read operation, but does not specify auth requirements, side effects, or return behavior. The agent lacks essential transparency about what happens when invoked.
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 extremely concise at four words, with no redundancy. However, it is under-specified; it could add key details (e.g., 'extracts chord labels from a score') without significantly increasing length.
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?
The tool has one parameter, no output schema, and no annotations. The description provides minimal context: it fails to explain what the analysis produces (e.g., chord symbols, Roman numerals), any constraints, or how results are returned. This is critically incomplete for an analytical 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 description coverage is 0%, and the description adds no meaning beyond the parameter name. While 'score_id' is self-explanatory, the tool needs to indicate its purpose (e.g., identifying which score to analyze). The description fails to compensate for the lack of schema documentation.
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 verb 'Analyze' and the resource 'chord progressions in a score', making the tool's purpose explicit. However, it does not differentiate from sibling tools like harmony_analysis, which may overlap.
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?
No usage guidance is provided. The description does not indicate when to use this tool over alternatives such as harmony_analysis or key_analysis, leaving the agent uncertain about selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a score from storage
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose that deletion is irreversible or if any confirmation is needed. Assumes destructive intent without warning.
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?
Very concise (1 sentence). However, it is under-specified; conciseness is appropriate for a simple tool but should include more context without being verbose.
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 output schema and no annotations, the description should clarify the destructive nature, required permissions, or confirmation steps. It lacks completeness for safe invocation.
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?
Parameter 'score_id' has no description in schema (0% coverage) and the tool description does not explain its meaning, origin, or constraints. Adds no value 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 verb 'delete' and object 'score' clearly indicate the action, but it lacks specificity like 'by ID' or 'permanently'. It distinguishes from siblings like 'list_scores' or 'score_info'.
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?
No guidance on when to use or when not to use this tool. No mention of prerequisites or alternatives like 'export_score' before deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a score to various formats
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | musicxml | |
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description omits any behavioral traits such as side effects (e.g., file creation, storage location), authentication requirements, or rate limits. Without annotations, the agent has no safety information.
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 sentence with no waste, but its brevity sacrifices necessary information. It is under-informative rather than efficiently 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?
For a tool with 2 parameters and no annotations or output schema, the description is far from complete. It does not cover return values, usage examples, or constraints.
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 description coverage is 0%, and the description adds no meaning beyond the parameter names 'format' and 'score_id'. Valid format values are not listed.
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 states the action (export) and resource (score), but the phrase 'various formats' is vague and does not specify which formats are supported. It is clear enough to distinguish from siblings like import_score, but lacks specificity.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., downloading or sharing). No prerequisites or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate species counterpoint (1=note-against-note, 2=2:1, 3=3:1, 4=syncopated, 5=florid)
| Name | Required | Description | Default |
|---|---|---|---|
| species | No | ||
| score_id | Yes | ||
| voice_position | No | above |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states it generates counterpoint but does not specify if it modifies the score, creates a new one, or returns data. No mention of side effects, authorization needs, or result format.
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 sentence with no wasted words. It efficiently conveys the core purpose and the species mapping.
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 has 3 parameters (one required), no output schema, and no annotations, the description is too minimal. It lacks details on preconditions, output, and overall behavior, leaving the agent uncertain about invocation and results.
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 description adds meaning to the 'species' parameter with a mapping of integer values to counterpoint styles, which is helpful. However, it provides no information about 'score_id' (the required parameter) or 'voice_position' (e.g., what values are valid, such as 'above' and 'below'?). Schema coverage is 0%, so description partially compensates but is incomplete.
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 specifies the action ('generate') and the resource ('species counterpoint'), and provides a mapping of species numbers to styles. However, it does not differentiate from sibling tools like harmonize_melody or voice_leading_analysis, which could be clarified.
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?
No explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description implies generation of counterpoint but lacks context on required input (e.g., a cantus firmus) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate harmonization for a melody in various styles (classical, jazz, pop, modal)
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | classical | |
| score_id | Yes | ||
| voice_parts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the tool modifies the original score, requires specific permissions, or returns a new score. The description is minimal and does not compensate for the lack of annotations.
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 sentence, efficient and front-loaded. However, it is underspecified given the tool's complexity, but that is more a completeness issue than conciseness.
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?
With no output schema, no annotations, and 0% schema coverage, the description is severely incomplete. It does not explain what the tool returns, how it uses the score_id, or what the styles entail. An agent cannot confidently invoke this tool without additional 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?
Schema description coverage is 0%, and the description adds no meaning to the parameters. For instance, 'style' does not list allowed values (though implied in the description), and 'voice_parts' is not explained. The description fails to compensate for the missing schema descriptions.
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 generates harmonization for a melody and lists styles (classical, jazz, pop, modal). The verb 'generate' and the resource 'melody' are specific, and the tool is distinguishable from siblings like 'generate_counterpoint' or 'harmony_analysis'.
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?
No guidance on when to use this tool versus alternatives like 'generate_counterpoint' or 'chord_analysis'. There is no mention of prerequisites, contexts, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform harmony analysis (roman numeral or functional)
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes | ||
| analysis_type | No | roman |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It fails to state whether the tool is read-only, requires authentication, or has any side effects. Minimal information given.
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 very short (one sentence), which is concise but lacks sufficient detail. It is not verbose, but it sacrifices clarity for brevity.
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?
Despite having no output schema and multiple sibling tools, the description does not explain what the analysis result contains, prerequisites (e.g., score must exist), or any other context. Incomplete for effective tool selection.
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 0%, and the description does not explicitly mention either parameter. It hints at 'roman numeral or functional' which relates to analysis_type, but does not clarify the score_id parameter or provide any parameter details.
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?
Description states the tool performs harmony analysis with roman numeral or functional types, which is somewhat specific but vague on what 'harmony analysis' exactly entails. It does not differentiate from sibling tools like chord_analysis or voice_leading_analysis, which could cause confusion.
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?
No guidance on when to use this tool versus alternatives like chord_analysis or key_analysis. Context signals show several related sibling tools, but the description provides no hints on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check server and adapter health
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond a vague 'check health'. No annotations exist, so it doesn't disclose whether it's a read operation, requires authentication, or what 'health' entails (e.g., uptime, latency).
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 sentence with no waste, satisfying conciseness. It is front-loaded but could be slightly more informative within the same length, e.g., specifying what aspects of health are checked.
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?
For a zero-parameter, no-output-schema tool with low complexity, the description is minimally adequate. However, it fails to clarify the return value or behavior (e.g., status code vs. textual report), leaving ambiguity for an AI agent.
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?
There are zero parameters, so schema coverage is trivially 100%. The description does not need to add parameter meaning, and no information beyond the empty schema is required. Baseline 4 applies.
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 'Check server and adapter health' uses a specific verb ('Check') and resource ('server and adapter health'), clearly distinguishing it from sibling tools which are all music-related (e.g., chord_analysis, harmonize_melody).
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?
No guidance is provided on when to use this tool versus alternatives or any prerequisites. With zero siblings sharing functionality, the description should at least hint at context like monitoring or diagnostics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate music imitating a specific composer style (bach, mozart, chopin, debussy) or analyze score for style
| Name | Required | Description | Default |
|---|---|---|---|
| composer | No | ||
| score_id | No | ||
| complexity | No | medium | |
| generation_length | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses two modes but omits crucial behavioral traits: whether generation/analysis modifies data, authentication needs, rate limits, or side effects. The output format is not mentioned.
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?
Single sentence, front-loaded with the core functionality. No redundant words or extraneous details.
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 4 parameters, no required ones, and no output schema, the description should clarify optional parameters and return values. It only covers the two main use cases, leaving complexity and generation_length unexplained.
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 description coverage is 0%, and the description only indirectly maps 'composer' and 'score_id' to the two modes. Parameters 'complexity' and 'generation_length' are undocumented, leaving their purpose and acceptable values unclear.
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 two distinct functions: generating music imitating specific composers (listing examples) and analyzing a score's style. This differentiates it from sibling tools like chord_analysis or pattern_recognition, which do not perform style imitation.
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 implies usage for imitation or analysis but does not provide explicit guidance on when to prefer this tool over alternatives or when not to use it. No exclusion criteria or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a score from various sources
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| score_id | Yes | ||
| source_type | No | corpus |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the tool is an import operation (creating a new resource), but with no annotations, it fails to disclose critical behavioral details such as whether existing scores are overwritten, authentication requirements, or error handling. The brief description leaves the agent guessing.
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 sentence, which is concise, but it sacrifices informative content. It is appropriately short for what it says, but it does not fully earn its place as it omits important details.
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 has 3 parameters, no annotations, and no output schema, the description is severely incomplete. It fails to explain the purpose of each parameter, supported sources, return value, or any side effects, making it inadequate for an agent to use correctly.
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 description coverage is 0%, and the description adds no explanation for the three parameters (source, score_id, source_type). Parameter names provide minimal hints, but the description does not clarify their meaning, formats, or allowed values, especially the 'source_type' with a default of 'corpus'.
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 imports a score from various sources, distinguishing it from sibling tools like export_score or delete_score. However, 'various sources' is vague and lacks specificity about supported source types.
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 no guidance on when to use this tool versus alternatives, such as when to prefer it over export_score or list_scores. There is no context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the key signature of a score
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as being read-only, potential side effects, or required permissions.
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?
While concise, the description is overly sparse and fails to include essential context, making it less useful.
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 lack of annotations, output schema, and parameter documentation, the description is insufficient for an agent to use the tool correctly.
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 0% description coverage, and the tool description adds no meaning to the 'score_id' parameter, leaving its purpose unexplained.
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 action ('Analyze') and the specific resource ('key signature of a score'), distinguishing it from sibling tools like chord_analysis or harmony_analysis.
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?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available scores
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral details like side effects, permissions, or return format. It only states 'list all available scores' with no additional context.
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 concise and front-loaded. However, it is too terse and could be expanded to include more useful information without losing conciseness.
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 zero parameters and no output schema, the description lacks completeness. It does not explain the return format, pagination, or any filters, leaving the agent without critical 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?
No parameters exist, but the description could add meaning about the output. It doesn't specify what information is returned (e.g., IDs, names), so it adds minimal value 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 action (list) and resource (scores). It distinguishes from sibling tools like 'score_info' which likely returns details of a single score, but could be more specific about scope.
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?
No guidance on when to use this tool versus alternatives. There's no mention of use cases, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recognize patterns in music
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes | ||
| pattern_type | No | melodic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description provides no behavioral details (e.g., whether it mutates data, requires permissions, or returns results). The verb 'recognize' is underspecified.
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?
Extremely concise but to the point of being inadequate. The description is too short to convey necessary information.
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?
With two parameters, no output schema, and no annotations, the description fails to provide enough context for an AI agent to use the tool correctly.
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 description coverage is 0%. The description adds no meaning to parameters; 'pattern_type' default is given but not explained.
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?
Description is vague: 'Recognize patterns in music' does not specify what kind of patterns (melodic, rhythmic, etc.) or how they are recognized. It fails to distinguish from siblings like chord_analysis or harmony_analysis.
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?
No guidance on when to use this tool vs alternatives like harmony_analysis. No context provided for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a score
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry full burden. It only says 'Get detailed information,' implying a read operation, but does not disclose limitations, authentication needs, or scope of data returned.
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 efficient sentence with no wasted words, perfectly 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 tool's simplicity (1 parameter, no output schema), the description is minimally adequate but lacks specifics about return value or what 'detailed information' comprises.
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 description coverage is 0%, and the description adds no meaning beyond the schema for score_id. The parameter is self-explanatory, but the description should clarify format or source of score_id given low coverage.
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 states 'Get detailed information about a score,' which is a clear verb+resource but fails to specify what 'detailed information' entails or distinguish it from sibling analysis tools like chord_analysis or harmony_analysis.
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?
No guidance is provided on when to use this tool versus alternatives such as the specific analysis tools (e.g., harmony_analysis). The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze voice leading patterns in a score
| Name | Required | Description | Default |
|---|---|---|---|
| score_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description alone must disclose behavioral traits. It only says 'analyze', giving no info on side effects, read-only nature, error handling, or authentication needs.
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?
Extremely concise (one sentence), but it under-specifies the tool. Conciseness is not a virtue when it omits critical information.
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?
No output schema, no annotations, and only one parameter. The description should explain what the analysis returns, prerequisites, or any side effects, but it provides none of this 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?
Schema has 0% description coverage for its only parameter (score_id). The description does not mention or clarify the parameter at all, failing to add value 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 uses a specific verb ('Analyze') and target resource ('voice leading patterns in a score'), clearly distinguishing it from sibling tools like chord_analysis or harmony_analysis. It lacks details on what 'voice leading patterns' entails but purpose is clear enough.
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?
No guidance on when to use or not use this tool vs alternatives. No prerequisites, context, or exclusion criteria provided.
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.
v1.0.0chord_analysisdelete_scoreexport_scoregenerate_counterpointharmonize_melodyharmony_analysishealth_checkimitate_styleimport_scorekey_analysislist_scorespattern_recognitionscore_infovoice_leading_analysisScored across 14 tools
Each tool targets a distinct task: analysis tools (chord, harmony, key, voice leading, pattern) are clearly separated, generation tools (counterpoint, harmonization, style imitation) are unique, and file management (import/export/list/delete/info) plus health check round out the set without overlap.
All names use lowercase with underscores, but there is a mix of verb-noun (e.g., delete_score, generate_counterpoint) and noun-verb/noun-noun patterns (e.g., chord_analysis, health_check). The inconsistency is minor and the names remain clear and predictable.
14 tools cover analysis, generation, and file management without being excessive. The count is well-scoped for a music theory server, each tool earns its place.
The set covers core music analysis and generation tasks, plus basic score I/O. Missing a 'create_score' tool (relying on import/generation) and some advanced compositional features, but overall it's reasonably complete for its domain.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Create, co-edit, analyze, publish, and export collaborative step-sequencer sessions through MCP.
MCP server for the Inistate platform: module discovery, entry management, and activity submission.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
