set_cel_position

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

The description lacks behavioral details beyond the basic action. It does not disclose that the tool can create cels if create_if_missing is true, or that it can copy from another frame via source_frame_index. With no annotations, the description should explain these side effects and requirements.

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 concise with a clear front-loaded sentence. The Args section lists parameters but is somewhat verbose; however, it is structured and readable. It could be more concise by integrating parameter details into prose.

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 7 parameters (5 required) and no output schema, the description should explain return values, prerequisites (e.g., file must exist), and overall effect. It only states 'set a cel's position', leaving many contextual gaps.

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 add meaning. It provides minimal explanations (e.g., 'in pixels', 'starting at 1'), which is baseline but not comprehensive. Key parameters like create_if_missing and source_frame_index are only listed without elaboration.

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 starts with 'Set a cel's position in a specific layer and frame,' which clearly specifies the verb (Set), resource (cel's position), and scope. This distinguishes it from sibling tools like create_cel, copy_cel, and offset_cel_positions.

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 guidance is provided on when to use this tool versus alternatives. For example, it does not mention when to use set_cel_position vs tween_cel_positions or offset_cel_positions. There are no when-to-use or when-not-to-use directives.

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