Allows the Strudel-based music page to play real MIDI instruments, with support for instrument setup files, sounds/catalogs, and instrument-specific tone, part, and scene settings described by user-provided model files.
The moon guides the tide.
Early: Moontide is young and has known bugs, and its Scratchpad is early experimental (see the known limits).
A hobby project: Claude plays live music for you. Describe a mood, a theme or an idea, and Claude writes Strudel code that plays in your browser and changes without ever stopping.
▶ Watch the demo on YouTube (3 minutes, with sound)
Moontide is a personal project. Most of the code, research and documentation was written by an AI coding assistant working under my direction. I set the goals, listened to every change, tried it on my own instruments, judged the results by ear, and made the decisions. I am responsible for what is here, errors included.
Related MCP server: Claude DJ MCP
You talk ("start something dreamy in D minor", "darker", "add a bass"). Claude writes Strudel code, and a browser page plays it at once, without stopping the music.
The code is always visible and editable. Every version that played is kept, and Claude can bring any of them back.
The page shows the music in several views: a timeline of named tracks where you can edit notes, a Song grid, the history, a mixer and a jam view with the scale on a piano or a guitar.
A right-click on anything in the page sends Claude a request with that context.
Claude can move the tempo up or down over a number of bars, instead of jumping.
The same code can play real MIDI instruments from the page, and a Scratchpad (early experimental) lets you draw or play in a motif and send it to Claude.
On an instrument whose model describes them, Claude can set tone, part and scene settings that no program change carries, written in the code like a sound or a control. Moontide stores none of them. The models that describe settings are files of your own; none ships with Moontide.
Moontide does not start from scratch. The music engine is Strudel, the JavaScript port of TidalCycles by Felix Roos, Alex McLean and the Strudel contributors. Moontide is the bridge between Claude and a Strudel page.
What you need: Node 22 or later, Claude Code or Claude Desktop, Chrome (Chrome or Edge for MIDI), internet access (Strudel and its sounds load from the web), and speakers or headphones.
claude mcp add --scope user moontide -- npx -y moontide-mcpThen start a new Claude session and ask for music. Claude Desktop, Windows, running from the source code, updating and uninstalling are on the manual's Install page.
Start a new Claude session. Nothing opens yet: Moontide waits until you want it.
Ask for music, for example "Play something calm to start the day". Or say "start Moontide".
The page opens in a new tab at http://localhost:5757, or on another port when 5757 is busy.
Click once anywhere in the page. Browsers start sound only after a click.
Ask for changes: "darker", "add a bass", "slower".
More in First music.
The manual is at https://konni-arcadia.github.io/moontide/. It is written in plain words, and every page ends with a box that says what was checked and what was not.
Getting started: Install, First music and the page and its views.
Working with Claude: asking Claude, requests from the page, small edits, song structure, tempo ramps and history.
MIDI gear: instruments and the setup file, sounds and catalogs, tone, part and scene settings, the Scratchpad, keyboard input and sending a motif.
Troubleshooting: problems and known limits.
How it works: the pieces and the tools, what was measured, and network, privacy, credits and license.
The same pages can be read on GitHub, as Markdown, in the site folder.
Early and personal. It runs on one setup: a Mac, Chrome, Claude Code and Claude Desktop, and, for MIDI, a Roland SC-55, the Munt MT-32 emulator and a Roland JUPITER-Xm. It has not been tried anywhere else. The test suite runs on Windows, Linux and macOS in CI, but nobody has played music on Windows or Linux yet. There are known bugs. Feedback is welcome, but support is not something I can promise. The list is in Known limits. What is not yet checked by hand is listed at the end of each manual page and in the changelog.
The server listens on 127.0.0.1 only and sends nothing out. The page loads Strudel and its samples from the web. Details: network, privacy, credits and license.
Bug reports and ideas are welcome as issues (use the bug form). How pull requests are handled is in CONTRIBUTING.md.
Security problems go through a private report, never a public issue. See https://github.com/konni-arcadia/moontide/security/policy.
Built on Strudel by Felix Roos, Alex McLean and the Strudel contributors (source: https://codeberg.org/uzu/strudel), on TidalCycles by Alex McLean and its community, on the sample sets Strudel loads (including the TidalCycles Dirt-Samples and the Versilian Community Sample Library), on the Model Context Protocol and its TypeScript SDK from Anthropic, and on the acorn parser. The full list is on the credits page.
Moontide plays Strudel, which is under AGPL-3.0-or-later. Moontide uses the same license. It loads Strudel from unpkg at run time and does not ship it. The license text is in LICENSE. Moontide is not affiliated with, or endorsed by, the Strudel or TidalCycles projects, or Anthropic.
Konni — built with an AI coding assistant.
Closes a request typed in the Moontide page without changing the music. Use outcome answered when the request was answered in words, declined when it will not or cannot be done. Give one sentence of at most 200 characters; the page shows it under the request. A change that answers a request names it with answering on set_code, edit_code or restore_version instead. An id that is not an open request is refused and nothing changes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the page request to close, from its request line | |
| text | Yes | One sentence for the user, at most 200 characters; the page shows it under the request | |
| outcome | Yes | answered when the request was answered in words, declined when it will not or cannot be done |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the lone destructiveHint=false annotation, the description discloses that no music is changed, that text is displayed under the request, and that an id which is not an open request is refused with no changes. That is meaningful side-effect and failure-mode context. It stops short of describing authorization needs or whether the close is reversible, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four tight sentences with zero waste. The core action and scope come first, followed by outcome semantics, text constraint, sibling alternatives, and failure behavior in a logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter, non-destructive close operation with no output schema, the definition covers the action, both outcome modes, the text requirement, the id failure mode, and the correct sibling tools. Nothing an agent needs in order to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents all three parameters, including the outcome enum and the 200-character text limit. The description largely restates that same information rather than adding new format, source, or edge-case detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource — 'Closes a request typed in the Moontide page' — and immediately scopes it with 'without changing the music'. It also explicitly distinguishes this tool from set_code, edit_code, and restore_version, so an agent can route correctly without opening sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use each outcome: 'answered when the request was answered in words, declined when it will not or cannot be done.' It also names the alternatives for change-based answers — set_code, edit_code, and restore_version with 'answering' — providing explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes part of the code that will play by exact text replacement, sending only the change. Use it to change an existing piece; use set_code for a new piece or a rewrite of most of its lines. Each edit has old_string, new_string and optional replace_all, as in your own Edit tool. Every old_string must match exactly once (or set replace_all), and every edit is matched against the code as it is before this call, so edits must not overlap and one edit cannot match text another edit writes. An edit that matches nowhere, matches more than once, overlaps another edit or changes nothing refuses the whole call with the reason and the edit number: nothing is applied and nothing reaches the page. CRLF counts as LF. The edits apply to the newest code that will play: the change waiting for its bar or phrase line when one waits (get_code shows the code playing until then), otherwise the code playing now with the user's evaluated hand edits; text typed in the page but not evaluated is replaced, as with set_code. Pass base, the version number get_code shows, to have the edit refused when the music moved on since. at, phraseCycles and label work as in set_code, and the edited program goes through the same checks, history entry and notices. The reply gives the version, when the change takes over and the changed lines with a few lines around them, not the whole program; get_code returns it. Put all replacements for one change in a single call: a second edit_code sent before the first reply is refused. It edits music that already plays, so before Moontide is started it is refused and starts nothing: use set_code first. Call get_code before changing existing music.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | When the change takes over: 'now' (the default) within a fraction of a second, 'bar' on the next bar line, 'phrase' on the next phrase line (4 cycles, counted from Play). The code is checked at once; the reply says the cycle and about how many seconds away it is. | |
| base | No | The version number get_code shows (#N); the edit is refused when another version plays now | |
| edits | Yes | The replacements, 1 to 50, applied all together or not at all | |
| label | No | A few words saying what this change is, for example "added a bass"; shown by list_history | |
| answering | No | The id of the page request this change answers, from its request line; the page shows that request as applied only when the change names it here | |
| glideBars | No | Whole bars, 1 to 64, to move the tempo smoothly from the tempo that plays to the one this code sets with setcps or setcpm; with at, it starts at the line. Refused when nothing plays, no tempo is set or it already plays. Stop, or code with another tempo or none, cancels it | |
| phraseCycles | No | How many cycles one phrase lasts, for at: 'phrase' (2 to 64, default 4) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses atomicity ('nothing is applied and nothing reaches the page'), the exact rejection reasons reported with the edit number, the reference version edits apply against, CRLF-as-LF normalization, and the concurrency rule. It also describes the shape of the reply (version, takeover time, changed lines with context). The main gap is permissions/auth and rate-limit context, which is minor here given the richness of the rest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the sibling contrast are front-loaded in the first two sentences, and almost every sentence carries operational information. It is dense and paragraph-shaped rather than scannable, and a few clauses (the parenthetical about get_code showing the playing code, the repeated get_code advice at the end) restate earlier points, costing some tightness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no output schema, the description covers everything an agent needs: preconditions, atomicity, matching rules, precedence between pending and currently playing code, batching, concurrency, and what the reply does and does not contain. It explicitly defers the full program to get_code, which closes the remaining question about return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter meaning the schema cannot express: edits are matched against the pre-call code, must not overlap, and one edit cannot match text another edit writes. It also explains base as the version from get_code that causes refusal when the music moved on, and says at/phraseCycles/label work as in set_code rather than restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource and mechanism: 'Changes part of the code that will play by exact text replacement, sending only the change.' It immediately contrasts itself with the sibling set_code ('use set_code for a new piece or a rewrite of most of its lines'), so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing rules against alternatives (set_code for new code or majority rewrites, get_code before editing existing music), plus hard preconditions ('before Moontide is started it is refused... use set_code first') and a batching rule ('Put all replacements for one change in a single call'). It even names the failure mode of violating that rule (a second edit_code sent before the first reply is refused).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keeps a version as a named favorite, by its id from list_history (the version playing now is the one shown as v{id} in the page top bar). Favorites are never dropped from the history. Favoriting the same id again renames it. List favorites with list_history and favorites: true.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Version id from list_history | |
| name | Yes | Name to keep it under, in the user's words |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose non-obvious behavior: favorites are never dropped from history, and favoriting the same id again renames rather than duplicating. It does not mention permissions, error cases, or what the call returns, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the core action front-loaded and every sentence adding operational value (id source, rename semantics, how to list favorites). There is no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers the important preconditions and side effects, including where the id comes from and the rename-on-repeat behavior. The only real gap is that it does not say what the tool returns or confirm the scope of the favorite name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: id specifically comes from list_history and can be read off the top bar as v{id}. The name parameter is only lightly elaborated beyond the schema's 'in the user's words' wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Keeps a version as a named favorite') and ties it to a concrete id source (list_history), which separates it from siblings like restore_version and list_history. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to call it (naming a version, id from list_history, v{id} in the top bar) and notes the rename case when favoriting the same id again. It stops short of explicitly excluding restore_version or naming it as the alternative, so it is not a full when/when-not routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the Strudel code currently playing in the Moontide page, i.e. the last code the page confirmed, including edits the user evaluated by hand; returns 'Nothing is playing yet.' before anything played, with a template of a song structure to start from. Before Moontide is started it says so and starts nothing; after the start its reply also names the page address, the port and the tab title. Call it before every change.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds much beyond the readOnlyHint annotation. It describes the sentinel response 'Nothing is playing yet.' and the song-structure template returned alongside that response. It also describes the state before Moontide is started ('starts nothing') and the metadata returned after start (page address, port, tab title).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The key fact, that this reads the currently playing code, comes first, and every clause adds real information about the return states. The single run-on sentence packs in many clauses, so the dense signal slightly hurts readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry the full load of explaining return values, and it does. It covers the empty case (sentinel plus template), the not-yet-started case, and the started case with metadata. An agent can call this tool and interpret every response state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to disambiguate, and the baseline score is 4. The description adds no parameter detail that it would need to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: it reads the Strudel code currently playing, meaning the last code the page confirmed. Its scope, 'including edits the user evaluated by hand', separates it from a plain state dump. It never names a sibling such as set_code or edit_code, but the closing instruction 'Call it before every change' does suggest how it relates to those mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'Call it before every change' clearly states when to use this tool, tying it to the mutation siblings. The description does not name an alternative or list a when-not case, but the context and the rule are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When the user has described their instruments, call this before writing MIDI code. Lists the MIDI instruments the user described in instruments.json, as facts: for each one its id, model, exact port name, whether it is connected right now, its channels and their roles, how many sounds it has, its bank select, its reset, whether it follows MIDI clock and its controls. Pass instrument (an id from that list) to get that instrument's full sound list, with the program number sent for each sound and its bank when it has one. A sound is chosen in the code with the sound option of .midi(). An instrument with a sound catalog shows how many sounds the catalog holds and its categories; search_midi_sounds finds them. For an instrument whose model describes settings it lists the tone, part and scene setting names with their ranges, the tone ones per engine, and the settings topic of get_strudel_reference has their rules; with instrument set it gives the engine of each sound the catalog places in one. For an instrument with a rhythm channel it says how a kit goes out and which drum map applies; with instrument set it lists each drum map as note numbers and drum names, a kit's own map only when it differs from the model's, and says when a kit has no known map. Drum notes are written as note numbers in the code. It also says which instruments the user switched off in the page: their notes are silent, and .midi() code newly aimed at them is refused until the user switches them on.
| Name | Required | Description | Default |
|---|---|---|---|
| instrument | No | An instrument id from instruments.json, to list its sounds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=true supplied, the description carries the behavioral burden and does so richly: it lists the returned facts, explains conditional sound-list and drum-map behavior, and notes enforcement such as silent notes and refused .midi() code for switched-off instruments.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening trigger is front-loaded, but the description is a single sprawling block with long sentences covering settings, drum maps, sound selection, and disabled instruments. The information is mostly useful, yet it is not concise or easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values and conditional behavior; it does so extensively. For a one-parameter read-only getter, the definition leaves no material gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, but the description adds real meaning: it says instrument must be an id from the listed instruments and explains that setting it expands the result to full sound lists, program numbers, banks, engines, and drum maps. This is substantially more than the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: it lists the MIDI instruments the user described in instruments.json and enumerates the facts returned. It also distinguishes itself from search_midi_sounds and get_strudel_reference by naming those siblings in the relevant conditional contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger: call it before writing MIDI code when the user has described their instruments. It also explains what passing instrument does, but it stops short of explicit when-not-to-use guidance or a crisp decision rule against every sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Strudel reference for @strudel/repl 1.3.0, the version the Moontide page loads: facts about what exists and how to write it, not what to choose. Topics: tidal-differences, mini-notation, functions, effects, sounds, theory, transitions, structure, midi, settings, motif. Call it without a topic for the index. Strudel is JavaScript, not TidalCycles: read tidal-differences before writing Strudel from Tidal habits.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | One topic to return; omit it to get the index of topics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, and the description adds meaningful context beyond that: version pinning to what the page actually loads, the descriptive-not-prescriptive nature of the content, and the index behavior when the topic is omitted. It stops short of saying what format the reference comes back in.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the version and purpose, then topics, then usage. Dense but each clause carries information; the topic enumeration is the only part that arguably repeats the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only lookup tool with no output schema, the description covers scope, versioning, content nature, and index behavior. The only gap is the shape of the returned reference (e.g., markdown vs structured), which an agent must discover by calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the enum fully enumerates topics, so the topic list in the description largely duplicates structured data. The one added nuance, that omitting topic returns an index, is also restated in the schema description, leaving the description with little net new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (returns the Strudel reference), pins the exact version (@strudel/repl 1.3.0) and the runtime context (the Moontide page), and clarifies the content type ('facts about what exists and how to write it, not what to choose'). No sibling tool competes with this purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete calling rule ('call it without a topic for the index') and a conditional prerequisite ('read tidal-differences before writing Strudel from Tidal habits'). It doesn't name alternatives, but none of the siblings overlap, so there is little to route against.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the versions of the music that played, newest first, one per row: "#id — time (UTC) — origin — "label" — first line of code". Ids never change. Rows without "#" mark where a Claude session started. The newest version row is usually what plays now; "the previous version" is the next version row down, "3 changes ago" is three version rows below the newest. Pass limit to see more than 20. Pass filter to find a version by a word from its label, code or favorite name; pass favorites: true to list favorites.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many versions to list, newest first (default 20) | |
| filter | No | Only versions whose label, code or favorite name contains this text (case-insensitive) | |
| favorites | No | true to list only favorites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses row structure, UTC timestamps, stable ids, session-start marker rows, and relative version positions. These details materially help an agent interpret results and navigate history correctly. The description adds substantial behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and row format, then moves to interpretation rules and parameter usage. It is dense but each sentence contributes useful information. Slightly more structure could improve readability, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description explains the return rows, ordering, id stability, session markers, and relative version semantics. It also covers all three optional parameters. An agent has enough information to call and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents limit, filter, and favorites in detail. The description reinforces parameter usage in natural language, such as seeing more than 20 rows and searching by label, code, or favorite name. It adds little meaning beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: lists versions of the music that played, newest first. It also defines the row format and distinguishes the history listing from getting current code or restoring a version. An agent can identify the tool's scope without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how to use the listing for version navigation, such as interpreting the newest row as what usually plays now and the next row as the previous version. It also explains how to use limit, filter, and favorites. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plays a past version again, by its id from list_history, in one call: it takes over within a fraction of a second without stopping the music, with the same checks as set_code. The restore is added to the history as a new version ("restored from #id"); nothing is rewritten. Returns the code as confirmed by the page. A restore always takes over at once and replaces a change that waits for a bar or phrase line. The old version replaces the music at once; when the user asked for gradual changes this session, bring it in with set_code and a transition instead. Like set_code, it starts Moontide first when it is not started yet, but only for an id that exists in the history.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Version id from list_history, for example 41 for #41 | |
| answering | No | The id of the page request this change answers, from its request line; the page shows that request as applied only when the change names it here |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: immediate takeover without stopping playback, non-destructive history append ("restored from #id", nothing rewritten), replacement of a pending bar/phrase-line change, Moontide auto-start only for ids that exist, and the return value being the page-confirmed code. These are exactly the mutation semantics an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the key routing rule, and most sentences carry distinct information. There is mild redundancy around immediate takeover ("within a fraction of a second", "always takes over at once", "replaces the music at once") that could be consolidated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with no annotations and no output schema, the description covers safety (non-destructive history append), timing (instant takeover), side effects (replaces pending queued changes, may start Moontide), and the return value. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, including the answering request-line field. The description reinforces the id's origin and adds the constraint that the id must exist in history, but adds little beyond the schema text, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — plays a past version again by its id from list_history — and makes the boundary with set_code and list_history explicit. An agent can distinguish this from edit_code, set_code, and favorite_version without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-not: if the user asked for gradual changes this session, use set_code with a transition instead. It also names list_history as the source of the id and notes the shared checks with set_code, so the routing decision is fully determined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves a sound catalog that you drafted from a sound list the user gave you (for example the maker's PDF list), into the user's Moontide data folder (catalogs/.json), never into Moontide itself. The catalog extends the model named by model. Send the sounds grouped as the list prints them, at most 500 per call: the first call starts the draft (source, programNumbering, and overwrite when it replaces a catalog), later calls add parts with append: true, with more: true while parts remain. The last part checks the whole draft and returns a summary that shows three sounds with their program as sent and as numbered from 1, and saves nothing. Show that summary to the user, then call again with model and confirmed: true, and nothing else, only after they say yes. The draft lives only in this session; a restart of the server loses it. For a model whose rhythm channels take a bank, a group of drum kits takes role: rhythm and may give noteMap; its kits are saved in the catalog's kits list.
| Name | Required | Description | Default |
|---|---|---|---|
| more | No | true while more parts remain; absent or false on the last part | |
| banks | No | The sounds of this part, grouped by bank and category; at most 500 sounds in the call | |
| model | Yes | The id of the model the catalog extends: a model Moontide ships or one saved with save_midi_model | |
| append | No | true to add this part to the draft of the model; absent or false starts a new draft | |
| source | No | The document title and version the list comes from; required when a draft starts | |
| confirmed | No | true only after the user said yes to the summary; send it with model and nothing else | |
| overwrite | No | true to replace an existing catalog of the model; read when a draft starts | |
| programNumbering | No | How the list numbers programs: from-1 when the first program is printed as 1; required when a draft starts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the key traits: the draft is session-scoped and lost on a server restart, the summary call saves nothing, and overwrite replaces an existing catalog. It does not say what happens on invalid or rejected input (e.g., whether the check reports errors or how failures surface), leaving a modest gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and then sequenced in call order, and nearly every sentence carries workflow information with little repetition. It is one dense paragraph, though, and the final sentence about rhythm channels and noteMap reads awkwardly, making the multi-step protocol harder to scan than a stepwise layout would.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a complex 8-parameter, multi-call tool with no output schema: it explains the session-limited draft, the confirmation gate, overwrite behavior, and the shape of the returned summary (three sounds with program as sent and as numbered from 1). Error/validation behavior and what 'extends the model' implies in the saved file are the remaining unstated details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so per-parameter meanings are already documented; the description adds cross-parameter workflow semantics instead — source/programNumbering/overwrite are read when a draft starts, append continues it, more marks remaining parts, and confirmed must be sent with model and nothing else. It adds little on the bank/role/noteMap nested structure beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it saves a sound catalog drafted from a user-supplied sound list into catalogs/<model id>.json, explicitly 'never into Moontide itself'. The resource specificity (catalog file vs. model) lets an agent separate it from save_midi_model and the search/list siblings without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit multi-call protocol: first call starts the draft (source, programNumbering, overwrite), later calls use append: true with more: true while parts remain, the last part only checks and returns a summary, and a final call with model plus confirmed: true is made 'only after they say yes'. It also states the grouping constraint (as the list prints them, at most 500 per call) and the rhythm/noteMap case for drum-kit groups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves an instrument model that you drafted from a page of the instrument's manual the user pasted, into the user's Moontide data folder (models/.json), never into Moontide itself. First call it with confirmed: false: it checks the model and returns a summary (channels, sounds with their program numbers as sent and as numbered in a manual from 1, controls, reset bytes, notes) and saves nothing. Show that summary to the user, and call it again with the same model and confirmed: true only after they say yes. It refuses an id of a model Moontide ships, and an existing model unless overwrite is true. Fields: id (lowercase letters, digits, dashes or underscores, at most 32), name, channels { melodic, rhythm } (lists of channels 1-16), bankSelect (none, msb or msb-lsb), rhythmBank (optional: true when the instrument chooses drum kits by bank select and program change; every rhythm sound then needs a bank), drumMaps (optional, at most 8: [{ id, name, notes: [{ note 0-127, name }] }] typed from the instrument's manual), drumMap (optional: the id of the map of kits without their own; general-midi is built in), a rhythm sound's noteMap (optional: a map id, or null when no map is known for that kit), defaultVolume (0-127), clock (optional: true when the instrument follows MIDI clock, so Moontide sends it the clock, Start and Stop), monophonic (optional: true when the instrument plays one note at a time), reset (optional: sysex with at most 4 messages, each { kind: roland-dt1, model, address, data } as hex bytes or { kind: raw, bytes } from F0 to F7 and at most 32 bytes, and waitMs), controls ([{ id, name, cc, min, max, default }]), sounds { melodic, rhythm } ([{ name, program 0-127 as sent, bank { msb, lsb } when the instrument needs one }]) and notes (facts about the instrument, at most 10).
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | The drafted model, as a JSON object | |
| confirmed | Yes | false to check and summarize without saving; true only after the user said yes to the summary | |
| overwrite | No | true to replace an existing user model with the same id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so: it discloses the dry-run behavior ('saves nothing'), the exact contents of the check summary (channels, sounds, program numbers, controls, reset bytes, notes), and the refusal conditions. Overwrite semantics and the user-confirmation gate are spelled out, which is exactly what an agent needs before a write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loading is good — workflow first, field inventory second — and every clause carries real constraint information. However, the field list is a single run-on enumeration that would be far more scannable as a bulleted or structured block, making it easy to mis-parse nested optional fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex nested write tool with no annotations and no output schema, the description covers the confirmation loop, refusal cases, return-summary contents, and all field constraints. An agent has enough to call this correctly on the first try.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the three top-level params, but the 'model' parameter is an open object with no internal schema, so the description is the only source of the field structure. It documents id format and length, channel ranges, bankSelect/rhythmBank/drumMaps rules, reset sysex limits, and program ranges; the density makes some nesting (drumMaps vs drumMap, noteMap) harder to parse than ideal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Saves an instrument model... into the user's Moontide data folder (models/<id>.json)') and explicitly scopes it away from Moontide itself, which separates it from the sibling save_midi_catalog by resource and destination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Prescribes an exact two-step workflow: call with confirmed: false first, show the returned summary to the user, then re-call with confirmed: true only after they approve. It also names the refusal cases (shipped ids, existing models without overwrite), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches the sound catalog of one instrument: a list of the model's sounds kept in the user's data folder, built from a patch-name file or a sound list the user owns. It finds sounds by words in the name or the category, in any order, with case and spaces ignored. It returns at most 25 matches: the exact name first, then names that start with the words, then names that contain them, then matches in the category only. Each match gives the name as the sound option of .midi() takes it, the program as sent (0-127), the bank when there is one, the category and, for an instrument whose model declares engines, the engine of the sound or that it is in no engine. It says how many more matched. A drum kit is marked (drum kit) and gives its drum map, or says the map is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Words to find in the sound name or its category, in any order; case and spaces do not matter | |
| category | No | Only sounds of this category; case and spaces do not matter | |
| instrument | Yes | An instrument id from instruments.json whose model has a sound catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, so the description carries the behavioral burden and does so thoroughly: a hard cap of 25 matches, an explicit ranking order (exact, prefix, contains, category-only), a note that remaining matches are counted, and special drum-kit handling including an "unknown map" state. This is far beyond what the annotation supplies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and no sentence is filler, but several sentences are dense run-ons that pack ranking, return fields, and drum-kit caveats into one breath. Slightly tighter phrasing would improve scannability without losing content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must describe return values itself, and it does: name as .midi() takes it, program 0-127, bank when present, category, engine or no-engine, plus the drum-kit marker and map status. Nothing an agent needs to call or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already states that query and category ignore case and spaces and that instrument must be an id from instruments.json with a sound catalog. The description largely restates those semantics rather than adding new meaning, and it does not clarify how query and category interact when both are supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: "Searches the sound catalog of one instrument," and clarifies the catalog's origin (patch-name file or user-owned sound list). It never names a sibling tool, so an agent must infer the boundary with get_midi_instruments and save_midi_catalog on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Use is implied — finding a sound by words in name or category for one instrument — but there is no explicit when-to-use statement, no exclusion, and no pointer to the sibling that lists instruments or builds the catalog. The one contextual clause about how the catalog is populated helps an agent understand prerequisites but does not route it among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces the music in the Moontide page with new Strudel code; the new pattern takes over within a fraction of a second, mid-cycle, without stopping the music. To change part of an existing piece, edit_code sends only the change; set_code is for a new piece or a rewrite of most of its lines. With at: 'bar' or at: 'phrase' the code is checked at once and takes over on the next bar line or the next phrase line instead (a bar is one cycle of 4 beats; a phrase is 4 cycles, or phraseCycles, counted from Play); the reply gives the cycle and about how many seconds, a newer change replaces a waiting one, and Stop cancels it. When the tempo changes, the reply gives it in BPM. Every call runs the whole program again, so a getTime() anchor restarts at each change; a transition that must keep running takes .timeline(id), which keeps its anchor as long as the code keeps the same id (see the transitions topic). Double-quoted and backtick strings are parsed as mini-notation wherever they appear, helpers included, while single-quoted strings stay plain JavaScript (see the tidal-differences topic). When Moontide is not started yet, set_code starts it first: its page opens in a new browser tab and the call waits up to 30 seconds for that page to connect. Before changing existing music, call get_code and build on what it returns, including hand edits. Keep what the user said matters; if a small request needs a full rewrite and the user said what matters, ask first, otherwise rewrite and say so. When a request is vague, act on your own reading of it instead of asking first. Returns the code as confirmed by the page. Pass a short label saying what changed; every version that plays is kept in the history. Then tell the user in one line what you chose: the musical terms, plus a short image in plain words.
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | When the change takes over: 'now' (the default) within a fraction of a second, 'bar' on the next bar line, 'phrase' on the next phrase line (4 cycles, counted from Play). The code is checked at once; the reply says the cycle and about how many seconds away it is. | |
| code | Yes | Complete Strudel code to play | |
| label | No | A few words saying what this change is, for example "added a bass"; shown by list_history | |
| answering | No | The id of the page request this change answers, from its request line; the page shows that request as applied only when the change names it here | |
| glideBars | No | Whole bars, 1 to 64, to move the tempo smoothly from the tempo that plays to the one this code sets with setcps or setcpm; with at, it starts at the line. Refused when nothing plays, no tempo is set or it already plays. Stop, or code with another tempo or none, cancels it | |
| phraseCycles | No | How many cycles one phrase lasts, for at: 'phrase' (2 to 64, default 4) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden and largely does: takeover latency ('within a fraction of a second, mid-cycle'), deferred takeover semantics for at, waiting-change replacement and cancellation by Stop, a 30-second wait when Moontide is not started, restart of getTime() anchors on every call, and history retention per played version. The gaps are minor rather than structural — error/failure modes beyond the 'refused' case for glideBars are not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the edit_code contrast are front-loaded, which is correct, but the body is one very long compound paragraph in which timing behavior, string-parsing rules, startup waiting, edit policy, history, and user-facing response style are all run together. The sentences are individually dense and several pack two or three distinct facts separated by semicolons, which raises reread cost; the editing-policy sentence ('Keep what the user said matters...') is agent instruction that sits awkwardly beside mechanical tool behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter mutation tool with no annotations and no output schema, the description covers what an agent needs to call it correctly: when it fires, what it returns ('the code as confirmed by the page', the cycle and rough seconds, BPM on tempo change), what the label and history do, and the prerequisite of reading get_code first. Return-value and prerequisite knowledge that would otherwise be missing is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining cross-parameter behavior the schema does not: that 'bar'/'phrase' validate the code immediately but defer takeover, that phrase length is 4 cycles or phraseCycles counted from Play, and that glideBars starts at the deferral line and is cancelled by Stop or a tempo-less rewrite. It still leaves 'answering' and 'label' almost entirely to the schema, so it stops short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Replaces the music in the Moontide page with new Strudel code', and immediately names the sibling it is not ('edit_code sends only the change; set_code is for a new piece or a rewrite of most of its lines'). An agent can distinguish it from edit_code and get_code without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing rules against alternatives (edit_code for partial edits, get_code before altering existing music), plus decision rules for ambiguous cases: ask first when a full rewrite would override what the user said matters, otherwise rewrite and say so, and act on your own reading when the request is vague. When-not-to-use conditions are stated, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switches how requests the user types in the Moontide page reach you. State on returns the command to run now with your Monitor tool, so each request arrives as soon as it is sent. State off says how to stop that monitor, after which requests wait on the Moontide server and arrive in the reply of your next other Moontide tool. Call it when the user asks, in any words, to turn page requests on or off, to take requests from the Moontide page right away, or to stop. The page-requests-on and page-requests-off prompts do the same where the client offers MCP prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | on to receive each page request right away, off to let them wait for the reply of your next other Moontide tool |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare idempotentHint and destructiveHint, so the description carries the real behavioral burden, and it does: 'on' means the agent must run a monitor command so requests arrive immediately, 'off' means the monitor is stopped and requests then queue on the Moontide server until the next Moontide tool call. That downstream consequence for other tools is exactly the kind of context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the effect of each state before the when-to-call guidance, and every sentence contributes something (state semantics, trigger conditions, prompt alternative). Sentences are dense and long, so the text is heavier than strictly necessary, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required enum parameter, no output schema, and only idempotency/non-destructiveness annotations, the description covers everything an agent needs: what each state does, how the monitor is started and stopped, where queued requests surface, and when to invoke it. Nothing material is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the enum values are already documented in the schema, so the baseline is 3. The description adds workflow-level meaning beyond the schema — what actually happens to the agent and the server in each state — which makes the choice between 'on' and 'off' operationally meaningful rather than just a label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it switches how requests typed on the Moontide page reach the agent, and it spells out both 'on' and 'off' modes concretely (run the Monitor tool now vs. requests wait and arrive in the next tool reply). That is far more specific than a restatement of the name, though the opening 'Switches how requests ... reach you' is slightly abstract until the following sentences clarify it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('Call it when the user asks, in any words, to turn page requests on or off, to take requests from the Moontide page right away, or to stop'), which covers phrasing variation an agent will actually encounter. It also names the alternative path — the page-requests-on and page-requests-off MCP prompts — so the agent knows a sibling mechanism exists when the client offers prompts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts Moontide: its web server on this computer and its page, which opens in a new browser tab; one click in that tab turns the sound on. Call it when the user asks, in any words, to start or open Moontide, or asks which tab or port is yours. Calling it again is safe: it gives the page address, the port and the tab title, and opens a new tab only when no page is connected. set_code starts Moontide by itself, and so does restore_version for a version that exists, so there is no need to call it before them. edit_code changes music that already plays and starts nothing. The start prompt does the same where the client offers MCP prompts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply idempotentHint and destructiveHint, but the description goes further: it explains what repeat calls return (page address, port, tab title) and the precise condition under which a new tab appears (only when no page is connected). It also discloses the browser-tab side effect and the manual sound-enable step, which annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first clause and every subsequent sentence carries distinct routing or behavioral information. It is slightly dense, with long semicolon-linked sentences, but no sentence is pure filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the returned values (address, port, tab title) and the observable side effects. Combined with the alternative-route guidance, an agent has everything needed to call it correctly or skip it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and object — starting Moontide, meaning its local web server plus a page in a new browser tab — and clarifies the follow-up interaction (one click to enable sound). It is clearly distinguishable from siblings like set_code and edit_code, which are named and contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit trigger conditions ('when the user asks, in any words, to start or open Moontide, or asks which tab or port is yours') and explicitly removes redundant calls: set_code and restore_version already start it, edit_code does not, and the start prompt is an equivalent path. This is a full when/when-not/alternatives map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stops all sound in the Moontide page right away, even when the current code is broken. The code stays in the editor; get_code still returns it, and the next set_code starts playing again. Before Moontide is started it says so and starts nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare idempotentHint and destructiveHint=false; the description adds real behavior beyond that — it works even with broken code, the editor contents survive, get_code still returns them, and a later set_code resumes playback. It also discloses the pre-start no-op with a message, which is exactly the kind of edge-case behavior an agent cannot infer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what it does, followed by state-aftermath and the pre-start edge case. Every sentence carries distinct information; nothing is repeated from the name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, non-destructive, idempotent toggle with no output schema, the description covers the only things an agent needs: what is stopped, what survives, how to resume, and what happens if the page was never started.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly avoids inventing argument-like details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Stops all sound in the Moontide page') with scope qualifiers ('right away, even when the current code is broken'). The sibling set includes 'start', and the name/description pair makes the complementary relationship unmistakable without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly frames the tool as the inverse of 'start' and gives a concrete precondition case: before Moontide is started it reports that and starts nothing, so the agent knows calling it pre-start is harmless. It never explicitly names 'start' or 'set_code' as alternatives for other intents, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0answer_requestedit_codefavorite_versionget_codeget_midi_instrumentsget_strudel_referencelist_historyrestore_versionsave_midi_catalogsave_midi_modelsearch_midi_soundsset_codeset_page_requestsstartstopScored across 15 tools
Most tools target clearly different actions or resources, and the descriptions carefully separate set_code, edit_code, and restore_version. Minor overlap exists between search_midi_sounds and get_midi_instruments (which can also list sounds), but the distinction between search and full instrument listing is explained.
The set is overwhelmingly consistent verb_noun snake_case: get_code, set_code, edit_code, list_history, restore_version, save_midi_model, and so on. The bare verbs start and stop are the only notable deviations.
Fifteen tools is well within a reasonable range for a live-coding music environment with playback, code editing, history, MIDI, and page-request concerns. Each tool maps to a distinct workflow rather than being redundant.
The surface covers the core lifecycle: start/stop, read/edit/set code, reference lookup, history browsing, favorites, restore, MIDI instrument/catalog/model management, and page requests. Minor gaps remain, such as removing a favorite or deleting saved models/catalogs, but these are workable limitations rather than dead ends.
ABC sheet music + Strudel live coding: songs, videos and live jam sessions in ext-apps widgets.
Build & publish sites — or a game, a calendar, a report — by chatting with Claude. Live in seconds.
Browser DAW for AI assistants: build multitrack songs with MIDI, effects, stems and generation.
Autonomous music production for AI agents with MIDI generation, QC and provenance.