SpriteMCP

Overview Schema Source Related Servers Discussions Admin

build_frame_animation

Draft a single animation frame by applying hierarchical joint rotations to rigid body parts, using an approved animation plan and optional outfit layers.

Instructions

Draft one animation frame (0..7) with hierarchical joint rotations.

GATE: refuses if no valid plan.json exists for this character+animation. If painted design/outfit plan exists, also requires compose_character. Optional plan_id must match the locked plan from plan_animation.

NEVER call this until plan_animation succeeded AND you showed user_facing_summary to the user (and they OK'd). Jumping straight to rotations is forbidden (e.g. a sword clip must not reuse a fist-fight plan).

DRESSED FRAMES: when design/ layers exist, the draft includes outfit layers rigid-rotated with the same pivot transforms as their parent body parts (DRAW_ORDER, draw_after, overhang preserved). No design → base only. Result includes dressed=true and design_slots when clothes were composited.

Pose model: each body part is a RIGID full-canvas layer rotated about articulation pivots (parent joints rotate children) — not freehand redraw. Use get_joint_docs for which parts each joint rotates.

rotations example: {"hip_near": -20, "knee_near": 6, "hip_far": 18, "knee_far": 14}. Joints: neck, shoulder_far, shoulder_near, elbow_far, elbow_near, hip_far, hip_near, knee_far, knee_near. Angles are absolute degrees from rest. Does not finalize — call finish_frame_animation next. For +X-facing idle: negative hip ≈ forward, positive knee ≈ flexion. Optional output_dir overrides session output root.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes
`scale`	No
`plan_id`	No
`rotations`	No
`output_dir`	No
`frame_index`	Yes
`animation_name`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 25, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden, and it delivers: discloses the GATE refusal condition, the dressed-frame compositing behavior (rigid rotation with DRAW_ORDER/draw_after/overhang preserved), the rigid-pivot pose model (not freehand redraw), and the 'does not finalize' trait. This is rich behavioral disclosure well beyond the minimum.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but dense and organized with labeled sections (GATE, DRESSED FRAMES, Pose model). Almost every sentence carries new information. Minor redundancy: 'Does not finalize — call finish_frame_animation next' appears twice. For a tool this complex the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a 7-param, pipeline-dependent tool: purpose, prerequisites, parameter semantics, gate conditions, pose model, dressed-frame behavior, and next step are all covered. Since an output schema exists, return-value documentation isn't needed. Only scale and name/animation_name go lightly explained, but these are self-evident or defaulted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description fully compensates: provides a concrete rotations example, lists all 9 joints, explains 'Angles are absolute degrees from rest', gives sign conventions ('negative hip ≈ forward, positive knee ≈ flexion'), constrains plan_id ('must match the locked plan'), and clarifies output_dir. frame_index is scoped via '0..7'. This is model compensation for an undocumented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+method ('Draft one animation frame (0..7) with hierarchical joint rotations'). The pipeline context distinguishes it from siblings plan_animation (planning) and finish_frame_animation (finalizing), so an agent can tell exactly where this tool fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use rules: requires plan_animation to have succeeded AND user OK of the user_facing_summary. Names exclusions ('Jumping straight to rotations is forbidden'), the compose_character prerequisite when a design exists, and the next step (finish_frame_animation). Also directs to get_joint_docs for rotation semantics. Nothing is left to inference.

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