ue-mcp 1.2.4 → 1.3.0

package/dist/tools/animation.js

@@ -1,6 +1,226 @@
 import { z } from "zod";
 import { categoryTool, bp } from "../types.js";
 import { Vec3, Quat } from "../schemas.js";
+// Keep the Control Rig operation schema self-contained so adding it does not
+// redirect JSON-schema references used by older animation actions.
+const ControlRigVec3 = z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+}).strict();
+const ControlRigRotator = z.object({ pitch: z.number(), yaw: z.number(), roll: z.number() }).strict();
+const ControlRigQuaternion = z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+    w: z.number().finite(),
+}).strict().refine((rotation) => Math.abs(Math.hypot(rotation.x, rotation.y, rotation.z, rotation.w) - 1) <= 1e-3, { message: "rotationQuaternion must be normalized" });
+const ControlRigKeyTransform = z.object({
+    translation: ControlRigVec3,
+    rotationDegrees: ControlRigRotator,
+    scale: ControlRigVec3,
+}).strict();
+const ControlRigSetEdit = z.object({
+    op: z.literal("set"),
+    control: z.string().min(1),
+    frame: z.number().int().optional(),
+    frames: z.array(z.number().int()).min(1).optional(),
+    transform: ControlRigKeyTransform,
+    space: z.enum(["local", "global"]).optional(),
+}).strict().refine((edit) => (edit.frame === undefined) !== (edit.frames === undefined), { message: "set operations require exactly one of frame or frames" });
+const ControlRigTransformKey = z.object({
+    frame: z.number().int(),
+    transform: z.object({
+        translation: ControlRigVec3,
+        rotationQuaternion: ControlRigQuaternion,
+        scale: ControlRigVec3,
+    }).strict(),
+}).strict();
+const ControlRigSetKeysEdit = z.object({
+    op: z.literal("set_keys"),
+    control: z.string().min(1),
+    keys: z.array(ControlRigTransformKey).min(1),
+    space: z.enum(["local", "global"]).optional(),
+}).strict().refine((edit) => edit.keys.every((key, index) => index === 0 || key.frame > edit.keys[index - 1].frame), { message: "set_keys frames must be strictly increasing" });
+const ControlRigOffsetEdit = z.object({
+    op: z.literal("offset"),
+    control: z.string().min(1),
+    startFrame: z.number().int(),
+    endFrame: z.number().int(),
+    translationCm: ControlRigVec3.optional(),
+    rotationDegrees: ControlRigRotator.optional(),
+    scaleMultiplier: ControlRigVec3.optional(),
+    space: z.enum(["local", "global"]).optional(),
+    blendInFrames: z.number().int().nonnegative().optional(),
+    blendOutFrames: z.number().int().nonnegative().optional(),
+}).strict()
+    .refine((edit) => edit.endFrame >= edit.startFrame, {
+    message: "offset endFrame must be greater than or equal to startFrame",
+})
+    .refine((edit) => edit.translationCm !== undefined || edit.rotationDegrees !== undefined || edit.scaleMultiplier !== undefined, { message: "offset operations require translationCm, rotationDegrees, or scaleMultiplier" });
+const ControlRigContactTarget = z.object({
+    translation: ControlRigVec3,
+    rotationQuaternion: ControlRigQuaternion.optional(),
+}).strict();
+const ControlRigContactLockEdit = z.object({
+    op: z.literal("contact_lock"),
+    control: z.string().min(1),
+    drivenReference: z.string().min(1).optional(),
+    startFrame: z.number().int(),
+    endFrame: z.number().int(),
+    target: ControlRigContactTarget,
+    blendInFrames: z.number().int().nonnegative().optional(),
+    blendOutFrames: z.number().int().nonnegative().optional(),
+    stabilizeControls: z.array(z.string().min(1)).max(8).optional(),
+    positionToleranceCm: z.number().finite().positive().max(100).optional(),
+    rotationToleranceDegrees: z.number().finite().positive().max(180).optional(),
+}).strict().superRefine((edit, context) => {
+    if (edit.endFrame < edit.startFrame) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["endFrame"], message: "contact_lock endFrame must be at least startFrame" });
+        return;
+    }
+    const intervalCount = edit.endFrame - edit.startFrame;
+    const blendIn = edit.blendInFrames ?? 0;
+    const blendOut = edit.blendOutFrames ?? 0;
+    if (blendIn + blendOut > intervalCount) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["blendOutFrames"],
+            message: "contact_lock blends must leave at least one fully constrained frame",
+        });
+    }
+    const controlKey = edit.control.toLowerCase();
+    const stabilizerKeys = (edit.stabilizeControls ?? []).map((control) => control.toLowerCase());
+    if (stabilizerKeys.includes(controlKey)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stabilizeControls"],
+            message: "contact_lock control cannot also be a stabilizer",
+        });
+    }
+    if (new Set(stabilizerKeys).size !== stabilizerKeys.length) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["stabilizeControls"],
+            message: "contact_lock stabilizers must be unique",
+        });
+    }
+    const frameCount = intervalCount + 1;
+    if (frameCount * (stabilizerKeys.length + 1) > 100_000) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["endFrame"],
+            message: "contact_lock is limited to 100000 control-frame cells",
+        });
+    }
+});
+const ControlRigSetBoolEdit = z.object({
+    op: z.literal("set_bool"),
+    control: z.string().min(1),
+    frame: z.number().int().optional(),
+    frames: z.array(z.number().int()).min(1).optional(),
+    value: z.boolean(),
+}).strict().refine((edit) => (edit.frame === undefined) !== (edit.frames === undefined), { message: "set_bool operations require exactly one of frame or frames" });
+const ControlRigSetFloatEdit = z.object({
+    op: z.literal("set_float"),
+    control: z.string().min(1),
+    frame: z.number().int().optional(),
+    frames: z.array(z.number().int()).min(1).optional(),
+    value: z.number().finite(),
+}).strict().refine((edit) => (edit.frame === undefined) !== (edit.frames === undefined), { message: "set_float operations require exactly one of frame or frames" });
+const ControlRigSetIntEdit = z.object({
+    op: z.literal("set_int"),
+    control: z.string().min(1),
+    frame: z.number().int().optional(),
+    frames: z.array(z.number().int()).min(1).optional(),
+    value: z.number().int(),
+}).strict().refine((edit) => (edit.frame === undefined) !== (edit.frames === undefined), { message: "set_int operations require exactly one of frame or frames" });
+const ControlRigEditOperation = z.union([
+    ControlRigSetEdit,
+    ControlRigSetKeysEdit,
+    ControlRigOffsetEdit,
+    ControlRigContactLockEdit,
+    ControlRigSetBoolEdit,
+    ControlRigSetFloatEdit,
+    ControlRigSetIntEdit,
+]);
+const IKRigAuthoringChain = z.object({
+    name: z.string().min(1),
+    startBone: z.string().min(1),
+    endBone: z.string().min(1),
+    goal: z.string().min(1).optional(),
+}).strict();
+const IKRigFullBodyGoal = z.object({
+    name: z.string().min(1),
+    bone: z.string().min(1),
+    positionAlpha: z.number().finite().min(0).max(1).optional(),
+    rotationAlpha: z.number().finite().min(0).max(1).optional(),
+    chainDepth: z.number().int().nonnegative().optional(),
+    strengthAlpha: z.number().finite().min(0).max(1).optional(),
+    pullChainAlpha: z.number().finite().min(0).max(1).optional(),
+    pinRotation: z.number().finite().min(0).max(1).optional(),
+}).strict();
+const IKRigFullBodySettings = z.object({
+    solverIndex: z.number().int().nonnegative().optional(),
+    rootBone: z.string().min(1),
+    enabled: z.boolean().optional(),
+    goals: z.array(IKRigFullBodyGoal).min(1).max(256),
+}).strict();
+const IKRigExclusion = z.object({
+    bone: z.string().min(1),
+    excluded: z.boolean(),
+}).strict();
+const IKRetargetChainMapping = z.object({
+    targetChain: z.string().min(1),
+    sourceChain: z.string().min(1).nullable().optional(),
+}).strict();
+const IKRetargetPose = z.object({
+    side: z.enum(["source", "target"]),
+    name: z.string().min(1),
+    create: z.boolean().optional(),
+    reset: z.boolean().optional(),
+    autoAlign: z.enum(["chain_to_chain", "mesh_to_mesh", "local_axes", "global_axes"]).optional(),
+    bones: z.array(z.string().min(1)).max(10_000).optional(),
+    rotationOffsets: z.array(z.object({
+        bone: z.string().min(1),
+        rotationQuaternion: ControlRigQuaternion,
+    }).strict()).max(10_000).optional(),
+    rootOffsetZ: z.number().finite().optional(),
+    snapBoneToGround: z.string().min(1).optional(),
+}).strict().refine((pose) => pose.rootOffsetZ === undefined || pose.snapBoneToGround === undefined, { message: "retarget pose rootOffsetZ and snapBoneToGround are mutually exclusive" });
+/**
+ * Element schemas for the Motion Matching authoring arrays (#936).
+ *
+ * These were `z.array(z.any())`, which serialises to an array schema with no
+ * `items`; VS Code refuses to load a tool that carries one. Each object stays
+ * open (`.passthrough()`) so nothing a caller sends today is dropped, and the
+ * entries that the handler also accepts as a bare string keep that spelling
+ * through a union rather than an untyped element.
+ */
+/** set_pose_search_clips: one clip entry. The handler accepts any of the four path spellings. */
+const PoseSearchClipEntry = z.object({
+    sequencePath: z.string().optional().describe("Animation asset path (aliases: asset, assetPath, animationPath)"),
+    asset: z.string().optional().describe("Alias for sequencePath"),
+    assetPath: z.string().optional().describe("Alias for sequencePath"),
+    animationPath: z.string().optional().describe("Alias for sequencePath"),
+    mirror: z.string().optional().describe("'original' | 'mirrored' | 'both'"),
+    disableReselection: z.boolean().optional().describe("Disallow reselecting poses from the same asset"),
+    sampleStart: z.number().optional().describe("Sampling range start in seconds"),
+    sampleEnd: z.number().optional().describe("Sampling range end in seconds"),
+    enabled: z.boolean().optional().describe("Include the clip in the database"),
+}).passthrough();
+/** add_pose_search_schema_pose_channel: one sampled bone. */
+const PoseSearchBoneEntry = z.object({
+    bone: z.string().describe("Bone name"),
+    flags: z.array(z.string()).optional().describe("Any of: velocity, position, rotation, phase"),
+    weight: z.number().optional().describe("Per-bone weight (default 1)"),
+}).passthrough();
+/** create_mirror_data_table: one find/replace bone-name rule. */
+const MirrorFindReplaceExpression = z.object({
+    find: z.string().describe("Bone-name fragment to match"),
+    replace: z.string().describe("Replacement fragment"),
+    method: z.string().optional().describe("suffix (default) | prefix | regex"),
+}).passthrough();
 export const animationTool = categoryTool("animation", "Animation assets, skeletons, montages, blendspaces, anim blueprints, physics assets.", {
     read_anim_blueprint: bp("Read AnimBP structure. Params: assetPath", "read_anim_blueprint"),
     read_montage: bp("Read montage. Params: assetPath", "read_anim_montage", (p) => ({ assetPath: p.assetPath })),
@@ -16,7 +236,7 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     create_blendspace: bp("Create blendspace (2D). Params: skeletonPath, name?, packagePath?, axisHorizontal?, axisVertical?", "create_blendspace"),
     create_blendspace_1d: bp("Create BlendSpace1D. Params: skeletonPath, name?, packagePath?, axisName? (default Speed), axisMin?, axisMax?, gridNum? (#459)", "create_blendspace_1d", (p) => ({ name: p.name, skeletonPath: p.skeletonPath, packagePath: p.packagePath, axisName: p.axisName, axisMin: p.axisMin, axisMax: p.axisMax, gridNum: p.gridNum, onConflict: p.onConflict })),
     populate_blendspace: bp("One-call axis params + samples authoring for BlendSpace 1D/2D. Params: assetPath, axis? ({name?, min?, max?, gridNum?}) for axis 0, blendspaceAxes? (per-axis array), axisHorizontal?/axisVertical? + horizontalMin/horizontalMax/verticalMin/verticalMax/gridNumHorizontal/gridNumVertical (back-compat), samples ([{animationPath, x, y?}]), clearExisting? (default true) (#459)", "populate_blendspace", (p) => ({ assetPath: p.assetPath, axis: p.axis, axes: p.blendspaceAxes, axisIndex: p.axisIndex, axisHorizontal: p.axisHorizontal, axisVertical: p.axisVertical, horizontalMin: p.horizontalMin, horizontalMax: p.horizontalMax, verticalMin: p.verticalMin, verticalMax: p.verticalMax, gridNumHorizontal: p.gridNumHorizontal, gridNumVertical: p.gridNumVertical, samples: p.samples, clearExisting: p.clearExisting })),
-    add_notify: bp("Add notify. For PlayMontageNotify the notifyName is also written onto the spawned notify object so OnPlayMontageNotifyBegin broadcasts it (not 'None'), and montage branching-point markers refresh (#528). notifyProperties writes EditAnywhere fields onto the spawned notify object and therefore requires a notifyClass that resolves. Params: assetPath, notifyName, triggerTime, notifyClass?, notifyProperties?", "add_anim_notify"),
+    add_notify: bp("Add notify. For PlayMontageNotify the notifyName is also written onto the spawned notify object so OnPlayMontageNotifyBegin broadcasts it (not 'None'), and montage branching-point markers refresh (#528/#880). On a montage the PlayMontageNotify classes are added as BRANCHING POINT notifies, which is the only tick type UAnimNotify_PlayMontageNotify::BranchingPointNotify runs at, so OnPlayMontageNotifyBegin broadcasts without a montage reload; pass branchingPoint to force it either way, and read branchingPointMarkerCount in the response to see what the montage cached. notifyProperties writes EditAnywhere fields onto the spawned notify object and therefore requires a notifyClass that resolves. Params: assetPath, notifyName, triggerTime, notifyClass?, notifyProperties?", "add_anim_notify"),
     remove_notify: bp("Remove notify(s) by name and/or class. Pass at least one of notifyName/notifyClass; both filters AND. Idempotent: alreadyDeleted=true if no match. Params: assetPath, notifyName?, notifyClass? (#471)", "remove_anim_notify", (p) => ({ assetPath: p.assetPath, notifyName: p.notifyName, notifyClass: p.notifyClass })),
     get_skeleton_info: bp("Read skeleton. Params: assetPath", "get_skeleton_info"),
     list_sockets: bp("List sockets. Params: assetPath", "list_animation_sockets"),
@@ -47,22 +267,29 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     remove_montage_segment: bp("Remove a segment from a montage slot by index, then relay out the remaining segments and rewrite the montage length. Idempotent: alreadyDeleted=true when the slot already holds no segments. Params: assetPath, segmentIndex, slotName?, slotIndex? (default 0) (#826)", "remove_montage_segment", (p) => ({ assetPath: p.assetPath, segmentIndex: p.segmentIndex, slotName: p.slotName, slotIndex: p.slotIndex })),
     list_montage_segments: bp("List every slot's segments on a montage so a caller can address them by index: animation path, startPos/endPos trim, playRate, loopCount, track position and length per segment, plus the sections with the slot and segment each one links to. Params: assetPath, slotName? (filter to one slot) (#826)", "list_montage_segments", (p) => ({ assetPath: p.assetPath, slotName: p.slotName })),
     create_ik_rig: bp("Create IKRigDefinition asset, optionally with retargetRoot + chains[]. Params: name, skeletalMeshPath, packagePath?, retargetRoot?, chains?: [{name, startBone, endBone, goal?}]", "create_ik_rig"),
-    read_ik_rig: bp("Read IK Rig chains, solvers, skeleton. Params: assetPath", "read_ik_rig"),
+    read_ik_rig: bp("Read an IK Rig's preview mesh, skeleton roots/bones, ancestry-validated chains and goal assignments, concrete goals, exclusions, and structured solver/FBIK effector state. Params: assetPath", "read_ik_rig"),
+    configure_ik_rig: bp("UE 5.8 only. Author an existing IK Rig through UIKRigController with strict bone, ancestry, goal, and setting validation, native readback, one transaction, and checked save; older engines return unsupported_engine_version. autoSetup='retarget' installs the native retarget definition; 'full_body' installs the retarget definition then Full Body IK before requested desired-state upserts. Params: rigPath, autoSetup? ('retarget'|'full_body'), retargetRoot?, rootMotionBone?, chains?: [{name,startBone,endBone,goal?}], fullBodyIK?: {solverIndex?,rootBone,enabled?,goals:[{name,bone,positionAlpha?,rotationAlpha?,chainDepth?,strengthAlpha?,pullChainAlpha?,pinRotation?}]}, exclusions?: [{bone,excluded}].", "configure_ik_rig", (p) => ({ rigPath: p.rigPath, autoSetup: p.autoSetup, retargetRoot: p.retargetRoot, rootMotionBone: p.rootMotionBone, chains: p.chains, fullBodyIK: p.fullBodyIK, exclusions: p.exclusions })),
     list_control_rig_variables: bp("List ControlRig variables and hierarchy. Params: assetPath", "list_control_rig_variables"),
     read_control_rig_graph: bp("Read a Control Rig's RigVM models: every graph with its nodes (name, node path, class), each node's pins (name, pin path, cppType, direction, execute flag, default value, nested sub-pins) and the links between them, plus full member-variable metadata (type, subtype, array-ness, default, public/read-only). list_control_rig_variables only ever reported a node COUNT, which is not enough to verify solver wiring (#774). Params: assetPath, graphName? (substring filter), includePins? (default true), includeDefaults? (default true), includeLinks? (default true), limit? (nodes per graph, default 200)", "read_control_rig_graph", (p) => ({ assetPath: p.assetPath, graphName: p.graphName, includePins: p.includePins, includeDefaults: p.includeDefaults, includeLinks: p.includeLinks, limit: p.limit })),
     read_control_rig_hierarchy: bp("Read a Control Rig's per-element hierarchy metadata: each element's name, type (Bone|Control|Null|Curve...), index, and parent. Params: assetPath (#619)", "read_control_rig_hierarchy", (p) => ({ assetPath: p.assetPath })),
+    begin_control_rig_edit: bp("UE 5.8 only. Create a Sequencer Control Rig editing session over a source AnimSequence; native returns unsupported_engine_version on older engines. Baseline first: before this call, reuse or create a Control Rig for the target character, bind/import the exact target skeleton, add the intended controls, author Forward Solve, add Backward/Inverse Solve, verify it with read_control_rig_hierarchy/read_control_rig_graph, and pass an unchanged source round-trip. For a new baseline, the bundled Epic 5.8 controlrig actions include epic_create, epic_import_bones_from_asset, epic_add_control, and epic_add_backward_solve_graph; epic_create alone is not a usable rig. There is no silent fallback to raw bone-key authoring. rigMode='fk' uses UFKControlRig only when generated FK controls are sufficient; rigMode='asset' requires the verified controlRigPath and rejects rigs without inverse execution. bindingTag is the stable natural key for replay. onConflict is skip|error (default error); existing sessions are never modified. layered defaults false. startFrame is inclusive and endFrame is exclusive. Params: sequencePath, skeletalMeshPath, sourceAnimationPath, rigMode ('fk'|'asset'), controlRigPath?, layered?, startFrame?, endFrame?, displayRate?, bindingTag?, onConflict?. Returns the resolved bindingTag/binding GUID, rig, frame range, controls and created/existed status.", "begin_control_rig_edit", (p) => ({ sequencePath: p.sequencePath, skeletalMeshPath: p.skeletalMeshPath, sourceAnimationPath: p.sourceAnimationPath, rigMode: p.rigMode, controlRigPath: p.controlRigPath, layered: p.layered, startFrame: p.startFrame, endFrame: p.endFrame, displayRate: p.displayRate, bindingTag: p.bindingTag, onConflict: p.onConflict })),
+    read_control_rig_edit: bp("UE 5.8 only. Read transform, bool, float/scale-float, and integer/enum controls from a Control Rig editing session without changing editor state; native returns unsupported_engine_version on older engines and has no silent fallback. Params: sequencePath, bindingTag, controlNames?, frames?, space? ('local'|'global'). Scalar samples return value instead of transform. Control metadata includes native controlType, animatable, and enum path/options where applicable. Returns session identity, layered mode, range/rate, filtered control metadata, and requested frame samples.", "read_control_rig_edit", (p) => ({ sequencePath: p.sequencePath, bindingTag: p.bindingTag, controlNames: p.controlNames, frames: p.frames, space: p.space })),
+    apply_control_rig_edits: bp("UE 5.8 only. Apply typed Control Rig edits in one transaction; native returns unsupported_engine_version on older engines. There is no silent fallback to raw bone tracks. set_keys writes strictly ordered full per-frame transforms from normalized quaternions and preserves shortest-arc quaternion continuity. A set operation writes one full absolute transform at frame or frames. An offset operation applies translation/rotation/scale deltas across an inclusive frame range with optional edge blends. contact_lock densely constrains a translatable driver control, or an optional driven bone/socket reference, to a fixed component-space target with smooth edge blends and optional pole/control stabilization. Driver and stabilizer keys are read back transactionally. A drivenReference contact returns verification='bake_and_analyze_required'; bake it and analyze every constrained frame before accepting the bone/socket result. set_bool, set_float, and set_int key matching scalar controls; enum controls use set_int with one of the integer values reported in enumOptions. Params: sequencePath, bindingTag, operations[] where set_keys={op:'set_keys',control,keys:[{frame,transform:{translation,rotationQuaternion,scale}}],space?}, set={op:'set',control,frame|frames,transform:{translation,rotationDegrees,scale},space?}, offset={op:'offset',control,startFrame,endFrame,translationCm?,rotationDegrees?,scaleMultiplier?,space?,blendInFrames?,blendOutFrames?}, contact_lock={op:'contact_lock',control,drivenReference?,startFrame,endFrame,target:{translation,rotationQuaternion?},blendInFrames?,blendOutFrames?,stabilizeControls?,positionToleranceCm?,rotationToleranceDegrees?}, set_bool={op:'set_bool',control,frame|frames,value}, set_float={op:'set_float',control,frame|frames,value}, or set_int={op:'set_int',control,frame|frames,value}. Sequencer's current interpolation mode is retained. Returns per-operation counts, affected controls/frames, and contactQa summaries; a failed key/readback batch is undone.", "apply_control_rig_edits", (p) => ({ sequencePath: p.sequencePath, bindingTag: p.bindingTag, operations: p.operations })),
+    bake_control_rig_edit: bp("UE 5.8 only. Bake the evaluated Control Rig session to a new AnimSequence asset; native returns unsupported_engine_version on older engines and has no raw-track fallback. The source LevelSequence remains unchanged. outputAssetPath is the output natural key; onConflict is skip|error (default error), never overwrite. Key reduction and Sequencer links are not supported yet, so reduceKeys/createLink must be false or omitted. Params: sequencePath, bindingTag, outputAssetPath, frameRate?, reduceKeys?, tolerance?, createLink?, onConflict?. Returns output asset metadata, frame/rate counts, status, and delete-created-asset rollback.", "bake_control_rig_edit", (p) => ({ sequencePath: p.sequencePath, bindingTag: p.bindingTag, outputAssetPath: p.outputAssetPath, frameRate: p.frameRate, reduceKeys: p.reduceKeys, tolerance: p.tolerance, createLink: p.createLink, onConflict: p.onConflict })),
+    analyze_animation: bp("Cross-version, data-driven AnimSequence inspection using the native animation APIs available in the compiled engine. Samples an AnimSequence and reports deterministic numeric motion diagnostics without Python or viewport inference. Params: assetPath (required AnimSequence), skeletalMeshPath?, boneNames?, frames?, sampleRate?, loop?, outputDirectory? (must resolve under Project/Saved/Codex/AnimationQA and must not already contain artifacts). Returns source/rate/range metadata, sampled local/component transforms, root-motion and continuity metrics, and any written analysis artifacts.", "analyze_animation", (p) => ({ assetPath: p.assetPath, skeletalMeshPath: p.skeletalMeshPath, boneNames: p.boneNames, frames: p.frames, sampleRate: p.sampleRate, loop: p.loop, outputDirectory: p.outputDirectory })),
     set_root_motion: bp("Set root motion settings on AnimSequence. Params: assetPath, enableRootMotion?, forceRootLock?, useNormalizedRootMotionScale?, rootMotionRootLock?", "set_root_motion_settings", (p) => ({ path: p.assetPath, enableRootMotion: p.enableRootMotion, forceRootLock: p.forceRootLock, useNormalizedRootMotionScale: p.useNormalizedRootMotionScale, rootMotionRootLock: p.rootMotionRootLock })),
     add_virtual_bone: bp("Add virtual bone. Params: skeletonPath, sourceBone, targetBone", "add_virtual_bone"),
     remove_virtual_bone: bp("Remove virtual bone. Params: skeletonPath, virtualBoneName", "remove_virtual_bone"),
     create_composite: bp("Create AnimComposite. Params: name, skeletonPath, packagePath?", "create_anim_composite"),
     list_modifiers: bp("List applied animation modifiers. Params: assetPath", "list_anim_modifiers", (p) => ({ path: p.assetPath })),
     create_ik_retargeter: bp("Create IKRetargeter asset and (default) initialize the UE 5.7 ops stack: assigns sourceRig+targetRig to all ops, runs AutoMapChains. Returns chainsMapped count. Params: name, packagePath?, sourceRig?, targetRig?, autoMapChains? (default true) (#246)", "create_ik_retargeter", (p) => ({ name: p.name, packagePath: p.packagePath, sourceRig: p.sourceRig, targetRig: p.targetRig, autoMapChains: p.autoMapChains, onConflict: p.onConflict })),
-    read_ik_retargeter: bp("Read IKRetargeter: source/target rigs and chain mappings. Params: assetPath (#246)", "read_ik_retargeter", (p) => ({ assetPath: p.assetPath })),
+    read_ik_retargeter: bp("Read an IK Retargeter's source/target rigs and preview meshes, flattened and per-op chain mappings, typed op stack, and all named/current pose offsets when the compiled engine exposes them. Params: assetPath (#246)", "read_ik_retargeter", (p) => ({ assetPath: p.assetPath })),
+    configure_ik_retargeter: bp("UE 5.8 only. Configure an existing IK Retargeter through UIKRetargeterController with the correct default-op and per-op rig assignment order, auto/manual chain mappings, named pose authoring, processor validation, native readback, transaction rollback, and checked save; older engines return unsupported_engine_version. Whole-pose auto-align resets that pose first: create a new pose or pass pose.reset=true to acknowledge replacement, then manual offsets are applied. Params: retargeterPath, sourceRig?, targetRig?, sourcePreviewMesh?, targetPreviewMesh?, ensureDefaultOps? (default true), autoMapMode? ('exact'|'fuzzy'|'clear'), forceRemap? (default false), chainMappings?: [{targetChain,sourceChain?:string|null}], pose?: {side,name,create?,reset?,autoAlign?,bones?,rotationOffsets?:[{bone,rotationQuaternion}],rootOffsetZ?,snapBoneToGround?}.", "configure_ik_retargeter", (p) => ({ retargeterPath: p.retargeterPath, sourceRig: p.sourceRig, targetRig: p.targetRig, sourcePreviewMesh: p.sourcePreviewMesh, targetPreviewMesh: p.targetPreviewMesh, ensureDefaultOps: p.ensureDefaultOps, autoMapMode: p.autoMapMode, forceRemap: p.forceRemap, chainMappings: p.chainMappings, pose: p.pose })),
     set_ik_rig_mesh: bp("Set the preview/source skeletal mesh on an EXISTING IK Rig. Params: rigPath, meshPath (#701)", "set_ik_rig_mesh", (p) => ({ rigPath: p.rigPath, meshPath: p.meshPath })),
     set_ik_retargeter_rig: bp("Set the source or target IK Rig on an EXISTING IK Retargeter. Params: retargeterPath, rigPath, side? (source|target, default target) (#703)", "set_ik_retargeter_rig", (p) => ({ retargeterPath: p.retargeterPath, rigPath: p.rigPath, side: p.side })),
     auto_align_retarget_pose: bp("Auto-align all bones of the source/target retarget pose (chain-to-chain) - fixes a retargeter that outputs a static reference pose. Params: retargeterPath, side? (source|target, default target) (#701)", "auto_align_retarget_pose", (p) => ({ retargeterPath: p.retargeterPath, side: p.side })),
     reset_retarget_pose: bp("Reset the current retarget pose (all bones) to the reference pose. Params: retargeterPath, side? (source|target, default target) (#701)", "reset_retarget_pose", (p) => ({ retargeterPath: p.retargeterPath, side: p.side })),
-    batch_retarget_animations: bp("Bake a set of source AnimSequences onto the target skeleton through an IK Retargeter (RunBatchRetarget). Params: retargeterPath, sourceMesh, targetMesh, animPaths[], outputPath? (default: alongside source), prefix?, suffix? (default _Retargeted), overwrite? (#701)", "batch_retarget_animations", (p) => ({ retargeterPath: p.retargeterPath, sourceMesh: p.sourceMesh, targetMesh: p.targetMesh, animPaths: p.animPaths, outputPath: p.outputPath, prefix: p.prefix, suffix: p.suffix, overwrite: p.overwrite })),
+    batch_retarget_animations: bp("Bake validated source AnimSequences onto the target skeleton through an IK Retargeter (RunBatchRetarget), save every output, and roll back newly created outputs if the batch is incomplete or unsavable. Overwrite is rejected. Returns mapping completeness and every unmapped target chain so partial retargets are explicit; pass requireCompleteMapping=true only when the target should have no intentional extra chains. Params: retargeterPath, sourceMesh, targetMesh, animPaths[], outputPath? (default: alongside source), prefix?, suffix? (default _Retargeted), overwrite? (must be false), requireCompleteMapping? (default false) (#701)", "batch_retarget_animations", (p) => ({ retargeterPath: p.retargeterPath, sourceMesh: p.sourceMesh, targetMesh: p.targetMesh, animPaths: p.animPaths, outputPath: p.outputPath, prefix: p.prefix, suffix: p.suffix, overwrite: p.overwrite, requireCompleteMapping: p.requireCompleteMapping })),
     set_anim_blueprint_skeleton: bp("Set target skeleton on AnimBP. Params: assetPath, skeletonPath", "set_anim_blueprint_skeleton"),
     read_bone_track: bp("Read bone transform samples from AnimSequence. Params: assetPath, boneName, frames?: [int]", "read_bone_track"),
     create_pose_search_database: bp("Create a PoseSearchDatabase asset (motion matching). Params: name, packagePath?, schemaPath?", "create_pose_search_database"),
@@ -89,10 +316,15 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     set_sequence_properties: bp("Batch-set properties on AnimSequence assets. If a path is a Montage and resolveFromMontages is true (default), resolves to its first AnimSequence. Params: assetPaths[], properties{enableRootMotion?, forceRootLock?, useNormalizedRootMotionScale?, rootMotionRootLock?}, resolveFromMontages?", "set_sequence_properties"),
     bake_root_motion_from_bone: bp("Bake delta translation from a source bone (e.g. pelvis) onto the root bone across the whole sequence; compensates the source bone so world-space position is unchanged. Params: assetPath, sourceBone, rootBone? (default 'root'), axes? (default ['x','y']), interpolation? ('linear'|'per_frame', default 'linear')", "bake_root_motion_from_bone"),
     // #419/#420 - live-actor skeletal operations (moved from level for proper domain alignment)
-    get_bone_transform: bp("Read a bone or socket transform on a live actor's SkeletalMeshComponent. Wraps GetBoneTransform / GetSocketTransform. Params: actorLabel, boneName (or socket name), componentName? (default: CharacterMesh0 / Mesh / first SK component), world? (auto|pie|game|editor, default auto), space? (world|component|local, default world). Returns location, rotation, scale (#420)", "get_bone_transform", (p) => ({ actorLabel: p.actorLabel, boneName: p.boneName, componentName: p.componentName, world: p.world, space: p.space })),
-    list_bones: bp("List bones in a live actor's SkeletalMeshComponent ref skeleton (name, index, parent). Params: actorLabel, componentName?, world? (auto|pie|game|editor, default auto) (#420)", "list_bones", (p) => ({ actorLabel: p.actorLabel, componentName: p.componentName, world: p.world })),
-    rebind_leader_pose: bp("Re-bind every secondary SkeletalMeshComponent on an actor to a body component (default CharacterMesh0 / Mesh). One-call fix for the 'character explodes after rotating the actor' failure mode. Params: actorLabel, bodyComponent? (#419)", "rebind_leader_pose", (p) => ({ actorLabel: p.actorLabel, bodyComponent: p.bodyComponent })),
-    preview_animation: bp("Toggle bUpdateAnimationInEditor + VisibilityBasedAnimTickOption=AlwaysTickPoseAndRefreshBones on every SkeletalMeshComponent of an actor. Bypasses the 'cannot be edited on templates' guard for level instances. Params: actorLabel, enabled (#419/#420)", "preview_animation", (p) => ({ actorLabel: p.actorLabel, enabled: p.enabled })),
+    get_bone_transform: bp("Read a bone or socket transform on a live actor's SkeletalMeshComponent. Wraps GetBoneTransform / GetSocketTransform. Params: actorLabel OR actorPath, boneName (or socket name), componentName? (default: CharacterMesh0 / Mesh / first SK component), world? (auto|pie|game|editor, default auto), space? (world|component|local, default world). Returns location, rotation, scale (#420)", "get_bone_transform", (p) => ({ actorLabel: p.actorLabel, actorPath: p.actorPath, boneName: p.boneName, componentName: p.componentName, world: p.world, space: p.space })),
+    list_bones: bp("List bones in a live actor's SkeletalMeshComponent ref skeleton (name, index, parent). Params: actorLabel OR actorPath, componentName?, world? (auto|pie|game|editor, default auto) (#420)", "list_bones", (p) => ({ actorLabel: p.actorLabel, actorPath: p.actorPath, componentName: p.componentName, world: p.world })),
+    rebind_leader_pose: bp("Re-bind every secondary SkeletalMeshComponent on an actor to a body component (default CharacterMesh0 / Mesh). One-call fix for the 'character explodes after rotating the actor' failure mode. Params: actorLabel OR actorPath, bodyComponent? (#419)", "rebind_leader_pose", (p) => ({ actorLabel: p.actorLabel, actorPath: p.actorPath, bodyComponent: p.bodyComponent })),
+    // #922/#923/#926 - evaluated pose reads. Everything above this line reads
+    // either raw local-space tracks or the reference pose; these evaluate.
+    sample_pose: bp("Evaluate an AnimSequence (or a BlendSpace at a blend position) and return COMPOSED bone transforms, which read_bone_track (raw local space) and get_bone_transforms (reference pose only) cannot give. Params: assetPath, boneNames? (omit for every bone), frames? or times? (omit for every sampled key), space? (component default | local | world), skeletalMeshPath? (evaluate with that mesh's proportions), incorporateRootMotion? (default true), blendPosition? {x,y,z} (BlendSpace only). Returns samples:[{frame, time, bones:[{name, location, rotation, scale}]}]. A montage is refused with a pointer to its segments, because a montage has no pose of its own (#923/#926/#922)", "sample_pose", (p) => ({ assetPath: p.assetPath ?? p.path, boneNames: p.boneNames, frames: p.frames, times: p.times, space: p.space, skeletalMeshPath: p.skeletalMeshPath, incorporateRootMotion: p.incorporateRootMotion, blendPosition: p.blendPosition })),
+    get_live_bone_transforms: bp("Read the EVALUATED pose off a live SkeletalMeshComponent in the editor world or PIE, for many bones at once. This is the read that tells 'standing' from 'prone' when the reference pose cannot (#922). Also returns componentTransform and an evaluation block (animationMode, animInstanceClass, componentSpaceTransformCount) so a clean component transform sitting on a dead anim instance is visible in one call. Params: actorLabel OR actorPath, componentName? (default CharacterMesh0 / Mesh), boneNames? (omit for every bone, max 1000), space? (world default | component | local), world? (auto|pie|game|editor) (#922/#926)", "get_live_bone_transforms", (p) => ({ actorLabel: p.actorLabel, actorPath: p.actorPath, componentName: p.componentName, boneNames: p.boneNames, space: p.space, world: p.world })),
+    measure_natural_speed: bp("Measure a locomotion clip's planted-foot speed, in cm/s, by evaluating the pose and tracking the lowest foot's horizontal travel while it is in contact. Every retarget changes natural speed by the target skeleton's leg-length ratio, so a BlendSpace built on retargeted clips has to re-measure per clip per character (#923). Params: assetPath, footBones[] (e.g. ['foot_l','foot_r']), contactThreshold? (contact height in cm; omit to derive it from the clip), skeletalMeshPath?, frames?/times?, blendPosition? (BlendSpace only). Returns naturalSpeed, plantedDistance, plantedTime, contactThreshold, per-foot breakdown", "measure_natural_speed", (p) => ({ assetPath: p.assetPath ?? p.path, footBones: p.footBones, contactThreshold: p.contactThreshold, skeletalMeshPath: p.skeletalMeshPath, frames: p.frames, times: p.times, blendPosition: p.blendPosition })),
+    preview_animation: bp("Toggle bUpdateAnimationInEditor + VisibilityBasedAnimTickOption=AlwaysTickPoseAndRefreshBones on every SkeletalMeshComponent of an actor. Bypasses the 'cannot be edited on templates' guard for level instances. Params: actorLabel OR actorPath, enabled (#419/#420)", "preview_animation", (p) => ({ actorLabel: p.actorLabel, actorPath: p.actorPath, enabled: p.enabled })),
 }, undefined, {
     assetPath: z.string().optional(),
     directory: z.string().optional(),
@@ -147,6 +379,7 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     triggerTime: z.number().optional(),
     notifyClass: z.string().optional(),
     notifyProperties: z.record(z.unknown()).optional().describe("add_notify: EditAnywhere fields to set on the spawned notify object (requires notifyClass)"),
+    branchingPoint: z.boolean().optional().describe("add_notify: force the montage notify's tick type. Branching-point notifies are the only ones UAnimNotify_PlayMontageNotify::BranchingPointNotify runs, so OnPlayMontageNotifyBegin needs one; the PlayMontageNotify classes default to true on a montage, everything else to the engine's queued tick (#880)"),
     slotIndex: z.number().optional(),
     segmentIndex: z.number().optional().describe("set_montage_sequence: replace only this segment index within the slot (#626). remove_montage_segment: segment to remove. add_montage_section: segment to anchor the section to (#826)"),
     // Montage segment authoring params (#826)
@@ -160,7 +393,7 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     blendIn: z.number().optional(),
     blendOut: z.number().optional(),
     numFrames: z.number().optional(),
-    frameRate: z.number().optional(),
+    frameRate: z.number().optional().describe("Frames per second for create_sequence or bake_control_rig_edit."),
     boneName: z.string().optional(),
     boneNames: z.array(z.string()).optional(),
     parentClass: z.string().optional().describe("Parent AnimInstance class name for create_anim_blueprint"),
@@ -201,7 +434,7 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     startTime: z.number().optional().describe("Start time for montage section"),
     linkedSection: z.string().optional().describe("Next section name to link to"),
     // IK Rig params (#93)
-    skeletalMeshPath: z.string().optional().describe("Path to skeletal mesh for create_ik_rig / compare_curves_to_morph_targets (#656)"),
+    skeletalMeshPath: z.string().optional().describe("SkeletalMesh asset path. Used by IK Rig creation, curve/morph comparison, Control Rig edit setup, and animation analysis."),
     animPath: z.string().optional().describe("compare_curves_to_morph_targets: AnimSequence or PoseAsset path (#656)"),
     nodeClass: z.string().optional().describe("inspect_anim_nodes: node class substring filter, e.g. PoseDriver (#657)"),
     enableRootMotion: z.boolean().optional(),
@@ -212,11 +445,22 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     targetBone: z.string().optional(),
     virtualBoneName: z.string().optional(),
     retargetRoot: z.string().optional().describe("Retarget root bone name for IK Rig"),
+    rootMotionBone: z.string().min(1).optional().describe("configure_ik_rig: root-motion bone name"),
+    autoSetup: z.enum(["retarget", "full_body"]).optional().describe("configure_ik_rig: optional native rig setup pass"),
+    fullBodyIK: IKRigFullBodySettings.optional().describe("configure_ik_rig: Full Body IK solver and desired goal/effector settings"),
+    exclusions: z.array(IKRigExclusion).max(2_048).optional().describe("configure_ik_rig: desired per-bone solver exclusions"),
     sourceRig: z.string().optional().describe("Source IKRig path for create_ik_retargeter"),
     targetRig: z.string().optional().describe("Target IKRig path for create_ik_retargeter"),
     rigPath: z.string().optional().describe("IK Rig path for set_ik_rig_mesh / set_ik_retargeter_rig (#701/#703)"),
     meshPath: z.string().optional().describe("Skeletal mesh path for set_ik_rig_mesh (#701)"),
     retargeterPath: z.string().optional().describe("IK Retargeter path (#701/#703)"),
+    sourcePreviewMesh: z.string().min(1).optional().describe("configure_ik_retargeter: source preview SkeletalMesh path"),
+    targetPreviewMesh: z.string().min(1).optional().describe("configure_ik_retargeter: target preview SkeletalMesh path"),
+    ensureDefaultOps: z.boolean().optional().describe("configure_ik_retargeter: ensure the complete UE 5.8 default operation stack; defaults true"),
+    autoMapMode: z.enum(["exact", "fuzzy", "clear"]).optional().describe("configure_ik_retargeter: native chain auto-map mode"),
+    forceRemap: z.boolean().optional().describe("configure_ik_retargeter: replace existing mappings during auto-map; defaults false"),
+    chainMappings: z.array(IKRetargetChainMapping).max(10_000).optional().describe("configure_ik_retargeter: explicit target-to-source chain overrides; null or omitted source clears"),
+    pose: IKRetargetPose.optional().describe("configure_ik_retargeter: named source or target pose authoring"),
     side: z.string().optional().describe("source|target for retargeter rig/pose actions (#701/#703)"),
     sourceMesh: z.string().optional().describe("batch_retarget_animations: source skeletal mesh (#701)"),
     targetMesh: z.string().optional().describe("batch_retarget_animations: target skeletal mesh (#701)"),
@@ -224,16 +468,29 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     prefix: z.string().optional().describe("batch_retarget_animations: output name prefix (#701)"),
     suffix: z.string().optional().describe("batch_retarget_animations: output name suffix (#701)"),
     overwrite: z.boolean().optional().describe("batch_retarget_animations: overwrite existing outputs (#701)"),
+    requireCompleteMapping: z.boolean().optional().describe("batch_retarget_animations: reject any unmapped target chain; default false"),
     outputPath: z.string().optional().describe("batch_retarget_animations: destination folder for baked assets (#701)"),
     autoMapChains: z.boolean().optional().describe("create_ik_retargeter: assign rigs to ops + AutoMapChains after creation (default true)"),
-    onConflict: z.string().optional().describe("Asset-creation conflict policy: skip (default) | error | overwrite"),
-    frames: z.array(z.number()).optional().describe("Specific frames to sample for read_bone_track"),
-    chains: z.array(z.object({
-        name: z.string(),
-        startBone: z.string(),
-        endBone: z.string(),
-        goal: z.string().optional(),
-    })).optional().describe("IK retarget chains for create_ik_rig"),
+    onConflict: z.string().optional().describe("Conflict policy. Existing asset actions use skip|error|overwrite; Control Rig begin/bake use skip|error and never overwrite."),
+    frames: z.array(z.number()).optional().describe("Frames to read/sample. Used by read_bone_track, read_control_rig_edit, and analyze_animation."),
+    // UE 5.8 Control Rig + data-driven animation editing workflow.
+    sourceAnimationPath: z.string().optional().describe("begin_control_rig_edit: source AnimSequence asset path (required)."),
+    controlRigPath: z.string().optional().describe("begin_control_rig_edit: verified baseline ControlRigBlueprint asset path for this target character; required when rigMode='asset'. Create and validate the rig first when the project/character has none."),
+    rigMode: z.enum(["fk", "asset"]).optional().describe("begin_control_rig_edit: use 'asset' with the verified baseline controlRigPath; use 'fk' only when generated raw FK controls are the intended editing surface."),
+    layered: z.boolean().optional().describe("begin_control_rig_edit: keep the source animation track active under the Control Rig layer; defaults false."),
+    startFrame: z.number().int().optional().describe("begin_control_rig_edit: optional inclusive edit range start frame."),
+    endFrame: z.number().int().optional().describe("begin_control_rig_edit: optional exclusive edit range end frame."),
+    displayRate: z.number().positive().optional().describe("begin_control_rig_edit: optional LevelSequence display rate in frames per second."),
+    bindingTag: z.string().min(1).optional().describe("Stable Control Rig edit-session natural key used by begin/read/apply/bake."),
+    controlNames: z.array(z.string().min(1)).min(1).optional().describe("read_control_rig_edit: optional controls to sample; omit to read every control."),
+    operations: z.array(ControlRigEditOperation).min(1).optional().describe("apply_control_rig_edits: typed transform/bool/float/int edit operations, including quaternion set_keys."),
+    outputAssetPath: z.string().optional().describe("bake_control_rig_edit: required destination AnimSequence asset path."),
+    reduceKeys: z.literal(false).optional().describe("bake_control_rig_edit: key reduction is not supported yet; omit or pass false."),
+    tolerance: z.number().nonnegative().optional().describe("bake_control_rig_edit: key-reduction tolerance."),
+    createLink: z.literal(false).optional().describe("bake_control_rig_edit: Sequencer links are not supported yet; omit or pass false."),
+    loop: z.boolean().optional().describe("analyze_animation: include end-to-start loop continuity metrics."),
+    outputDirectory: z.string().optional().describe("analyze_animation: optional directory under Project/Saved/Codex/AnimationQA for deterministic artifacts; relative values resolve under that root."),
+    chains: z.array(IKRigAuthoringChain).max(256).optional().describe("IK retarget chains for create_ik_rig or configure_ik_rig"),
     keyframes: z.array(z.object({
         frame: z.number(),
         location: Vec3.optional(),
@@ -252,21 +509,21 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     save: z.boolean().optional().describe("bake_keyframes_batch: save the asset after baking (default true)"),
     // PoseSearch (v0.7.15)
     schemaPath: z.string().optional().describe("Path to a UPoseSearchSchema asset"),
-    sequencePath: z.string().optional().describe("Animation asset path to add to a PoseSearchDatabase"),
+    sequencePath: z.string().optional().describe("Animation path for PoseSearch graph actions, or LevelSequence path for the UE 5.8 Control Rig edit workflow."),
     wait: z.boolean().optional().describe("build_pose_search_index: block until the async build resolves (default true)"),
     // #684 per-clip flags + bulk clip authoring
     mirror: z.string().optional().describe("PoseSearch clip mirror option: 'original' | 'mirrored' | 'both'"),
     disableReselection: z.boolean().optional().describe("PoseSearch clip: disallow reselecting poses from the same asset"),
     sampleStart: z.number().optional().describe("PoseSearch clip sampling range start (seconds); [0,0] = whole clip"),
     sampleEnd: z.number().optional().describe("PoseSearch clip sampling range end (seconds); [0,0] = whole clip"),
-    clips: z.array(z.any()).optional().describe("set_pose_search_clips: array of clip entries ({sequencePath, mirror?, disableReselection?, sampleStart?, sampleEnd?, enabled?}) or bare path strings"),
+    clips: z.array(z.union([PoseSearchClipEntry, z.string()])).optional().describe("set_pose_search_clips: array of clip entries ({sequencePath, mirror?, disableReselection?, sampleStart?, sampleEnd?, enabled?}) or bare path strings"),
     // Motion Matching content pipeline (schema / mirror / normalization / tuning)
-    sampleRate: z.number().optional().describe("create_pose_search_schema: schema sample rate (default 30)"),
+    sampleRate: z.number().optional().describe("Sample rate. create_pose_search_schema: schema rate (default 30); analyze_animation: optional analysis sampling rate."),
     addDefaultChannels: z.boolean().optional().describe("create_pose_search_schema: add Trajectory+Pose default channels (default true)"),
     mirrorDataTablePath: z.string().optional().describe("create_pose_search_schema: optional MirrorDataTable to bind"),
-    bones: z.array(z.any()).optional().describe("add_pose_search_schema_pose_channel: [{bone, flags?, weight?}] or bone-name strings; also add_pose_search_schema_trajectory_channel reuses 'samples'"),
+    bones: z.array(z.union([PoseSearchBoneEntry, z.string()])).optional().describe("add_pose_search_schema_pose_channel: [{bone, flags?, weight?}] or bone-name strings; also add_pose_search_schema_trajectory_channel reuses 'samples'"),
     weight: z.number().optional().describe("Channel weight for pose/trajectory channels"),
-    expressions: z.array(z.any()).optional().describe("create_mirror_data_table: [{find, replace, method?}] find/replace bone-name rules"),
+    expressions: z.array(MirrorFindReplaceExpression).optional().describe("create_mirror_data_table: [{find, replace, method?}] find/replace bone-name rules"),
     mirrorAxis: z.string().optional().describe("create_mirror_data_table: X, Y or Z (default X)"),
     mirrorRootMotion: z.boolean().optional().describe("create_mirror_data_table: mirror root motion (default true)"),
     databases: z.array(z.string()).optional().describe("create_pose_search_normalization_set: PoseSearchDatabase paths to normalize together"),
@@ -295,7 +552,7 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     rootBone: z.string().optional().describe("Root bone name for bake_root_motion_from_bone (default 'root')"),
     axes: z.array(z.string()).optional().describe("Axes to bake ('x','y','z') for bake_root_motion_from_bone"),
     interpolation: z.string().optional().describe("bake_root_motion_from_bone: 'linear' (default) or 'per_frame'"),
-    space: z.string().optional().describe("Bone-space frame. get_bone_transforms (ref skeleton): 'local' (default) | 'component'. get_bone_transform (live actor): 'world' (default) | 'component' | 'local'"),
+    space: z.string().optional().describe("Transform space. Control Rig edit actions: 'local'|'global'. get_bone_transforms: 'local'|'component'. get_bone_transform: 'world'|'component'|'local'."),
     world: z.string().optional().describe("World scope for live actor skeletal queries: auto (default, prefer PIE), pie/game, or editor"),
     animation: z.string().optional().describe("AnimSequence path for add_blend_sample / set_blend_sample"),
     sampleIndex: z.number().optional().describe("BlendSpace sample index for set_blend_sample"),
@@ -304,8 +561,15 @@ export const animationTool = categoryTool("animation", "Animation assets, skelet
     y: z.number().optional(),
     // Live-actor skeletal operations (moved from level)
     actorLabel: z.string().optional().describe("Actor label for live skeletal queries"),
+    actorPath: z.string().optional().describe("Full actor object path. The unambiguous selector, and it wins over actorLabel when both are given. Editor labels are NOT unique, and a label matching several actors is refused with the candidates rather than resolved at random (#983)"),
     componentName: z.string().optional().describe("SkeletalMeshComponent name (default: CharacterMesh0 / Mesh)"),
     bodyComponent: z.string().optional().describe("rebind_leader_pose: explicit body component name"),
     enabled: z.boolean().optional().describe("preview_animation: toggle on/off"),
+    // #922/#923/#926 - evaluated pose reads
+    times: z.array(z.number()).optional().describe("sample_pose / measure_natural_speed: sample times in seconds; pass either this or 'frames'"),
+    incorporateRootMotion: z.boolean().optional().describe("sample_pose: fold the clip's root motion into the returned pose (default true, matching the engine). measure_natural_speed always excludes it, because it measures travel relative to the planted foot"),
+    blendPosition: z.object({ x: z.number().optional(), y: z.number().optional(), z: z.number().optional() }).optional().describe("sample_pose / measure_natural_speed: BlendSpace blend input, in the blendspace's own axis units"),
+    footBones: z.array(z.string()).optional().describe("measure_natural_speed: the foot bones to track, e.g. ['foot_l','foot_r']"),
+    contactThreshold: z.number().optional().describe("measure_natural_speed: height in cm below which a foot counts as planted; omit to derive it from the clip's own lowest foot height, which is what makes the measurement scale-independent across skeletons"),
 });
 //# sourceMappingURL=animation.js.map