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

Annotations already declare non-destructive, idempotent, closed-world mutation, so the safety profile is carried structurally. The description adds the key ambiguity it should resolve but doesn't: whether the whole group is dissolved or only this clip detaches, and what happens if the clip isn't linked. Pointing to 'the server instructions' for the return value is a deferral rather than disclosure.

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 short sentences with the action front-loaded and zero filler. The parenthetical pointer to server instructions is the only soft spot, trading brevity for a cross-reference the agent has to chase.

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?

An output schema exists and annotations cover safety, so the remaining burden is small but real: the scope of the break (single clip vs. entire group) and the no-op/error case for an unlinked clip are unaddressed. For a state-mutating timeline tool, those are the questions an agent most needs answered.

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?

At 67% schema coverage, the schema documents preview (with enum meanings) and timeline_id (the new-handle semantics), while clip_id has no description at all. The description only implies clip_id via 'a clip belongs to' and says nothing about preview, so it neither compensates for the gap nor adds meaning beyond 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?

States a concrete verb and object ('Break the link group a clip belongs to'), which an agent can map cleanly against sibling clip.link as its inverse. It stops short of naming the sibling explicitly, so it is clear but not fully differentiated in text.

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?

No when-to-use or when-not-to-use guidance. Nothing tells the agent how this differs in practice from clip.remove (which likely also detaches a clip) or that it should be used only when the clip is actually part of a link group.

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