# 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).

Agent View of the PolicyLayer registry record for `theory_analyze_score`. HTML page: https://policylayer.com/tools/com-gradusmusic-notation/theory-analyze-score

## Facts

- Tool: `theory_analyze_score`
- Server: Gradus Notation (`@gradusmusic/notation-mcp`) — https://policylayer.com/tools/com-gradusmusic-notation.md
- Install: `npx -y @gradusmusic/notation-mcp`
- Homepage: https://github.com/delmas41/gradusnotation
- Risk category: Read (Low risk)
- Registry record: grade C, identity unverified
- Server rate-limited: no
- Parameters: 4 (1 required)
- Recommended policy verdict: Allowed

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `xml` | string | yes | Raw MusicXML document string (score-partwise format). |
| `options` | object | no | Optional AnalyzeScoreOptions: { useLocalKeys: "phrase"\|"window"\|"overall", localKeyHalfWindow?: number }. |
| `includeKnowledge` | boolean | no | Set false to skip GKB lookup and get analysis-only. Useful when knowledge is not needed or when latency matters. |
| `maxKnowledgeTokens` | integer | no | Token budget for GKB knowledge chunks. Raise for richer context, lower for tight budgets. |

Parameters from the server's own tool schema.

## Example call (MCP tools/call, JSON-RPC 2.0)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "theory_analyze_score",
    "arguments": {
      "xml": "<xml>"
    }
  }
}
```

## 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 own 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…"

## Use case

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.

## Recommended policy (PolicyLayer)

Verdict: **Allowed**. Enforced by the PolicyLayer MCP gateway (https://policylayer.com/mcp-gateway) before a call reaches Gradus Notation:

```json
{
  "version": "1",
  "default": "deny",
  "tools": {
    "theory_analyze_score": {}
  }
}
```

## Other tools on Gradus Notation (9)

- `knowledge_search` — Read — https://policylayer.com/tools/com-gradusmusic-notation/knowledge-search.md
- `notation_examples` — Read — https://policylayer.com/tools/com-gradusmusic-notation/notation-examples.md
- `notation_render` — Read — https://policylayer.com/tools/com-gradusmusic-notation/notation-render.md
- `notation_schema` — Read — https://policylayer.com/tools/com-gradusmusic-notation/notation-schema.md
- `notation_validate` — Read — https://policylayer.com/tools/com-gradusmusic-notation/notation-validate.md
- `theory_parse_xml` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-parse-xml.md
- `theory_pitch_utils` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-pitch-utils.md
- `theory_respell` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-respell.md
- `theory_validate_ranges` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-validate-ranges.md

## For agents

This record is a snapshot. Live verdicts and the full registry:

- Check every server in your MCP config at once: `npx -y policylayer stack`
- Vet a server before you add it: install the mcp-precheck skill — `npx skills add https://policylayer.com` (skill text: https://policylayer.com/skill.md)
- Query the registry over MCP: endpoint `https://api.policylayer.com/mcp` — tools `check_mcp_server`, `check_mcp_stack`, `check_tool`, `search_registry`, `get_change_events`

---

Source: the PolicyLayer MCP registry — one continuously verified record per MCP server. Full record: https://policylayer.com/registry?q=com-gradusmusic-notation · API: https://policylayer.com/registry/api · Policy library: https://policylayer.com/policies/com-gradusmusic-notation