# theory_pitch_utils

A collection of fast, pure pitch-utility operations that replace the most-used music21 pitch functions with zero network round-trip. OPERATIONS: midi_to_pitch — MIDI number → pitch string. midi=60 → "C4". preferFlats=true → "Db" spellings. pitch_to_midi — pitch string → MIDI number. "C4"→60, "F#5"→78, "Bb3"→46. Returns null for rests. interval_name — semitone count → interval quality string. 0→"P1" 3→"m3" 4→"M3" 7→"P5" 12→"P8". Compound intervals: 14→"M2+8". transpose_pitch — shift a pitch by semitones. "C4"+7→"G4", "E5"+-2→"D5". preferFlats controls black-key spelling. WHEN TO USE: fast arithmetic during score generation or analysis without invoking a full analysis pipeline; populating MIDI output tables; labeling intervals in educational contexts; transposing individual notes while composing. INPUT: { op: string, ...params } where op is one of the operations above. EXAMPLES: { op: "midi_to_pitch", midi: 60 } → { pitch: "C4" } { op: "pitch_to_midi", pitch: "F#5" } → { midi: 78 } { op: "interval_name", semitones: 7 } → { interval: "P5" } { op: "transpose_pitch", pitch: "C4", semitones: 7 } → { pitch: "G4" } { op: "transpose_pitch", pitch: "E4", semitones: 1, preferFlats: true } → { pitch: "F4" }

Agent View of the PolicyLayer registry record for `theory_pitch_utils`. HTML page: https://policylayer.com/tools/com-gradusmusic-notation/theory-pitch-utils

## Facts

- Tool: `theory_pitch_utils`
- 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: 5 (1 required)
- Recommended policy verdict: Allowed

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `op` | string | yes | Operation to perform. |
| `midi` | integer | no | MIDI number (0–127). Required for midi_to_pitch. |
| `pitch` | string | no | Pitch string e.g. "C4", "F#5". Required for pitch_to_midi and transpose_pitch. |
| `semitones` | integer | no | Semitone offset. Required for interval_name and transpose_pitch. |
| `preferFlats` | boolean | no | Use flat spellings for black keys (Db instead of C#). Optional. |

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_pitch_utils",
    "arguments": {
      "op": "<op>"
    }
  }
}
```

## Why theory_pitch_utils is rated Low

This is a Read category tool because it retrieves/computes music theory data without modifying any state. The operations perform lookups and calculations (MIDI↔pitch conversion, interval naming, transposition) but do not create, modify, delete, or execute external operations. Severity is low because misuse poses minimal risk—incorrect pitch conversions cannot damage systems or data.

From the tool's own definition: "Tool provides pure utility functions that convert and analyze pitch data: midi_to_pitch, pitch_to_midi, interval_name, transpose_pitch. All operations are read-only transformations with no side effects."

## Use case

AI agents call theory_pitch_utils 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_pitch_utils": {}
  }
}
```

## 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_analyze_score` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-analyze-score.md
- `theory_parse_xml` — Read — https://policylayer.com/tools/com-gradusmusic-notation/theory-parse-xml.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