MPFB MCP

Official

Overview Schema Source Related Servers Discussions Admin

mpfb_save_expression

Destructive

Save a MakeHuman character's live face as a named expression file for reuse with apply_expressions and presets. Writes outside the .blend; character unchanged.

Instructions

Save a MakeHuman character's live face - every non-zero ARKit face unit

as a named expression file that mpfb_apply_expressions can apply and presets can carry. This writes a file outside the .blend, and nothing in Blender can undo it. The character is not changed.

expression_name is a name, never a path: the file is <expression_name>.json in the expressions directory of MPFB's user data, and path and fragment are in every answer. Same rule as preset names: letters, digits, _, -, ., at most 64 characters, no leading dot.

What is saved is the whole live face, including what applied expressions contribute. To make it durable, call mpfb_apply_expressions with mode: "replace" and the new fragment at 1.0 - replace, not merge, or the stack counts twice. result's apply_with holds exactly those arguments.

overwrite (default false) refuses an existing file (blocked_by: "expression_exists", file_before giving its size and age); the directory is shared with installed asset packs. Other refusals, nothing written: name_shadowed (a same-named file in a higher-priority data root would hide this one from MPFB for good - shadowed_by names it), empty_expression (every unit is 0.0), subject_not_found.

Optional metadata, stored as given: description, tags (list of strings), author, copyright, license (default "CC0", MPFB's composer default), homepage. On success result also carries face_units and metadata as read back from the file, overwrote, and panel_synced (whether MPFB's library panel gained the slider).

Input Schema

TableJSON Schema

Name	Required	Default
`name`	No
`tags`	No
`author`	No
`license`	No	CC0
`homepage`	No
`copyright`	No
`overwrite`	No
`description`	No
`expression_name`	Yes

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 already flag destructiveHint=true and readOnlyHint=false; the description adds context beyond them: the write targets a file outside the .blend, nothing in Blender can undo it, the character itself is unchanged, the directory is shared with asset packs, and `name_shadowed` can hide a file permanently. This is exactly the deeper behavioral context the annotations don't carry.

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?

Front-loaded with purpose and the irreversible-write warning, then naming rules, then side effects. Dense but nearly every sentence earns its place; the parenthetical error-code detail is heavy but useful. Slightly verbose overall.

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 helpfully notes what `result` carries (`path`, `fragment`, `face_units`, `metadata`, `overwrote`, `panel_synced`, `apply_with`). Combined with refusal handling and metadata semantics, it is complete for a destructive 9-param file-writing tool.

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?

With 0% schema coverage the description must carry the load, and it does: naming rules for `expression_name`, `overwrite` default and behavior, and the metadata fields (`license` default "CC0", stored as given). However the schema also exposes a `name` parameter that the description never mentions, leaving one of nine params unexplained.

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+resource (save a live face as a named expression file) with precise scope ('every non-zero ARKit face unit'). It explicitly distinguishes itself from `mpfb_apply_expressions` and presets, so an agent can route correctly without opening schemas.

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?

Names the alternative (`mpfb_apply_expressions` with `mode: "replace"` at 1.0) and explains exactly why replace-vs-merge matters, plus when `overwrite` is needed. Refusal conditions (`name_shadowed`, `empty_expression`, `subject_not_found`) act as explicit when-not guidance.

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