Skip to main content
Glama

read_vmf_visibility

Checks whether named pairs of points in an uncompiled .vmf can see each other, reports the brush, face, and material blocking each blocked view, and flags endpoints stuck inside geometry.

Instructions

Whether each of several named pairs of points can see each other in an uncompiled .vmf, and what blocks the ones that cannot -- by brush id, face and material. read_sightlines answers a different question on a compiled map: it samples the ground and finds the LONGEST lines. This one answers about sight lines you name, which is what 'does moving this wall break the view from the lobby to the desk' needs. Also reports the nearest surface to each endpoint, so an endpoint accidentally inside geometry is visible as such rather than reported as blind.

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>",
      "pairs": "<pairs>"
    },
    "name": "read_vmf_visibility"
  }
}

Input Schema

NameRequiredDescriptionDefault
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.
pairsYes
ownersNo

Output Schema

NameRequiredDescriptionDefault
pathYes
clearYes
linesYes
notesYes
blockedYes
excludedYes
brushCountYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4.4/5.0
Behavior4/5

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

Annotations carry only a title, so the description bears the disclosure burden, and it delivers unusual value: it states what the report contains (brush id, face, material for blockers), adds a per-endpoint nearest-surface diagnostic that prevents misreading an endpoint-inside-geometry case as a genuine blind result, and implies no map mutation since the file is uncompiled input. It stops short of stating read-only guarantees, resource cost, or the 200-pair cap explicitly.

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 capability statement is front-loaded before the sibling contrast, and the concrete example earns its space by tying the tool to a real workflow. The second and third sentences are long and slightly associative, but no sentence is pure filler.

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

Completeness5/5

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

For a moderately complex spatial-analysis tool, the description covers what is asked, what is returned, the key failure mode (endpoint inside geometry), and the sibling boundary. An output schema exists so return shape need not be spelled out, and the only residual gap — the undocumented owners filter — is minor against the overall coverage.

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?

With 50% schema description coverage, the description should compensate, and it only partially does: it clarifies the semantics of the named pairs and why a name matters ('for the report'), but says nothing about the `owners` parameter, the `path` resolution, or how `mask` values change obstacle classification. The mask enum and point format are already documented in the schema, so the remaining gap is the undocumented owners array.

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 names a specific verb and resource: tests visibility between named point pairs in an uncompiled .vmf and reports blocking geometry by brush id, face and material. It also explicitly disqualifies the nearest look-alike sibling, read_sightlines, by noting that one works on compiled maps and finds longest lines rather than named pairs.

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

Usage Guidelines5/5

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

It contrasts compiled-map sampling (read_sightlines) against this uncompiled, named-pair test, and gives a concrete decision scenario: 'does moving this wall break the view from the lobby to the desk'. That is an explicit when-to-use rule an agent can act on without opening a schema.

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