Skip to main content
Glama

read_vmf_trace

Trace rays or player-sized hulls through a .vmf without compiling, revealing what blocks movement or sight and which brush face is hit, so geometry can be checked before a build.

Instructions

Trace a ray, or a swept player-sized box, through a .vmf -- with no compilation. Answers what a mapper checks by walking the map: what is in the way, how far, which brush and which face. A brush is already an intersection of half-spaces, so this needs no vbsp; the same rays agree with the compiled map's own tracer to under half a unit on the probe map. Use hull: standing for anything about whether a person gets through: a line passes a 24-unit gap that nobody fits.

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>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "read_vmf_trace"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYes
fromYesA point in Hammer units, [x, y, z].
hullNoTrace a player-sized box instead of a line. `standing` is Source's 32x32x72, `crouching` its 32x32x36. A line goes through a 24-unit gap that nobody fits.none
maskNoWhat counts as an obstacle. `sight` sees through clip brushes, `player` does not, `solid` is the world as vbsp builds it. The difference between 'can they see the door' and 'can they reach it'.solid
pathYesPath to the .vmf, absolute or relative to the repo root.
ownersNoOnly trace against these owners, e.g. ["world", "func_detail"]. Absent means every brush in the file, including brush entities.

Output Schema

NameRequiredDescriptionDefault
hitYes
hullYes
maskYes
pathYes
notesYes
pointYes
normalYes
sideIdYes
brushIdYes
excludedYes
fractionYes
materialYes
brushCountYes
startSolidYesThe start was already inside a brush, so the distance means nothing. No brush is named either: a point in a wall is usually in several at once.
distanceUnitsYes
distanceMetresYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A3.9/5.0
Behavior4/5

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

With annotations carrying only a title, the description does real work: it discloses that no compilation or vbsp run is needed, that brushes are treated as half-space intersections, and that results agree with the compiled tracer to under half a unit. It omits cost/performance characteristics and never explicitly says the read is non-mutating, but the accuracy and no-compile claims are substantial behavioral disclosure.

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?

The opening clause is front-loaded with the action and the no-compile payoff, and each following sentence adds a distinct fact (what question it answers, why no vbsp, accuracy bound, hull caveat). Slight waste in repeating the 24-unit gap claim that the schema already states.

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 6-parameter tool with an output schema, the description covers purpose, the compilation-free behavior, and the most consequential parameter choice. Details like path resolution failure behavior and owner filtering are delegated to the schema, which is acceptable given 83% coverage and a declared return schema.

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% and the enum descriptions for `hull` and `mask` are already detailed, so the schema does the heavy lifting. The description's added meaning is limited to restating the hull choice, and its '24-unit gap' line duplicates text already present in the hull schema description, so it barely exceeds the baseline.

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 states a concrete verb and resource ('Trace a ray, or a swept player-sized box, through a .vmf') and frames the output in mapper terms ('what is in the way, how far, which brush and which face'). That framing also separates it from pure-visibility or measurement siblings without needing to name them.

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?

It gives one strong conditional ('Use `hull: standing` for anything about whether a person gets through') plus the rationale that a line passes a 24-unit gap nobody fits. That is parameter-level guidance, however; there is no statement of when to choose this over read_vmf_sightlines, measure_vmf_clearance, or read_vmf_solids, so the routing decision is left implied.

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