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...
This record as markdown: /tools/com-gradusmusic-notation/theory-pitch-utils.md
What theory_pitch_utils does on Gradus Notation
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
op | string | Yes | Operation to perform. |
midi | integer | — | MIDI number (0–127). Required for midi_to_pitch. |
pitch | string | — | Pitch string e.g. "C4", "F#5". Required for pitch_to_midi and transpose_pitch. |
semitones | integer | — | Semitone offset. Required for interval_name and transpose_pitch. |
preferFlats | boolean | — | Use flat spellings for black keys (Db instead of C#). Optional. |
Parameters from the server's own tool schema.
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 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.
Attacks that exploit this kind of access
The rule that runs theory_pitch_utils 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_pitch_utils, this is the rule to start with:
theory_pitch_utils 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_pitch_utils call is checked against it from then on.
Questions about 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" }. It is categorised as a Read tool in the Gradus Notation MCP Server, which means it retrieves data without modifying state.
theory_pitch_utils accepts 5 parameters: op, midi, pitch, semitones, preferFlats. Required: op. 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_pitch_utils: 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_pitch_utils 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_pitch_utils 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_pitch_utils. 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_pitch_utils 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