live_events

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

With no annotations, the description carries the full burden, and it does disclose two genuinely useful traits: edits are a single undoable unit ("one live_undo reverts the whole edit") and copy mutates the clipboard ("uses the clipboard"). It does not say what happens when an event number is invalid, whether editing affects live playback, or what any action returns. Useful but incomplete for a mutation tool with zero annotation coverage.

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 resource definition is front-loaded and each action is a compact labelled clause, so an agent can scan to the relevant line. The brace shorthand ("edit {event, and any of: ...}") is efficient but verges on telegraphic and would be harder to parse than plain sentences. Almost no wasted words overall.

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 10-parameter tool with no annotations and no output schema, the definition covers the list output shape (ordering, start/end in seconds, gain and fade for audio) and the mutate semantics reasonably well. It omits which parameters are required per action (edit/duplicate/copy all need event; duplicate needs times), what non-list actions return, and any error behavior. Adequate but with clear gaps given the tool's complexity.

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 only 20%, so the description has to compensate, and it largely does: to is a new start, to_track moves the event, gain_db sets while add_gain_db is relative, fade_in/fade_out are audio-only seconds, times is a repeat count placed right after the original, and event is a number from list or a name. The position format (seconds or bars like "9.1.1.0") is restated. Only the required `track` and the conditional requirement of event/times per action are left unaddressed.

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 opens with a concrete verb+resource ("One event (audio clip or instrument part) on a track in the running Studio One") and then enumerates the four operations it multiplexes: list, edit, duplicate, copy. An agent can immediately tell this is the per-event tool rather than a track or song tool. It stops short of naming or contrasting the near-identical siblings live_edit_events and live_select_events, so differentiation is left to inference.

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?

Each action gets a one-line gloss ("list: the track's events...", "edit {...}: one live_undo reverts...", "copy {...}: pastes a copy at a position"), which implies when each is appropriate. However, there is no explicit guidance on which of these actions to prefer over live_edit_events or live_select_events, nor any stated prerequisites or failure conditions. Usage is implied rather than prescribed.

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