update_timeline

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the burden of explaining mutation semantics, and it does not. It never says whether the patch is merged with or replaces existing markers, segments, and events, which is the destructive question an agent most needs answered. It also omits the optimistic-concurrency behavior implied by expectedRevision and says nothing about permissions or error conditions.

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?

A single front-loaded sentence with no filler, and the enumeration is dense rather than padded. It is efficient, though the field list is a flat run-on that would read better grouped or paired with one sentence on patch behavior.

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?

This is a high-complexity mutation tool with a free-form nested patch object, no parameter descriptions, no output schema, and only the minimum annotations. Against that complexity the description leaves out merge-vs-replace semantics, revision conflict handling, and return/error behavior, which are exactly the gaps an agent cannot resolve elsewhere.

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% and the patch parameter is a free-form object with no nested schema, so the field enumeration in the description is the only documentation of what patch accepts — genuinely valuable. However, four of five parameters (timelineId, expectedRevision, sessionId, requestId) get no mention at all, and expectedRevision in particular needs meaning supplied from somewhere; nothing does that.

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 specific verb ('Set') and names the resource and the exact aspects being modified: duration, looping, pingPong, autoplay, work area, layer membership, markers, segments, events. This clearly separates it from siblings like create_timeline, delete_timeline, and clone_timeline. It stops short of naming update_composition or describe_timeline as alternatives, so it is clear but not fully differentiated.

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?

There is no guidance on when to reach for update_timeline versus update_composition, patch_object, or set_keyframes, nor any prerequisite or exclusion stated. The field list implies what it is for, but an agent must infer the boundary between this tool and the many other mutation siblings on the same list.

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