knowledge_search
Search the Gradus music-theory knowledge base for authoritative source material. The corpus includes hand-authored curriculum prose, Bach chorale analysis (408 chorales), score commentaries on 50+ orchestral works, and primary historical sources from Fux (1725) through Boulanger. WHEN TO USE: bef...
This record as markdown: /tools/com-gradusmusic-notation/knowledge-search.md
What knowledge_search does on Gradus Notation
AI agents call knowledge_search 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 |
|---|---|---|---|
step | integer | — | Curriculum step number (1-49). Fallback when you do not know the topic tag. Maps to the Gradus 10-stage curriculum: Stage I 1-7 (single voice, intervals, scales |
limit | integer | — | Maximum chunks to return. Default 8 is right for most queries; raise for broad surveys, lower for tight context budgets. |
topics | array | — | Topic tags in kebab-case. Matched semantically via Voyage 3 Large embeddings plus a topic-overlap boost; exact-match is not required, so close synonyms work. Ex |
maxTokens | integer | — | Token budget for the combined chunk content. Default 1500 fits comfortably in most agent context windows. The endpoint greedy-selects highest-similarity chunks |
Parameters from the server's own tool schema.
Why knowledge_search is rated Low
This tool queries a static knowledge base and returns informational results about music theory. It retrieves data without side effects, making it a Read operation. The low severity reflects the benign nature of accessing educational reference material with no capability to modify state, execute code, or cause harm.
From the tool's definition Tool description states 'Search the Gradus music-theory knowledge base' and lists retrieval of 'hand-authored curriculum prose, Bach chorale analysis, score commentaries, and primary historical sources.' No modifications, deletions, code execution, or…
Attacks that exploit this kind of access
The rule that runs knowledge_search 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 knowledge_search, this is the rule to start with:
knowledge_search 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 knowledge_search call is checked against it from then on.
Questions about knowledge_search
Search the Gradus music-theory knowledge base for authoritative source material. The corpus includes hand-authored curriculum prose, Bach chorale analysis (408 chorales), score commentaries on 50+ orchestral works, and primary historical sources from Fux (1725) through Boulanger. WHEN TO USE: before generating notation if you need to look up a specific theory fact — typical voice leading for a Neapolitan-to-V resolution, idiomatic figured-bass realizations of a particular cadence, what makes a chromatic mediant feel like one composer's style versus another. Hitting this first prevents the agent from inventing chord progressions that are stylistically wrong. WHEN NOT TO USE: for generic music vocabulary ("what is a chord?") that any LLM already knows; for non-theory queries like composer biographies, performance recommendations, or history dates — those are out of scope; for fetching actual score notation (use notation_render or notation_examples instead). INPUT: provide EITHER topics (kebab-case tags) OR step (curriculum step 1-49). Topics are stronger; step is the fallback when you do not know the canonical topic tag. Both empty returns a MISSING_QUERY error. OUTPUT (JSON): { ok: true, requestId, chunks: [{ id, sourceType, sourceId, title, content, composer?, era?, topics: string[], curriculumSteps: number[], tokenEstimate }], meta: { query, returnedCount, totalTokens, responseTimeMs }, attribution }. sourceType is one of: kg_concept, score_analysis, score_commentary, bach_chorale_analysis, composer, dictionary, curriculum, lesson_content, practicum, voice_leading, fugue, chorale_exercise, etc. Empty chunks: [] when nothing matched the topics — agent should fall back to its own knowledge or try a different topic tag. EXAMPLE INPUT: { "topics": ["voice-leading", "deceptive-cadence"], "limit": 3 } TYPICAL LATENCY: 200-700 ms (one Voyage 3 embedding call + Supabase pgvector RPC). It is categorised as a Read tool in the Gradus Notation MCP Server, which means it retrieves data without modifying state.
knowledge_search accepts 4 parameters: step, limit, topics, maxTokens. 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 knowledge_search: 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.
knowledge_search 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 knowledge_search 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 knowledge_search. 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.
knowledge_search 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