add_clip_marker

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

No annotations, so the description carries the full burden. It says where the marker lands (source media) but omits the important consequences: that a source-media marker may appear on every clip referencing that media, what happens when time falls outside the clip, and whether anything is returned or fails silently.

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?

One sentence, front-loaded with the verb and the key scope distinction, with zero filler. It is tight but arguably under-packed for a 7-parameter mutation 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?

A mutation tool with 7 parameters, no annotations, and no output schema is described in a single sentence. An agent still lacks the source-vs-timeline marker distinction spelled out, error behavior, and any note on the optional metadata fields.

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 57%; the description reinforces the time parameter with the 'inside the clip' constraint, which is real added meaning beyond 'Sequence time, seconds'. It says nothing about name, color, or comment, which are undocumented in both places.

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?

Specific verb (add) plus a precise resource: a marker on a clip's *source media* at a sequence time inside the clip. The 'source media' phrasing implicitly separates it from add_marker, add_markers, and add_project_item_marker, though it never names those siblings.

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?

The phrase 'at a sequence time inside the clip' implies a precondition (the time must fall within the clip's bounds), but there is no explicit when-to-use guidance and no routing to add_marker / add_project_item_marker when a timeline- or project-level marker is wanted.

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