theory_analyze_score
One-shot endpoint: parse MusicXML → run the full MaestroAnalyzer harmonic analysis pipeline → query the Gradus Knowledge Base (GKB) for curated theory chunks matched to the score's detected features. Returns both the algorithmic analysis and relevant hand-authored knowledge in a single call. WHEN...
This record as markdown: /tools/com-gradusmusic-notation/theory-analyze-score.md
What theory_analyze_score does on Gradus Notation
AI agents call theory_analyze_score to retrieve information from Gradus Notation without modifying anything. It is typically the context-gathering step in research, monitoring, and reporting workflows, before the agent takes action elsewhere.
| Parameter | Type | Required | Description |
|---|---|---|---|
xml | string | Yes | Raw MusicXML document string (score-partwise format). |
options | object | — | Optional AnalyzeScoreOptions: { useLocalKeys: "phrase"|"window"|"overall", localKeyHalfWindow?: number }. |
includeKnowledge | boolean | — | Set false to skip GKB lookup and get analysis-only. Useful when knowledge is not needed or when latency matters. |
maxKnowledgeTokens | integer | — | Token budget for GKB knowledge chunks. Raise for richer context, lower for tight budgets. |
Parameters from the server's own tool schema.
Why theory_analyze_score is rated Low
This tool performs harmonic analysis and knowledge retrieval on music scores. It reads MusicXML input, processes it through an analysis pipeline, and returns analytical results and matched theory knowledge. There is no indication that it modifies scores, executes arbitrary commands, deletes data, or involves financial transactions.
From the tool's definition Tool parses MusicXML, runs analysis pipeline, and queries knowledge base to return 'both the algorithmic analysis and relevant hand-authored knowledge in a single call.' All operations are retrievals and queries with no modification of data, no code…
Attacks that exploit this kind of access
The rule that runs theory_analyze_score safely
PolicyLayer is an MCP gateway: it sits between your AI agents and Gradus Notation, and checks every tool call against a rule you set before the call runs. Nothing changes on the server itself. For theory_analyze_score, this is the rule to start with:
theory_analyze_score is read-only, so it stays allowed. Everything else on the server is denied unless you say otherwise.
The button opens the PolicyLayer dashboard: create your workspace, connect Gradus Notation, apply this rule, and every theory_analyze_score call is checked against it from then on.
Questions about theory_analyze_score
One-shot endpoint: parse MusicXML → run the full MaestroAnalyzer harmonic analysis pipeline → query the Gradus Knowledge Base (GKB) for curated theory chunks matched to the score's detected features. Returns both the algorithmic analysis and relevant hand-authored knowledge in a single call. WHEN TO USE: when an agent has a MusicXML score and wants to know what's harmonically interesting about it — key, local-key trajectory, chord analyses with Roman numerals, cadences, phrase structure, style period, AND relevant theory context from the GKB (voice-leading rules, harmonic vocabulary, orchestration notes, historical context). This is the richest single-call analysis available. WHEN NOT TO USE: if you only need range checking (theory_validate_ranges); if you only need re-spelling (theory_respell); if you want raw GKB search without score analysis (knowledge_search). INPUT: { xml: string, maxKnowledgeTokens?: number (default 1500), includeKnowledge?: boolean (default true) } OUTPUT: { meta: { partCount, noteCount, measureCount }, analysis: { overallKey: { key, mode, confidence }, localKeys: [{ measure, key, confidence }], chordAnalyses: [{ measure, beat, primary, readings: [{ rn, rnAscii, inversion, localKey, confidence }], tendencyTones }], cadences: [{ type: "PAC"|"IAC"|"HC"|"DC"|"Plagal"|"Phrygian"|"unclear", ... }], phrases: [{ index, measureStart, measureEnd, fermataMeasures }], }, submissionHints: { stylePeriod, focusAreas, rationale }, // inferred style heuristic knowledge: { topics: string[], // GKB tags derived from the analysis chunks: [{ title, content, sourceType, era, composer, curriculumSteps }], totalTokens: number, }, } TYPICAL LATENCY: 200-600 ms (analysis is pure JS; GKB adds one Voyage embedding call ~100-200 ms). It is categorised as a Read tool in the Gradus Notation MCP Server, which means it retrieves data without modifying state.
theory_analyze_score accepts 4 parameters: xml, options, includeKnowledge, maxKnowledgeTokens. Required: xml. The full parameter table on this page comes from the server's own tool schema.
Register the Gradus Notation MCP server in PolicyLayer and add a rule for theory_analyze_score: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Gradus Notation. Nothing to install.
theory_analyze_score is a Read tool with low risk. Read-only tools are generally safe to allow by default.
Yes. Add a rate_limit block to the theory_analyze_score rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.
Set action: deny in the PolicyLayer policy for theory_analyze_score. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.
theory_analyze_score is provided by the Gradus Notation MCP server (@gradusmusic/notation-mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.
More on Gradus Notation, and thousands of servers like it.
This server
Across the catalogue