MPFB MCP

Official

Overview Schema Source Related Servers Discussions Admin

mpfb_set_asset_material

Destructive

Swap the material on an equipped MHCLO asset for an alternative shipped beside it, or restore the asset's own default material by asset object name.

Instructions

Replace the material on an equipped MHCLO asset with one of the alternatives that ship beside it - a hat in another colour - or put the asset's own material back.

name is required and is the asset's own Blender object name, as mpfb_list_objects reports it or as mpfb_add_asset returned it in asset_object_name - not the character's. There is no active-object fallback: this destroys that object's current material.

Name the material with either path or fragment, never both. Both come from mpfb_list_asset_materials, the only catalogue for them: alternative materials sit in the asset's own directory rather than in an asset library section, so mpfb_list_assets does not know about them.

restore_default (default false) instead puts back the material named by the asset's own MHCLO and clears the recorded alternative_material. It cannot be combined with path or fragment.

MPFB has no service-level "set an alternative material" - the logic exists only in its asset library panel - and two of that panel's quirks are reproduced here rather than tidied up, because tidying them would make the result differ from what a user gets from the panel: the new material is always a MakeSkin material named makeskinmaterial, whatever the asset had before, and the slots are popped rather than deleted, so node groups from the previous material survive. The viewport display colour comes from MPFB's per-type table keyed on the asset's object_type, so an asset mislabelled when it was equipped gets the wrong colour here too; diffuse_color_from reports which type was used and is null when the neutral grey fallback applied.

On applied: true, result carries asset_object_name, object_type, asset_subdir, path_resolved_by/resolved_path, alternative_material (the fragment now recorded on the object, empty when the default was restored) beside alternative_material_before, materials_destroyed, material_name and diffuse_color_from.

Refusals come back as applied: false (and so performed: false) with a blocked_by and a sentence: subject_not_found, not_an_mpfb_object, material_not_found, not_object_mode, asset_source_missing and default_material_not_found (both for restore_default on an asset whose own MHCLO cannot be found or names no material on disk), and type_not_supported for a Basemesh, Proxymeshes or Skeleton - MPFB's own panel refuses all three, and the first two have a skin rather than an asset material, which is mpfb_set_skin's job.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	No
`fragment`	No
`restore_default`	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.9/5.0

Behavior5/5

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

Annotations only declare destructive/non-idempotent; the description adds far more: the result is always a MakeSkin material named `makeskinmaterial`, slots are popped rather than deleted so old node groups survive, viewport colour derives from a per-type table, and the specific `blocked_by` refusal codes. It also discloses the `materials_destroyed` consequence of the required `name` and the absence of an active-object fallback.

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?

Purpose is front-loaded and the paragraphs map cleanly to mode selection, quirk disclosure, and refusals. It is dense rather than rambling, but the enumeration of result fields (`asset_object_name`, `object_type`, `path_resolved_by`, etc.) is partly redundant given an output schema exists, and could be trimmed.

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?

For a destructive, mode-switching tool with zero schema coverage and unusual upstream quirks, the description covers sourcing, exclusivity, side effects, and failure taxonomy. Nothing an agent needs to call it correctly is missing, and the duplicated result-field list is harmless surplus rather than a gap.

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

Parameters5/5

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

Schema coverage is 0%, so the description carries the full burden and does: `name` is described as the asset's own Blender object name (sourced from mpfb_list_objects or mpfb_add_asset's `asset_object_name`, never the character), `path`/`fragment` are given a source and an XOR rule, and `restore_default` is given its default and its incompatibility. All four parameters gain semantics absent from the schema.

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

Purpose5/5

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

First sentence states a precise verb+resource+scope: replace an equipped MHCLO asset's material with a shipped alternative, or restore the asset's own material. It explicitly names where the material data lives (mpfb_list_asset_materials, not mpfb_list_assets) and routes skin-bearing types to mpfb_set_skin, so an agent can separate it from every sibling.

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 mutually-exclusive modes: either `path` or `fragment`, never both; `restore_default` cannot be combined with either. It names the only catalogue for path/fragment and states the signs under which the tool refuses (Basemesh/Proxymeshes/Skeleton), pointing to mpfb_set_skin as the alternative. Exclusions are stated, not implied.

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