midi_fx_render

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

Adds real value beyond the annotations: a non-obvious side effect (the effect is bypassed after rendering unless bypass=false) and reversibility ('Undoable'). However it never says what happens to notes already present in to_slot (overwrite/merge), what happens when input_slot is omitted, or what preconditions exist, which matters for a write tool whose annotations claim destructiveHint=false.

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?

Two sentences, zero filler, front-loaded with the core operation and followed by clarifying examples and the bypass/undo caveats. The parentheticals are short and each carries information.

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?

Covers the mechanism, the side effect, and undo, which is solid. But for a 6-parameter mutation tool with no output schema, the agent is left guessing about destination-slot overwrite semantics, the effect of omitting optional input_slot, and required preconditions — gaps that could cause an unintended data loss.

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 all six parameters are documented; the description still earns credit by explaining the relationship the schema cannot — input_slot is the chord source feeding an Arpeggiator, to_slot is the destination clip, and bypass is the post-render toggle. It does not clarify the meaning of input_slot when omitted or the interaction between bars and clip length.

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 one MIDI FX slot offline over some bars and write what it played into a session slot as notes') and concretizes it with two worked examples distinguishing generative sources (Markov/L-System/Marbles, Arpeggiator) by their output clip type. That is enough for an agent to separate it from midi_fx_set_params, midi_fx_set_bypass and clips_write_midi 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?

Makes the use case clear: convert a live MIDI FX generation into an editable clip (vs. leaving it as a live effect). It even flags the parameter-level alternative inline ('bypass false keeps it on'), pointing at the behavior of midi_fx_set_bypass. It stops short of explicit when-not-to-use statements or prerequisites (e.g. must the destination slot be empty, must transport be stopped).

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