Provides tools for inspecting and posing first-person arm and rifle rigs inside Blender, including measuring spatial relationships, clearances, visibility, and rendering labelled contact sheets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.hpdkhoa/poselab-mcp Can turning the rifle show its ejection port to the eye? Check the sample rig."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Measured spatial answers for posing first-person arms and a rifle in Blender, over MCP.
Models are weak at judging 3D space from pictures: which side of a rifle faces the eye, whether a finger sits inside the receiver, whether any turn of the gun can ever show its ejection port. Pose Lab gives a model numbers instead. It reports positions in named frames and how deep anything clips. It measures how squarely a surface faces the eye and what the eye can see. Its solver searches rifle moves against goals and reports which goals no move can meet. For animation, it scans a clip frame by frame against the same checks and mends what fails.
I built it while hand-making chamber checks for my first-person shooter. One question took me several full Blender
runs: can turning the rifle show its ejection port to the eye? With Pose Lab it is one solve call. On my game's AK
rig, turning alone met the goal in 0 of 60 samples. That is a fact of the geometry: the eye looks along the barrel.
Turning and moving the rifle met each goal on its own, but no sample of 400 met all four goals together. So that
check needs a new hand pose, not only a new rifle position. On the built-in sample rig, turning alone also met the port
goal in 0 of 60 samples, and turning and moving met every goal in 9 s.
Tool | Answers |
| the rigs, the frames, the sign rules, named points, clips, moving parts |
| put the rig in a pose: a clip at a time, the carrier drawn back, saved poses |
| roll, swing, pitch and move the rifle; the hands keep their hold by arm IK |
| a wrist onto a point by arm IK (try elbow poles to clear a forearm) |
| positions in a named frame |
| how deep the rifle sits inside a forearm, palm or finger, measured to its surface, and where |
| each arm against the human arm's limits: elbow, wrist and each finger joint, and every rule a pose breaks |
| how each hand touches the rifle: with the palm, not the back of the hand; whether the palm itself holds it; how deep on each side |
| the research behind those limits: each joint's AAOS range, its functional range, the value checked, and the sources |
| how squarely a surface faces the eye, how much of it the eye sees, where it falls on screen |
| searches rifle moves against goals; reports each goal and how often any sample met it |
| a contact sheet: the player's eye and outside views, each tile labelled as a Blender view |
| a clip from keyed poses, or from a file: |
| every frame against checks; the worst value, when, and the time spans that fail |
| mends what fails and reports the scan before and after, and what no fix can reach |
| writes a clip as |
Every position goes in and comes out in a named frame, so no one has to guess axes:
gun: the gun bone as it stands, Unreal-style axes, cm: +X the gun's left, +Y along the barrel, +Z up (the default)
arms: the arms' space, Unreal-style axes, cm
view: from the eye, cm: +X right, +Y forward, +Z up
Turns use the player's words: roll + turns the gun's right side up, swing + takes the muzzle left, pitch + the
muzzle up. Moves (right, forward, up) are in the view.
A hand round its grip touches the rifle on the idle pose already (a finger on the trigger, fingers round the
handguard). Call clearance at pose_idle for that baseline, and leave those segments out with ignore wildcards.
On the built-in sample the left thumb sits 2.7 cm inside the handguard at idle. clearance measures to the rifle's
surface (inside or out by ray parity), so it sees a body part inside a flat face between the mesh's corner points.
anatomy)A pose can clear the rifle and still be one no human arm can take. anatomy checks each arm against these limits:
Joint | Rule |
Shoulder | the elbow stays at least 2 cm below the shoulder while the hand works the gun |
Elbow | a hinge, bent 5 to 150 degrees: never locked straight |
Forearm | it carries the hand's roll (the radius turns over the ulna): pronation and supination at most 80 degrees each from thumb up, measured against the elbow's hinge plane |
Forearm skin | on a rig with forearm twist bones, the roll spreads along the forearm: no single link (the elbow's end, each twist bone, the wrist) rolls more than 50 degrees |
Wrist | no twist of its own; on a rig without twist bones, the hand's twist against the idle grip's at most 30 degrees |
Wrist | within 30 degrees of the forearm's line; inside its joint range: flexion 80, extension 70, radial 20, ulnar 30 |
Fingers | each joint curls only toward the palm: knuckle -30 to 100, middle joint -5 to 110, end joint -10 to 90 |
Fingers | each finger stays in its own plane: the middle joint at most 15 degrees off its hinge, the end joint at most 25 off the middle joint's plane |
Thumb | the knuckle bends -10 to 60 and the end joint -15 to 90, across the palm; the base spreads at most 80 from the index metacarpal and sits at most 20 behind the palm |
The wrist and elbow ranges are the AAOS normal values, from the AAOS 1965 table as reprinted in Greene and Heckman
1994. Other tables differ, by 10 to 25 degrees for the fingers and thumb. The 30 degree wrist line, the 5 degree elbow
minimum and the elbow under the shoulder are working rules for this game's look of a hand on a gun, not joint limits.
The wrist rule is stricter than daily tasks: Ryu 1991 found daily tasks use up to 60 degrees of extension and 40 of
ulnar deviation. The finger limits allow 10 more flexion than AAOS at the knuckle and the middle joint;
docs/ANATOMY.md says why the defaults stay that way. It gives each joint's standard and functional
range, the value checked, and the sources (AAOS; Eaton; Morrey 1981; Palmer 1985; Ryu 1991; Hume 1990; Bain 2015;
Soucie 2011). arm_ranges returns the same data to a model.
The anatomy reply lists, for each arm, the elbow's height under the shoulder, the elbow's bend, the wrist's bend split into
flexion and radial deviation, the wrist's twist, each finger joint's curl and twist, and bad: every rule the pose
breaks. Each rule reads the value as reported: angles to the degree, the elbow's height to 0.1 cm. A rig's
limits, finger_limits and thumb_limits entries in rigs.json override any value. solve takes {"type": "anatomy"} as a goal.
move_gun, reach and fix_clip place hands with a turn. They move the hand's twist into the forearm, so the wrist
joint only bends: a 60 degree rifle roll with the hands kept reads no wrist twist.
Fix a broken rule by moving the rifle, the grip or the elbow's pole. Do not bend a joint further.
The sample rig's idle grip breaks the wrist rule: the left wrist bends 44 degrees off the forearm and the right 58.
fix_clip with an anatomy check brings the left to 29. It leaves the right at 58: every turn that mends it puts
the rifle inside the back of the palm, so that hand needs a new grip or elbow, not a wrist turn.
grip)A hand holds the rifle with its palm and the palm sides of its fingers. clearance is usually run with the palms and
fingers left out, since a grip touches the rifle there. That also hides a hand on the wrong side. grip checks the
contact itself, for each hand:
Rule | Default |
A hand on the rifle faces it with the palm, not the back ( | within |
A hand holding the rifle has its palm on it, not only a fingertip ( |
|
The rifle stays out of the back of the hand and the back of each finger |
|
The palm side may press in a little: the capsules are rounder than a palm |
|
Each finger segment's palm side is the side it curls toward. The thumb's pad faces sideways, so its contacts count
toward the palm side's depth only. The reply gives each hand's touching (some part within hold_within_cm),
holding (touching, the palm facing the rifle and its surface within palm_within_cm), palm_gap_cm,
palm_faces_rifle, palm_contact_cm, back_contact_cm, where the back contact is, and bad. With hold true, a hand
that is not holding breaks a rule. solve takes {"type": "grip"} as a goal and scan_clip as a check. On the sample
rig, a hand turned 180 degrees about its forearm fails it. So does the idle grip: the left thumb sits 2.8 cm inside the
handguard, the right palm presses 1.2 cm into the pistol grip, and the trigger finger's back sits 0.8 cm inside the
trigger guard. The sample stays as it is, so the benchmark's numbers keep their meaning.
Related MCP server: blender-animation-mcp
scan_clip plays a clip frame by frame and runs checks on each frame. The checks are the solver's goals
(clearance, anatomy, grip, faces_eye, visible, on_screen, barrel) and three more:
contact: a point of the hand on its mark, such as a fingertip on the charging handle (a, b, max_cm)
hold: how far a hand drifts on the rifle from its grip at ref_s (side, max_cm)
pop: a sudden jump, as the fastest bone speed between frames (bones, max_cm_per_s)
Any check takes during: [from_s, to_s]. fix_clip then mends a copy of the clip:
a pop: it blends the jumping frames again from the good frames round them
a hold: it puts the hand back on its grip by arm IK
a contact: it moves the wrist until the point touches its mark
clearance: it swings each elbow about the shoulder to wrist line by the least angle that clears, wrist kept, and eases that swing over the neighbouring frames
anatomy: it swings the elbow the same way until the elbow sits under the shoulder and inside its bend. Then it turns
the wrist back inside its limits and each finger joint back inside its range. It never turns a wrist so far that
the rifle goes into the back of the hand; a wrist it cannot mend that way stays as it was, and the scan after says
so. Turning the wrist turns the hand on its grip, so add a hold check when the grip must stay exact.
grip: not mended; fix_clip reports it before and after. A wrong-side hold needs a new grip.
It reports the scan before and after. It also lists the frames where a hand must be somewhere its arm cannot reach, since only a new pose can mend those.
examples/motion_test.py records a clip on the sample rig with two common faults. The rifle rolls 75 degrees and
back, keyed only at its ends, so the hands drift off the rifle between keys. One frame also jumps 15 cm. The scan and
the fix gave these numbers:
Check | Before | After |
left hand drift on the rifle | 2.27 cm | 0.48 cm |
right hand drift on the rifle | 1.67 cm | 0.45 cm |
fastest hand speed (the pop) | 450 cm/s | 33 cm/s |
clearance | 0.93 cm | 0.0 cm |
The fix changed 34 of 43 frames, and every check passed after it. It also flagged 6 frames where the left arm fell 0.46 cm short of its grip. That still passed the 0.5 cm limit. (Before 0.3.1 the clearance read 0.0 cm: the corner points missed the forearm inside the rifle.)
You need Blender and Python 3.10 or newer. I tested it on Windows 10 with Blender 5.2.2 and Python 3.14. I have not tested macOS, Linux or older Blender versions yet.
uvx poselab-mcpor pip install poselab-mcp and run poselab-mcp.
Add it to Claude Code:
claude mcp add poselab -- uvx poselab-mcpor to any MCP client's configuration:
{
"mcpServers": {
"poselab": {
"command": "uvx",
"args": ["poselab-mcp"],
"env": { "POSELAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" }
}
}
}Variable | Meaning |
| Blender's executable, if it is not on the PATH or in the usual install folder |
| a |
| the only folder Pose Lab writes to (renders, saved clips, the worker's log); default |
The built-in sample (load_rig {"rig": "sample"}) needs no files. Pose Lab builds it in Blender from code: two
arms with Unreal mannequin bone names hold an AR-style rifle with a charging handle that slides back.
Your own rigs come from FBX files: the arms mesh, an idle pose, the rifle, and clips. Describe them in a
rigs.json (copy examples/rigs.example.json) and point POSELAB_RIGS at it. Clips can be FBX animations on the same
skeleton, or <clip>.pose.json bone data: {"fps": 30, "frames": [{"bone": [[x, y, z], [w, x, y, z]], ...}, ...]},
local location and rotation per bone on the idle armature. (Blender misreads an FBX animation it exported itself when
it imports it again; bone data avoids that. describe reports each FBX clip's skeleton fit.)
Pose Lab only reads your rig and clip files. It writes renders, saved clips and its log, and only inside
POSELAB_OUT.
The Blender worker listens on 127.0.0.1 only, on a free port, and answers only requests that carry the session's random token. It runs only Pose Lab's own commands.
poselab_mcp/server.py: the MCP server (the official Python SDK, stdio).
poselab_mcp/worker_client.py: starts one headless Blender on the first call and keeps the rig loaded.
poselab_mcp/blender/lab.py: inside Blender: the rig, the frames, the measures, the IK, the solver, the renders.
poselab_mcp/blender/sample.py: the built-in sample rig.
python examples/selftest.pyIt starts the server as an MCP client does and loads the sample rig. Then it replays the question above: turning
alone never shows the port, and turning and moving does. The contact sheet lands in ~/.poselab/renders/sheet.png.
python examples/motion_test.pyIt records the faulty clip described above, scans it, fixes it, and saves roll_fixed.pose.json and roll_fixed.fbx
in ~/.poselab/clips/.
blender -b -P examples/anatomy_faults.pyIt puts one known fault at a time on the sample and fails if a check misses it: a finger kinked sideways, a hand twisted against its forearm, a hand inside a flat face, a fingertip-only touch, and a rigs file with a byte order mark. These come from a real rig's benchmark (below).
benchmarks/ asks whether a model poses the rig better with Pose Lab's measurements than with renders alone. It runs
five tasks on the sample rig and grades them with Pose Lab. A scripted oracle and a do-nothing control check the
graders. See benchmarks/README.md.
benchmarks/runs/2026-10-09-toangtown-m24 tests the checks themselves on a real game rig: 8 poses of a hand on a magazine, 7 with a known fault. Pose Lab 0.3.0 caught 5 and read clipping at 40% of its depth; 0.3.1 catches all 7 with the depths exact.
MIT
How deep the rifle sits inside the arms (capsules: forearm 3 cm, palm 1.8 cm, finger segments 0.75 cm). worst_cm 0 means nothing touches. The deepest contacts by segment, with the rifle point in the frame.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| frame | No | gun: the gun bone, cm (+X gun's left, +Y barrel, +Z up); arms: the arms' space, cm; view: from the eye, cm (+X right, +Y forward, +Z up) | gun |
| parts | No | both | |
| ignore | No | segment names, prefixes or wildcards to leave out (thumb, index3_r, *_l) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but does disclose some behavioral context: units (cm), capsule sizes, and that 'worst_cm 0 means nothing touches'. However, it does not state that the operation is read-only, nor does it describe the output format or any side effects. The description adds partial value over the schema.
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 brief and front-loads the core concept. It contains no filler sentences. However, the phrasing is somewhat disjointed and could be better structured, but it is efficient overall.
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 the tool has 4 parameters, no output schema, and no annotations, the description should be far more complete. It omits explanation of what the tool returns (output shape), when to use it, and details on the undocumented parameters. The brief hints about 'worst_cm' and contacts are insufficient for correct invocation.
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 coverage is only 50% (frame and ignore are described in the schema). The description mentions 'the rifle point in the frame', which loosely relates to the frame parameter, but provides no meaning for 'top' or 'parts', which are undocumented in both schema and description. The description fails to compensate for the missing parameter semantics.
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 measurement ('How deep the rifle sits inside the arms') rather than a clear verb+resource. It implies the tool computes clearance but does not frame it as an action or distinguish it from siblings like distance. The mention of 'worst_cm' and 'deepest contacts by segment' gives some functional context.
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 when-to-use guidance or alternatives are provided. The agent is left to infer the tool's role from the cryptic description. There is no indication of when this tool should be preferred over 'distance', 'reach', or other measurement siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is loaded and the conventions every tool uses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 the tool reports both loaded state and cross-tool conventions, which is meaningful for a zero-argument tool, but it says nothing about return shape, whether it is a safe read, or how the 'conventions' are presented.
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?
A single short sentence with no padding, and the 'what is loaded' clause is front-loaded. It is efficient, though the compression borders on cryptic rather than informative.
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?
For a no-parameter, no-annotation, no-output-schema tool the burden is low, and the description names both things it reports. However, the vague wording ('the conventions every tool uses') gives an agent no concrete expectation of what the response actually contains, which is the one thing this description needed to nail down.
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?
The schema declares zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims in the description conflict with the empty schema.
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 gestures at the tool's content ('what is loaded', 'the conventions every tool uses') but never states a verb or a concrete resource, so it reads more like a topic label than a stated action. It is not a pure tautology of the name 'describe', but an agent gets only an abstract sense of what comes back and no differentiation from siblings like list_rigs or where.
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?
There is no statement of when to call this versus the other fifteen tools, nor any prerequisite or ordering hint (e.g. 'call first to orient'). The only implicit cue is that it surfaces conventions, from which an agent might infer it is an orientation call, but that is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The distance between two points, cm, and b minus a in the frame.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame | |
| b | Yes | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame | |
| frame | No | gun: the gun bone, cm (+X gun's left, +Y barrel, +Z up); arms: the arms' space, cm; view: from the eye, cm (+X right, +Y forward, +Z up) | gun |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the unit (cm) and ties the result to the selected frame, but it never states whether the returned value is a signed scalar, unsigned magnitude, or a vector, and 'b minus a' actively suggests a directional result that contradicts the word 'distance'.
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?
It is a single short sentence with no padding, which is good, but the clause 'cm, and b minus a in the frame' is grammatically awkward and buries the key semantic point, reducing clarity rather than achieving crispness.
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 and no annotations, the description must explain the return value and the mathematical convention, and it fails to do so. For a measurement tool with three parameters and three frames, this leaves the agent unsure what it actually gets back.
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%, so the schema already documents the name/coordinate options and the frame semantics; baseline 3 applies. The description reiterates the unit and frame context but adds no syntax or format detail beyond the schema.
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 the tool computes the distance between two points with a unit (cm), so the resource is identifiable. However, the phrasing is muddled: 'b minus a in the frame' describes a vector difference, which conflicts with the scalar notion of distance, and no sibling (e.g. clearance, where) is named to distinguish this tool from related measurement tools.
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?
There is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives such as clearance or where. Usage is only weakly implied by the idea of measuring between two rig points.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How squarely a surface faces the eye: facing 1 square on, 0 edge on, below 0 turned away.
| Name | Required | Description | Default |
|---|---|---|---|
| point | No | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame | port |
| normal | No | the surface's normal, gun frame; a rig normal by the point's name if left out |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the output scale and its semantics (1 square on, 0 edge on, below 0 turned away), which is genuinely useful behavioral context, but it omits whether this is a pure read/query, how the 'eye' is defined, and what happens with an unknown point name or a missing rig normal.
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?
It is a single front-loaded sentence with no filler, which is good. But the phrasing ('squarely', 'square on', 'edge on', 'turned away') is cryptic shorthand that costs the reader more effort than a slightly longer explicit statement would.
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 and no annotations, the description should at minimum explain the return value and the frame/eye conventions. It conveys the value's range and meaning but not its type, the definition of 'the eye', or error/edge-case behavior, leaving notable gaps for a geometric query tool.
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%: both point (name or [x,y,z]) and normal (gun-frame normal, defaulting to the point's rig normal) are fully documented in the schema. The description adds no parameter detail beyond that, so the baseline of 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 defines the computed quantity — a facing score with 1 = square-on, 0 = edge-on, negative = turned away — so an agent can infer the metric. However, it is a noun phrase with no verb (never states that the tool returns a number), and it draws no boundary against closely related siblings like visible, screen, or clearance.
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?
There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as visible or screen that also assess surfaces from the eye. Use is only faintly implied by the metric's definition, so the agent must guess the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The rigs to load: the built-in sample and those in the rigs file (POSELAB_RIGS).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that rigs come from a built-in sample plus the POSELAB_RIGS file, which is genuinely useful environmental context, but it never states that this is a read-only enumeration, what the result looks like, or what happens if the rigs file is missing or unset.
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?
It is a single short sentence with no padding, so it is not verbose. However, the one sentence spends its words on the composition of the rig list rather than on the action performed, which is the more valuable information to front-load.
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, the description is responsible for conveying what comes back, and it does not say the tool returns a list of rig names/identifiers or how they are used downstream. For a discovery tool whose result feeds load_rig, this leaves a real gap despite the schema being trivial.
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?
The tool takes zero parameters, so there is no per-parameter meaning for the description to add. The baseline for a parameterless tool applies. The sentence does not mislead about inputs, though it is written as if it describes an input.
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 is a noun phrase that never states an action — it reads like a parameter description ('the rigs to load') rather than a tool description. It restates the resource named in the tool title without saying that the tool lists/enumerates rigs. The only added value is naming the two sources of rigs, which does not clarify what the tool does.
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 on when to call this versus the sibling load_rig, or whether it should precede loading a rig. It does not state any condition, prerequisite, or alternative. An agent must infer the relationship between list_rigs and load_rig entirely on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Loads a rig: the arms on their idle pose, the rifle on the gun bone, its clips. Returns the frames, sign rules, named points, clips and moving parts. Call first.
| Name | Required | Description | Default |
|---|---|---|---|
| rig | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It does disclose meaningful side effects (poses arms idle, attaches rifle to the gun bone, loads clips) and lists what is returned, which is useful. However it omits idempotency/reload behavior and what happens on an invalid rig identifier.
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?
Three short sentences, zero filler, with the core action front-loaded. The trailing 'Call first' would read better up front, but nothing is wasted.
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?
No output schema, so describing the return payload is appropriate and partially done. But with zero annotation coverage and a completely undocumented required parameter, the definition leaves an agent guessing on how to supply 'rig', which is a real gap for a tool that must be called first.
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 coverage is 0% and the single 'rig' parameter is undocumented in both schema and description. An agent cannot tell whether 'rig' is a name, ID, path, or handle, and the description's 'rig' references add no format or validity detail. With one undocumented required param, the description fails to compensate for the coverage gap.
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?
States a specific verb+resource ('Loads a rig') and goes further by enumerating what state is initialized (idle arm pose, rifle on the gun bone, clips). It doesn't explicitly contrast with sibling list_rigs, but 'Call first' effectively signals its role as the initializer.
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?
'Call first' is an explicit ordering directive that tells the agent when to invoke this relative to the pose_*/move_* siblings. It stops short of naming alternatives or exclusion conditions (e.g. when not to reload), so it lands just under a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves the rifle from where it stands: roll + turns its right side up (about the bore); swing + takes the muzzle left, pitch + the muzzle up (about the pivot); right, forward, up move it in the view, cm. The hands in keep_hands keep their hold. Returns how far each hand ended from its hold and the barrel's angle off the view line.
| Name | Required | Description | Default |
|---|---|---|---|
| up | No | ||
| roll | No | ||
| pitch | No | ||
| pivot | No | a rig point (stock, bore) or [x, y, z] in the gun frame | stock |
| right | No | ||
| swing | No | ||
| forward | No | ||
| keep_hands | No | hands that keep their hold on the rifle as it moves (arm IK) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that hands listed in keep_hands maintain their hold and that the return includes each hand's displacement from its hold plus the barrel angle relative to the view line. However, it omits whether the move is relative to the current pose, what happens on failure, and whether any constraints or permissions apply.
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 purpose is front-loaded, and the dense middle sentence efficiently maps all parameters and output. It is appropriately sized for an 8-parameter spatial tool, with only minor redundancy and awkwardness in the axis clauses.
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?
There is no output schema, but the description helpfully summarizes the return values. For a spatial manipulator with no annotations, it still leaves gaps around the coordinate frame referred to by 'the view,' whether motion is relative or absolute, and what happens when hands cannot keep their hold. It is minimally viable but not fully complete.
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 only 25%, so the description must compensate, and it largely does: it assigns directional meaning to roll, swing, pitch, right, forward, and up, specifies centimeters for translational moves, and ties pivot to the bore or pivot point. This adds substantial meaning beyond the bare schema, though the exact axis conventions remain slightly ambiguous.
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 opens with a specific verb and resource: 'Moves the rifle from where it stands.' It is clear what physically happens, but it never names or contrasts with the sibling tool move_part, so an agent cannot tell from the description alone why it should choose move_gun over move_part.
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 explains the mechanics of the six movement axes but gives no when-to-use context, no prerequisites, and no alternatives. It does not state whether this is for aiming, posing, or collision avoidance, nor when to prefer reach or solve instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draws a moving part of the rifle (such as carrier) back along the barrel, cm from home.
| Name | Required | Description | Default |
|---|---|---|---|
| cm | Yes | ||
| part | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full behavioral burden. It implies physical actuation but says nothing about whether this is a simulation or real hardware, whether the motion is reversible, permission needs, valid part names, or what happens on an out-of-range value.
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?
A single front-loaded sentence with no filler. It is terse, though the phrasing ('cm from home') is slightly awkward rather than maximally clear.
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?
For an actuation/motion tool with no annotations, no output schema, and 0% parameter coverage, the description is far too thin. Missing reversibility, valid values, and safety/context information an agent would need to invoke it 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 0%, so the description must compensate. It does give meaning to both: 'part' with the example 'carrier', and 'cm' as distance 'from home'. But it leaves the valid set of part names and whether cm is a signed delta or absolute offset ambiguous.
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?
States a specific action (drawing/moving a rifle part) and its resource (a named moving part such as the carrier), so an agent can infer this is an actuation/positioning command. However, it does not distinguish itself from the sibling move_gun, leaving the agent to guess which motion tool fits.
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 when-to-use guidance, no prerequisites, and no reference to the obvious alternative move_gun. The agent must infer the context entirely from the sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The arms as a clip has them at a time in seconds. The rifle follows the gun bone; its parts stay where move_part left them.
| Name | Required | Description | Default |
|---|---|---|---|
| clip | Yes | ||
| seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses some behavior (rifle follows gun bone; parts remain where move_part left them) but omits critical details such as whether the tool mutates state, required prerequisites, or how 'clip' and 'seconds' interact. The disclosure is partial and confusing.
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 short (two sentences), so it is not verbose. However, the first sentence is garbled and the second sentence, while useful, is oddly placed. Structure is poor but size is appropriate.
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?
For a two-parameter pose tool with no output schema and no annotations, the description is incomplete. It never clarifies the clip format, whether a rig must be loaded first, what the tool returns, or its side effects. The minimal behavioral notes are insufficient for correct invocation.
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 coverage is 0% and no annotations exist, so the description must explain parameters. It only vaguely states 'a time in seconds', which gives the unit for 'seconds' but says nothing about what 'clip' expects (name, path, ID?) or its format. Compensation for the coverage gap is inadequate.
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 is grammatically broken and does not clearly state a verb+resource. 'The arms as a clip has them at a time in seconds' is confusing; it hints at posing arms from a clip but never says 'pose' or defines the action unambiguously. It fails to differentiate from pose_idle or move_part.
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 when-to-use guidance is given. move_part is mentioned only as a behavioral note ('parts stay where move_part left them'), not as an alternative. There is no indication of when this tool should be chosen over pose_idle or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The arms back on the idle pose, every rifle part home.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It hints at a state-mutating reset ('arms back', 'rifle part home') but does not disclose permissions, whether it discards a current pose, or what the resulting state is. The poetic phrasing leaves real behavior unstated.
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?
It is a single short sentence, so it is not bloated, but the content is cryptic rather than front-loaded. The metaphor ('every rifle part home') trades clarity for brevity.
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?
For a zero-annotation, no-output-schema tool, the description should fully explain what state change occurs and any prerequisites. Instead it offers only a vague poetic image, leaving an agent unsure of the exact effect on the rig.
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?
The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter semantics to add meaningfully beyond the schema.
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 name pose_idle plus 'arms back on the idle pose, every rifle part home' conveys that this resets a rig's arms and rifle parts to an idle/home position. However, the phrasing is cryptic prose rather than a clear verb+resource statement, and it does not distinguish itself from siblings like pose_clip or move_part.
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 on when to use this tool versus alternatives. The siblings include pose_clip and move_part, which plausibly overlap, but the description offers no condition that would select one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Puts a wrist on a point by arm IK; the hand keeps its turn. Returns how far the wrist ended from the point. Trying poles while the wrist stays put moves only the elbow: a way to clear a forearm.
| Name | Required | Description | Default |
|---|---|---|---|
| pole | No | where the elbow points, arms frame cm | |
| side | Yes | ||
| frame | No | gun: the gun bone, cm (+X gun's left, +Y barrel, +Z up); arms: the arms' space, cm; view: from the eye, cm (+X right, +Y forward, +Z up) | gun |
| target | Yes | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the hand orientation is preserved and that the return value is the residual wrist-to-target distance, and it explains pole side effects. It omits what happens when the target is unreachable or whether the existing arm pose is overwritten.
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?
Two tight sentences: the primary behavior and return value come first, the pole side-effect second. No filler, and the most important fact (it moves the wrist to a point) is front-loaded.
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?
No output schema exists, and the description correctly covers the return value ('how far the wrist ended from the point'). Combined with reasonably rich schema descriptions for pole/frame/target, an agent has what it needs, though failure modes (unreachable target) are absent.
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 coverage is 75% (side and target/frame are documented), and the description adds genuinely new meaning for 'pole' by explaining its effect on the elbow rather than just its format. It complements the schema rather than repeating it.
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?
States a specific action (arm IK placing the wrist on a point) and a specific constraint (hand keeps its turn), which is enough to separate it from pose/move siblings like move_part or solve. It is clear but relies on domain jargon (poles, forearm clearance) that isn't fully unpacked.
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?
Gives one concrete usage scenario ('trying poles while the wrist stays put moves only the elbow... a way to clear a forearm'), which implies when the tool is useful. It never names an alternative sibling or states when not to use it, so selection guidance remains inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renders the pose as one labelled contact sheet: eye is the player's camera (90 degrees, 5 cm near plane); right, left, top and front look at the rifle from outside. Every tile is a Blender view, labelled so.
| Name | Required | Description | Default |
|---|---|---|---|
| views | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the output is a single labelled contact sheet, eye uses a 90-degree FOV with a 5 cm near plane, and the other four views observe the rifle from outside. It does not say whether files are written to disk, where the render is produced, or whether the operation is expensive, which matters for a render tool.
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?
Two dense sentences with zero filler, and the primary output claim (a single labelled contact sheet) is front-loaded. The camera-detail clause is slightly run-on but still earns its place.
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?
For a render tool with no annotations and no output schema, the description correctly characterizes the returned artifact and the camera setup, so the agent can call it. It stops short of covering persistence, format, or side effects, which are exactly the gaps annotations would normally fill.
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% and the enum values are not described in the schema, so the description must compensate — and it does, explaining that 'eye' is the player's camera and that right/left/top/front look at the rifle from outside. It omits the default view set (eye, right, left, top) and what happens if 'views' is left unset.
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?
States a specific verb (renders) and resource (the pose) and names the output artifact (one labelled contact sheet), so the agent knows exactly what it gets back. It doesn't explicitly differentiate itself from nearby siblings like snapshot or screen, which is the only thing keeping it from a 5.
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?
There is no statement of when to call render versus snapshot or screen, nor any prerequisites or exclusions. The description only explains what the output looks like, leaving the agent to infer the selection criteria from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where a point falls on a 90 degree, 16:9 screen from the eye: x and y from -1 to 1, and whether it is on screen.
| Name | Required | Description | Default |
|---|---|---|---|
| point | Yes | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output coordinate range and on-screen boolean, which is useful, but it omits error behavior, permission requirements, and edge-case handling for point resolution.
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 definition is a single front-loaded sentence with no wasted words. It efficiently conveys the projection and return semantics.
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?
For a one-parameter tool with no output schema, the description gives a reasonable summary of the computed result, but it lacks usage guidance among many siblings and does not fully specify the return structure or failure modes.
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%, and the point parameter is fully documented in the schema. The description does not add syntax or format details beyond what the schema already provides, 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 states a specific computation: projecting a point onto a 90-degree 16:9 screen from the eye and reporting x/y in -1..1 plus on-screen status. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings such as visible or where.
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?
There is no guidance on when to use this tool instead of alternatives like visible, faces_eye, or where. The description implies a screen-projection use case but provides no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves or loads a named pose (the arms and the rifle's parts).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| action | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full behavioral burden. It reveals the save/load action and that it affects arms and rifle parts, but omits whether saving overwrites an existing pose, what loading does to the current pose, required permissions, or any side effects.
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?
A single concise sentence with zero waste. The parenthetical clarifying the pose's scope is front-loaded and useful.
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?
For a tool with no annotations, no output schema, two required parameters, and 0% schema description coverage, the description is too thin. It lacks usage context, parameter detail, and behavioral transparency needed for confident invocation.
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%. The description faintly maps 'name' to a pose name and 'action' to save/load, but adds no format, constraints, uniqueness rules, or other semantics beyond what the bare schema properties imply.
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?
States a specific verb ('saves or loads') and resource ('a named pose (the arms and the rifle's parts)'), so the agent knows it manages saved poses. It does not explicitly distinguish itself from siblings such as pose_idle, pose_clip, or load_rig, leaving some ambiguity about when snapshot is preferred.
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?
Provides no when-to-use guidance, prerequisites, or named alternatives. The agent must infer context entirely from the name and one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches rifle moves from the current pose for one meeting every goal, and leaves the scene there. Reports each goal at the best move and how often it was met across samples: a goal never met is a fact of the geometry.
| Name | Required | Description | Default |
|---|---|---|---|
| dofs | Yes | roll, swing, pitch, right, forward, up -> [min, max] | |
| goals | Yes | each {type: faces_eye|visible (point, min), on_screen (point), clearance (parts, ignore, max_cm), barrel (max_deg), distance (a, b, max_cm)} | |
| pivot | No | stock | |
| samples | No | ||
| maximize | No | a goal's index to push higher once all are met | |
| keep_hands | No | hands that keep their hold on the rifle as it moves (arm IK) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the tool mutates the scene ('leaves the scene there') and reports per-goal success frequency, but it omits reversibility, failure behavior, and dependency details.
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 dense sentences with no wasted words and leads with the core action. The phrasing is somewhat awkward but structurally front-loaded and efficient.
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?
For a complex six-parameter solver with no annotations and no output schema, the description is minimally adequate. It summarizes the side effect and return report, but does not explain key parameters or edge cases, leaving the agent to rely heavily on the schema.
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 only 67%, and the description does not compensate. It mentions goals and samples in passing but provides no additional meaning for dofs, pivot, maximize, or keep_hands beyond what the schema already says.
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 operation: searching rifle moves from the current pose to satisfy every goal and leaving the scene at the result. It is clear enough to distinguish this from simple move or list tools, though it does not explicitly name any sibling alternative.
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 phrase 'from the current pose' implies a context, but the description gives no explicit when-to-use guidance or alternatives such as reach, move_gun, or pose_clip. An agent must infer the tool's place in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The share of a small disc round a point that the eye sees with nothing (arms, rifle) in the way.
| Name | Required | Description | Default |
|---|---|---|---|
| point | No | a name (a bone such as hand_l, a fingertip such as index_tip_l, a rig point such as port) or [x, y, z] in the frame | port |
| radius_cm | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state the return type (fraction vs percentage), whether it is a read-only query, what 'eye' and 'nothing in the way' imply, or any side effects or permissions.
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 a single sentence with no wasted words, but it is not front-loaded with a clear action or purpose. The structure is adequate but the cryptic phrasing reduces usefulness.
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 a two-parameter tool with no output schema and no annotations, the description is incomplete. It omits parameter guidance, return value format, and behavioral context needed to invoke it 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 50%: the 'point' parameter is documented in the schema, but 'radius_cm' is not. The description adds no parameter information, so it fails to compensate for the gap.
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 defines a metric ('share of a small disc round a point that the eye sees') but lacks an action verb and does not distinguish it from siblings like clearance or faces_eye. It is specific enough to identify the domain (visibility), but the exact operation remains unclear.
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 given about when to use this tool versus alternatives, nor are any prerequisites or contexts mentioned. The description simply states what it computes without usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where bones, fingertips (tip<l|r>) and rig points are, in a frame.
| Name | Required | Description | Default |
|---|---|---|---|
| frame | No | gun: the gun bone, cm (+X gun's left, +Y barrel, +Z up); arms: the arms' space, cm; view: from the eye, cm (+X right, +Y forward, +Z up) | gun |
| names | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only location query but does not explicitly state that it is non-destructive, what it returns, whether results are coordinates or names, or what units apply.
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?
It is a single, tightly written sentence with the resource listed first and the frame context second. There is no wasted wording, though the brevity borders on under-specification rather than ideal conciseness.
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 annotations and no output schema, the description should do more to explain the return shape and how frame coordinates are reported. It also omits routing guidance among the many sibling rig and spatial tools, leaving notable gaps for correct invocation.
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 coverage is 50%: the frame enum is documented in the schema, while names has no schema description. The description compensates partially by giving the fingertip naming pattern `<finger>_tip_<l|r>`, but it does not explain valid rig point or bone name formats.
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 the resource being queried: bones, fingertips, and rig points, and notes that they are located in a frame. However, it does not use a clear query verb such as 'get' or 'returns', and it does not distinguish this tool from spatial siblings like distance, clearance, visible, or describe. The intent is inferable but not crisply differentiated.
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?
There is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives. An agent must infer that this is the right tool when it needs positional data rather than distance, clearance, or visibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0clearancedescribedistancefaces_eyelist_rigsload_rigmove_gunmove_partpose_clippose_idlereachrenderscreensnapshotsolvevisiblewhereScored across 17 tools
Each tool targets a distinct action or spatial question: loading/rig setup, posing modes, rifle/part translation, wrist IK, snapshot save/load, geometry queries, solving, and rendering. Even the eye-related tools (faces_eye, visible, screen) measure different things and are differentiated by their descriptions.
All names are lowercase snake_case, so casing and separators are consistent. The only minor deviation is that some tools are verb-led actions while others are noun/adjective-style queries (where, distance, visible), so it is not a strict verb_noun pattern.
17 tools is slightly above the typical 3-15 range, but the domain is a specialized 3D rig/rifle posing and analysis lab with many distinct operations. Each tool appears to cover a separate capability, so the count is reasonable rather than bloated.
The surface covers the core lifecycle: list/load rigs, describe conventions, reset/clip posing, manipulate rifle and parts, wrist IK, save/load snapshots, spatial diagnostics, goal solving, and rendering. Minor gaps include snapshot management (list/delete) and direct hand-orientation control, but the main workflows are complete.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Build 3D scenes, place cameras and render shots. Previs, storyboards, set design, product and CAD.
3D avatar/asset foundry: text/image -> rigged, validated, engine-ready GLB via x402.
