Skip to main content
Glama

sculpt_displacement

Reshape terrain displacements by flattening, raising, sloping between heights, or adding seeded noise; check if shared edges opened a seam and repair it.

Instructions

Reshapes displacements: flatten, raise, slope between two heights, or add noise. Declarative shapes rather than a table of vertices, and noise takes a seed rather than reaching for a random number generator -- a terrain that cannot be regenerated from what produced it cannot be reviewed, cannot be tested and cannot survive a merge. Sculpting one displacement of a terrain moves the edge it shares with its neighbours, so the result says whether a seam opened and sew_displacements closes 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>",
      "shape": "<shape>"
    },
    "name": "sculpt_displacement"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesPath to the .vmf, absolute or relative to the repo root.
shapeYes
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.
solidIdsNoDisplacements on these brushes.

Output Schema

NameRequiredDescriptionDefault
pathYes
writtenYes
nextStepYes
warningsYes
unchangedYes
backupPathYes
seamsAfterYes
maxDistanceYes
minDistanceYes
verticesMovedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A3.5/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 burden, and it delivers real behavioral context: determinism via seed, the rationale that unreproducible terrain cannot be reviewed or merged, and the seam side-effect on neighbouring displacements. It does not disclose that the tool writes to disk and is gated behind confirm, nor what backup and dryRun actually do — those facts live only in the schema, leaving the mutation profile under-described for an unannotated 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 purpose is front-loaded in the first clause, which is good, but the middle of the description drifts into justification prose ("a terrain that cannot be regenerated from what produced it cannot be reviewed, cannot be tested and cannot survive a merge") that argues a design philosophy instead of instructing the caller. The seed rationale could be one clause rather than a triple-clause sermon.

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 the description needn't enumerate return fields, and it usefully notes the result reports whether a seam opened. But for a mutating, confirm-gated tool with no annotations, it omits the write/backup safety story entirely and never contrasts itself with the sibling sculpting tools, leaving gaps an agent would have to close from the schema alone.

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 83%, so the baseline is 3 and the description mostly restates shape kinds already encoded as const values in the union. It does add meaning for the seed ("same seed, same terrain") by framing it as a reproducibility contract rather than an arbitrary integer, but path, solidIds, backup, dryRun and confirm get no treatment in the description.

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 and resource ("Reshapes displacements") and enumerates the four concrete operations: flatten, raise, slope between two heights, and noise. That enumeration maps directly onto the shape union in the schema, so an agent can tell this apart from read_displacements or paint_displacement without opening anything.

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?

Guidance is present but narrow: the description explains that sculpting a displacement moves the shared edge with neighbours and points to sew_displacements when a seam opens, which is genuine routing advice. It says nothing about when to prefer this over paint_displacement or write_displacement, or when a dryRun/backup pass is warranted, so the broader when-to-use question is left implicit.

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