remove_anim_sync_marker

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

Annotations cover the safety profile (destructiveHint=true, readOnlyHint=false), but the description adds substantial context beyond them: it runs in an undo transaction, saves the package, returns before/after counts, treats a missing marker as a successful no-op with nothing saved, and reports save failure via success=false with saved=false and save_error. That is rich, call-relevant detail an agent cannot infer from annotations alone.

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 core action and its transactional/save behavior are front-loaded in the first sentence with no wasted words. The full return object is then repeated at the end, which is slightly redundant since the same field names were already enumerated, but it remains a compact, readable structure.

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 present, the description fully documents the return fields (sequence_path, marker_name, markers_before, markers_after, removed, saved, save_error) and the success/partial-failure semantics. Combined with the annotations covering destructiveness, an agent has everything needed to call and interpret this tool correctly.

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 100%, with both parameters self-documenting ('Name of the marker to remove.', 'Asset path of the UAnimSequence.'). The description reinforces that marker_name matches by name and sequence_path is a UAnimSequence, but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 names a precise verb and resource ('Remove every authored sync marker ... from a UAnimSequence') with clear scope ('with the given name'). It clearly distinguishes itself from the obvious sibling add_anim_sync_marker and from other remove_anim_* tools by naming the exact target (sync markers, not curves/notifies/tracks).

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?

Usage is implied by the action and the edge-case clause ('no marker with that name is a success with removed=false'), which helps an agent anticipate no-op outcomes. However, no alternative tool is named (e.g. add_anim_sync_marker for the inverse) and no preconditions about the asset state are stated, so guidance remains implicit.

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