live_mix_snapshot

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

With no annotations supplied, the description carries the full burden and does substantial work: it discloses the captured state, the explicit exclusions, that restore applies a partial/differential update ('sets only what differs'), and the undo interaction caveat. The remaining gap is name-collision behavior on save and whether snapshots persist for the life of the project, which matter for a state-capturing 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?

The core action and its scope are front-loaded in the first sentence, followed by three short sentences that each add one distinct fact (differential restore, exclusions, undo caveat). No filler and no restatement of the tool name.

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 annotations and no output schema, the description covers capture scope, exclusions, restore semantics, and the undo relationship. What 'list' returns (names only, or names with timestamps) is left unspecified, which is the one thing an agent must guess before calling with action='list'.

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 0%, so the description must compensate for both parameters. It conveys the three action values through their verb phrases and implies 'name' is the snapshot label for save, but it never says that 'name' is required for save and restore yet ignored for list, leaving the enum/required interaction to inference from the schema.

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 names a specific verb set (save/restore/list) against a specific resource (the whole mix of the running song) and enumerates exactly what is captured: every channel's volume, pan, mute, solo, input monitoring, and each send's level and mute. This distinguishes it from live_plugin_snapshot (plugin-level) and live_save (session-level) without the agent needing to open 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?

It gives a concrete routing rule against a sibling: 'Mixer changes are not reverted by one live_undo; restore a snapshot instead,' which tells the agent when to pick this over live_undo. It also scopes out record-arm and automation mode, implying those belong to live_record_setup or live_set_automation, but it never states when to choose snapshotting over live_save or live_plugin_snapshot, so the alternative guidance is partial rather than exhaustive.

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