Live Midi Clock In

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

With no annotations provided, the description carries the full behavioral burden and does so: it discloses tempo-filter latency math (about 0.215/bandwidth_hz s, 430 ms default), the tempo-change cadence and tolerance gates (step_beats, tempo_tol_bpm, phase_tol_ms, max_bend_pct), dropout behavior (holds last tempo at 300 ms), and hard refusals (clock in and out on one port is refused; live_tempo refused while on). It even declares unsupported behavior (their meter is assumed, Start/Stop is not forwarded to clock out).

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 routing are correctly front-loaded, and nearly every clause carries real information. However, the body is a dense, run-on block of roughly 350 words that mixes parameter semantics, transport state machine, latency math and limitations without paragraph or label structure, which makes it hard to scan and pushes key defaults deep into the text.

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 an 11-parameter sync tool this is essentially complete: the interaction with live_tempo, the clock-out collision refusal, the no-source fallback ('the inputs and the follow; live_status shows it too'), and the explicit not-yet list are all covered. Return values need not be explained since an output schema exists.

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 0% across 11 parameters, so the description must compensate, and it does for ten of them: source resolution rules, offset_ms sign convention and -500 to 2000 range plus tuning advice, transport's two modes and their exact consequences, dropout_ms, step_beats, bandwidth_hz with its tradeoff, max_bend_pct, phase_tol_ms and tempo_tol_bpm with defaults. Only 'project' (the required parameter) is left unexplained, which is the sole gap.

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 first sentence names the specific verb and resource: the set follows another app's MIDI clock in, and the external app sets tempo, beat, and (with transport='follow') Start/Stop/Continue. It explicitly distinguishes the inverse case ('the other way round, the set leading: live_midi_clock'), so an agent can separate it from live_midi_clock, live_midi_timecode_in and live_link 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?

Use conditions are stated in plain trigger language ('follow, sync to or slave to an external clock', 'my drum machine or my DAW') plus explicit exclusions routed to siblings: video/timecode goes to live_midi_timecode_in, Ableton Link to live_link. It also states the conflict rule that live_tempo is refused while this is on, and that 'on=False lets go (the tempo holds)'.

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