Skip to main content
Glama

set_face_material

Assigns a material to selected .vmf faces filtered by solid, existing material, facing or area, normalizing the name to the form vbsp expects and optionally backing up or dry-running the write.

Instructions

Sets the material on selected faces of a .vmf. Until this existed a brush's material was fixed at creation and nothing could change it, which made set_lightmap_scale the odd position of being able to say how finely to light a wall but not what the wall was made of. Selects by solid, material, facing or area. The name is normalised to the form a .vmf stores -- uppercase, no materials/ prefix, no .vmt suffix -- because vbsp resolves it literally and a wrong one is invisible until a player loads the map. Whether the material exists is NOT checked here: use read_game_content for that.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "newMaterial": "<newMaterial>"
    },
    "name": "set_face_material"
  }
}

Input Schema

NameRequiredDescriptionDefault
allNoEvery face of the map. Required when no other criterion is given.
pathYesPath to the .vmf, absolute or relative to the repo root.
backupNoCopy the file to <file>.bak before writing. Nothing is copied on a no-op.
dryRunNoCheck and report without writing. Every verification runs either way.
facingNoOnly faces pointing this way. 'up' is a floor, 'down' a ceiling, 'side' a wall; the cut is at 45 degrees, so a ramp counts as what it is closer to being.
confirmNoRequired (true) to run this tool: it writes or executes.
minAreaNoOnly faces at least this large, in square units.
materialNoOnly faces already carrying this. Substring, case-insensitive.
solidIdsNoOnly faces of these solids.
newMaterialYesMaterial to apply, in any of the usual forms.

Output Schema

NameRequiredDescriptionDefault
pathYes
changedYes
matchedYes
writtenYes
nextStepYes
warningsYes
unchangedYes
backupPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4.2/5.0
Behavior4/5

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

Annotations carry essentially nothing (title only), so the description is doing real work: it warns that materials are normalized to .vmf-stored form, that a wrong name fails silently until a player loads the map, and that existence is not verified. It does not say that existing face materials are overwritten or whether the write is reversible, which is the main remaining gap 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.

Conciseness3/5

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

The tool's identity and constraint are front-loaded, but the middle sentence is a ~35-word historical aside about set_lightmap_scale that conveys little the agent needs to call the tool. It is informative flavor rather than wasted words, yet it dilutes an otherwise tight definition.

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

Completeness4/5

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

For a 10-parameter write tool with no meaningful annotations, the description covers the highest-risk aspects: name normalization, silent failure, and no existence check; an output schema exists so return values needn't be explained, and backup/dryRun/confirm are documented in the schema. It stops short of stating the overwrite semantics of an existing material.

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 100% schema coverage the baseline is 3, but the description adds genuine meaning for newMaterial beyond 'any of the usual forms' — uppercase, no materials/ prefix, no .vmt suffix, and why that matters. It also frames the selection parameters collectively (solid, material, facing, area) so the agent understands they are filters rather than alternatives.

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?

The first sentence states a specific verb and resource ('Sets the material on selected faces of a .vmf') and the following sentence adds the scope of selection ('solid, material, facing or area'). The historical note about materials being fixed at creation makes clear this is the only mutation path for face materials, which separates it from set_lightmap_scale.

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

Usage Guidelines4/5

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

It draws one explicit boundary with an alternative: existence of the material is not validated here and read_game_content should be used for that check. It also implies that some selection criterion is needed, though it doesn't spell out when to use this versus paint_displacement or edit_vmf for broader edits.

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