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

Annotations declare destructiveHint=true and idempotentHint=false; the description goes beyond them by explaining that 'zurueckholen' saves the cut it replaces (so it is undoable), that named states are never cleaned up while unnamed ones are capped, and that branching creates a standalone sequence with no merge-back. It does not, however, explain return formats or failure/permission conditions, so it is strong but not exhaustive.

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 triggering condition is front-loaded, but the rest is a dense run-on paragraph that interleaves purpose, five action behaviors, and cross-tool notes into one block. Most sentences carry information, yet the wall-of-text format and mixed German/English make it harder to scan than it needs to be for a multi-action tool.

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?

With no output schema, the description must describe returns, and it does: 'liste' returns saved states newest-first with marke, ursprung and abgezweigt, and 'vergleichen' returns clip-by-clip differences. Combined with per-action guidance and mutation semantics, it is complete for a 6-parameter, 5-mode tool.

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 baseline is 3, but the prose adds meaning beyond the schema: it maps each aktion to the parameters it needs (checkpoint_id required for markieren/vergleichen/zurueckholen, optional for abzweigen), explains that empty marke removes a name, and clarifies the gegen target. This goes past the schema's own field notes.

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 states a specific resource (the saved states / versions of ONE cut) and covers every action it performs, while explicitly distinguishing itself from lab_timeline_apply and the editor/Resolve bridge that generate the states it reads. An agent can tell it apart from timeline-editing siblings without opening the 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 opens with an explicit 'Use when' clause listing the triggering intents (recall earlier states, revert, compare, name, branch a second cut), and names the alternative editing path (lab_timeline_apply). When-to-use and the routing to the sibling are both stated.

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