MPFB MCP

Official

Overview Schema Source Related Servers Discussions Admin

mpfb_set_face_units

DestructiveIdempotent

Set ARKit face units (0.0-1.0) on a MakeHuman character to compose facial expressions, with merge or replace modes and validation.

Instructions

Compose a MakeHuman character's face from ARKit face units - the same 52-unit vocabulary mpfb_get_face_units reads and MPFB's own composer panel edits, applied directly to the !ex- shape keys.

Send the whole expression as one call. face_units is a list of {face_unit, value}, value in 0.0-1.0. Call mpfb_get_face_units first if you need the exact 52 legal names, grouped by region in known_face_units.

Nothing is written unless every name resolves. Every face_unit is checked against MPFB's own vocabulary before anything is touched; one misspelled name refuses the whole call and unknown_face_units names it together with the closest legal spellings. This tool also refuses outright when the faceunits01 asset pack is not installed, since every target file would then be missing - check mpfb_get_face_units' faceunits01_installed first if unsure.

mode is "merge" by default, matching MPFB: a face unit not mentioned in face_units is left exactly as it was. "replace" zeroes every one of the 52 units before applying this call's entries, which is the difference between "smile a bit more" and "make this face and nothing else"; removed_by_replace names what it zeroed.

refit (default true, unlike every other refitting tool here: composing is normally one call) re-fits the mesh assets and the rig afterwards.

A composed face is transient. MPFB has two mechanisms over one set of shape keys: this tool writes them directly, while saved expressions live on a stack (mpfb_get_expression) that mpfb_apply_expressions and preset loads rebuild the face from, discarding anything composed here. result's matches_stack is false when the face now differs from the stack, and unexplained_face_units lists what the next rebuild would overwrite. mpfb_save_expression keeps a composed face.

result carries changes - one entry per unit actually written, with previous_value and new_value - plus loaded_from_disk (units whose shape key had to be created from a target file on this call), could_not_load (a unit whose target file was missing even though the pack passed its own install probe - a partially installed pack), and skipped_absent_at_zero (a unit requested at 0.0 with no shape key yet, which is left alone rather than created). basemesh_name names the object actually changed. A subject that cannot be resolved (found: false, subject_not_found) and a basemesh in edit mode (ready: false) are answers, not errors.

Input Schema

TableJSON Schema

Name	Required	Default
`mode`	No	merge
`name`	No
`refit`	No
`face_units`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover the safety profile (destructiveHint=true, idempotentHint=true), and the description goes well beyond them: all-or-nothing validation before any write, refusal when the asset pack is missing, merge-vs-replace zeroing semantics, refit defaulting to true, and the transient nature of a composed face relative to the expression stack. This is unusually rich behavioral disclosure for a mutation tool.

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

Conciseness4/5

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

It is long, but it is front-loaded with the action and the 'send the whole expression as one call' instruction, and each bolded paragraph covers a distinct concern (vocabulary, validation, mode, refit, transience, result fields). Nearly every sentence earns its place, though the result-field inventory is dense enough that it slightly overshoots what an agent needs up front.

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

Completeness5/5

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

An output schema exists, yet the description still clarifies the ambiguous result fields (`matches_stack`, `unexplained_face_units`, `removed_by_replace`) and explicitly frames non-error answers (`found: false`, `ready: false`). For a 4-param mutation tool with 0% schema coverage and multiple interacting modes, nothing material is missing.

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

Parameters4/5

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

Schema description coverage is 0%, so the description carries the burden and largely does: `mode` merge/replace semantics and default, `refit` meaning and non-standard default, and the `{face_unit, value}` shape with `value` in 0.0-1.0. The `name` parameter is only obliquely referenced via 'a subject that cannot be resolved', leaving its role as the target subject implicit rather than stated.

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

Purpose5/5

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

States a specific verb and resource ('Compose a MakeHuman character's face from ARKit face units') and immediately fixes the vocabulary and the target ('!ex-' shape keys). It explicitly distinguishes itself from the sibling reader `mpfb_get_face_units` and from the stack-based `mpfb_apply_expressions`, so an agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use guidance ('Send the whole expression as one call', call `mpfb_get_face_units` first for legal names) and explicit alternatives ('`mpfb_save_expression` keeps a composed face', while `mpfb_apply_expressions` and preset loads discard composed work). It also states the precondition that the `faceunits01` pack must be installed.

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