Skip to main content
Glama

write_displacement

Creates 5x5, 9x9, or 17x17 displacement grids on selected VMF brush faces for terrain sculpting, and refuses faces that already have a displacement to protect existing work.

Instructions

Creates displacements on selected faces: the vertex grids that make every piece of terrain in Source. Power 2, 3 or 4, which are 5x5, 9x9 and 17x17 grids -- Source accepts 0 and 1 and no terrain is built with them. Flat by default, which is what Hammer's own create makes and what a mapper then sculpts. WARNING: a displacement does not seal. vbsp builds the hull from the brush's own planes and draws the terrain over it, so displacing a face of the map's shell leaks through a shape the terrain no longer has, and the leak names a brush that looks solid in the editor. Refuses a face that already carries one rather than discarding what was sculpted onto 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>",
      "power": "<power>"
    },
    "name": "write_displacement"
  }
}

Input Schema

NameRequiredDescriptionDefault
allNoEvery quadrilateral face of the map. Required when nothing else narrows it.
pathYesPath to the .vmf, absolute or relative to the repo root.
powerYes2, 3 or 4: a 5x5, 9x9 or 17x17 grid.
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.
facingNo
confirmNoRequired (true) to run this tool: it writes or executes.
minAreaNo
materialNoFaces carrying this. Substring, case-insensitive.
solidIdsNo

Output Schema

NameRequiredDescriptionDefault
pathYes
createdYes
matchedYes
writtenYes
nextStepYes
warningsYes
unchangedYes
backupPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4/5.0
Behavior4/5

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

With no meaningful annotations beyond a title, the description carries the full burden and it discloses real behavioral traits: the refusal on already-displaced faces, the flat default, and the leak consequence where 'the leak names a brush that looks solid in the editor.' It doesn't mention that confirm=true is required to execute or how backup/dryRun interact with the write, leaving a 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.

Conciseness4/5

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

It's a single dense paragraph that stays on topic and puts the creation semantics before the warning, with the destructive failure mode called out in capitals. Some clauses, such as the grid-dimension restatement of power, repeat what the schema already says, but there is little true waste.

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?

For a 10-parameter write tool, the description covers purpose, defaults, and the main failure mode well, and an output schema exists to explain returns. What it omits is how the face-selection parameters combine (all vs facing vs material vs solidIds) and the confirm gating, which an agent needs before invoking a mutating tool.

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

Parameters3/5

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

Schema coverage is 70%, so the baseline is 3. The description does add meaning for power by noting Source accepts 0 and 1 but no terrain uses them, and explains the flat default. However, the selection parameters (all, facing, material, solidIds, minArea) are never explained in the description, so it doesn't fully compensate for the coverage gap.

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 description gives a specific verb and resource — 'Creates displacements on selected faces' — and defines the term inline as 'the vertex grids that make every piece of terrain in Source.' It also implicitly separates this tool from the sculpting and painting siblings by noting the result is 'Flat by default... what a mapper then sculpts.'

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 clearly establishes the use case (initial creation on faces that have none) and a when-not condition: it 'Refuses a face that already carries one rather than discarding what was sculpted onto it,' which routes an agent away from re-running it on existing terrain. It gives a strong contextual warning about where not to displace (the map's shell). It never names an alternative sibling tool such as sculpt_displacement, so it stops short of the top score.

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