markers_clear

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

With no annotations, the description carries the full behavioral burden. It does disclose that this is a destructive delete operation and mentions scope, but it leaves critical behavior ambiguous: whether at least one filter is required, whether multiple filters combine as OR/AND, and what happens when no filter is provided. For a deletion tool, this is a significant transparency gap.

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 description is two short sentences with no filler, front-loading the action and then compactly presenting scope options. Every word earns its place, and the terse structure helps an agent parse the core behavior quickly.

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?

Given no annotations, six parameters, and a destructive operation, the description is not complete enough. It omits how media_id and unique_id relate to item/clip scopes, does not clarify behavior with no filters, and does not state whether the filters are mutually exclusive or combinable. The output schema may cover return values, but call-shaping behavior is under-specified.

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. It adds meaning to id ('payload id'), color, frame, and scope with its default and allowed values, but it does not explain media_id or unique_id at all. The description partially compensates for the schema gap but not fully.

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 delete operation on markers with clear filter dimensions (payload id, frame, or color) and scope options. This clearly distinguishes it from sibling tools like markers_query or marker_upsert, even though no sibling is named.

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 description implies when to use the tool: when markers need to be deleted by id, frame, or color, with timeline as the default scope. However, it does not explicitly state when not to use it or name alternatives such as markers_query or marker_upsert, so the routing guidance is only implicit.

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