cw_midi_note

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It usefully discloses latency ('millisecond latency') and that the CakeScript layer is bypassed, plus the record-armed write side effect — real value beyond a bare schema. But it omits whether the MIDI port must first be enabled (siblings cw_enable_midi_port / cw_midi_panic suggest a port lifecycle), whether the note is auto-released after durationMs, and whether output is anything at all.

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, front-loaded sentences: action first, then use case, then a behavioral note. Nothing is padded, though the fragment style ('millisecond latency; no CakeScript involved.') is terse to the point of needing interpretation.

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 4-parameter, no-annotation, no-output-schema tool this is only partially sufficient: purpose and use case are covered, but port-enablement prerequisites, return behavior, and the semantics of three parameters are missing. An agent could invoke it but might do so before the port is open or with wrong velocity/channel assumptions.

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 only 25% — only pitch is documented, and channel and velocity have no descriptions anywhere. The description adds nothing about velocity, channel routing, or how durationMs controls note-off, so the undocumented parameters remain opaque to an agent.

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 — 'Play a note on the live MIDI port' — which is precise enough to separate it from cw_midi_chord and cw_midi_cc by implication (singular note vs chord / controller data). It never names a sibling explicitly, so differentiation is inferred rather than stated.

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 this to audition or to write into a record-armed track' gives concrete when-to-use contexts, including the important prerequisite that a track must be record-armed for the write case to apply. No when-not conditions or named alternatives (e.g., cw_midi_chord for multi-note, cw_midi_send for raw messages) are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.