Skip to main content
Glama

paint_displacement

Paints displacement blend channels uniformly, by height, or by slope so blend materials display textures correctly; warns when a material has no blend shader.

Instructions

Paints the blend channel of displacements: uniform, by height, or by slope. A blend material draws its second texture where alpha is 255 and its first where it is zero, which is how a gravel path appears through grass. By height fades between two elevations rather than stepping, because a shoreline that changes in one vertex is not what anyone wants. Says so when the material has no blend in its name: alpha does nothing on a material that is not a blend shader, and vbsp does not mention it.

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>",
      "rule": "<rule>"
    },
    "name": "paint_displacement"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesPath to the .vmf, absolute or relative to the repo root.
ruleYes
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.
confirmNoRequired (true) to run this tool: it writes or executes.
solidIdsNo

Output Schema

NameRequiredDescriptionDefault
pathYes
writtenYes
maxAlphaYes
minAlphaYes
nextStepYes
warningsYes
unchangedYes
backupPathYes
verticesPaintedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

B3.4/5.0
Behavior3/5

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

Annotations carry only a title, so the description bears the full behavioral burden. It usefully discloses a silent no-op condition (non-blend material, vbsp ignores alpha), but says nothing about the mutation itself: what file state is changed, that a backup is made, that confirm is needed, or how failures are reported. The domain detail is genuinely additive but the write/risk profile is left to 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.

Conciseness3/5

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

The purpose is front-loaded in the first clause, which is good, but the body drifts into illustrative asides ('which is how a gravel path appears through grass') and editorializing ('is not what anyone wants'), and the final clause about vbsp is syntactically muddled. It is informative but not tight.

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

Completeness3/5

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

An output schema exists, so return values need no explanation, and schema descriptions cover backup/dryRun/confirm. What is missing is scope and safety framing for a write tool with no annotation hints: whether all displacements or only solidIds are painted, and what happens on partial failure. Adequate for the core purpose, incomplete for a mutation 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?

Schema coverage is 67%, and the description goes beyond it for the most important parameter: it explains that alpha 255 selects the second texture and alpha 0 the first, and that by-height fades between elevations rather than stepping in a single vertex. That is real semantic meaning the schema's bare min/max does not convey. It adds nothing for solidIds, backup, dryRun, or confirm, which is why it stops at 4.

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

Purpose4/5

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

States a specific verb and resource ('Paints the blend channel of displacements') and immediately enumerates the three modes (uniform, by height, by slope), which map one-to-one onto the `rule` union. An agent can tell what the tool does without opening the schema. It does not name or distinguish itself from sibling tools like sculpt_displacement or write_displacement, which keeps it below a 5.

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

Usage Guidelines3/5

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

Usage context is implied by explaining what each blend mode produces (gravel path through grass, shoreline fading) and by a real caveat: alpha does nothing on a material that is not a blend shader. However there is no explicit when-to-use / when-not-to-use routing against the other displacement tools, so the agent must infer the choice.

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