Skip to main content
Glama

read_vmf_rooms

Reads a .vmf's geometry to identify rooms, door openings, and connections without compiling or annotations, helping you determine how many rooms exist and what connects to what.

Instructions

The rooms of a .vmf, the openings between them, and how they connect -- from the geometry alone, with no compilation and no annotation in the file. Rooms come from a watershed on the clearance field, NOT from connected components: a sealed map has exactly one of those. This is a heuristic and it says so, with the parameters that produced it; it can split a hall with a pillar in it and swallow an alcove. Widths are voxel estimates to within a cell. Use it to ask what a place IS -- how many rooms, how wide the doors, what connects to what -- rather than what is at a coordinate.

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

Input Schema

NameRequiredDescriptionDefault
pathYesPath to the .vmf, absolute or relative to the repo root.
stepNoCell size in units. 16 is the coarsest that resolves a 32-unit doorway. Halving it multiplies the cell count by eight.
seedsNoPoints known to be inside. Default: every spawn entity in the map.
maxCellsNo
mergeLimitNoHow many merges to report, newest first-hit last. mergeCount stays exact.
minRoomAreaNoBelow this floor area, in square units, a region is merged into its largest neighbour.

Output Schema

NameRequiredDescriptionDefault
pathYes
notesYes
roomsYes
mergesYes
methodYes
sealedYes
portalsYes
roomCountYes
mergeCountYes
parametersYes
unreachableYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A3.6/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 disclosure burden, and it does a lot: the watershed-on-clearance-field method, why connected components are unusable on a sealed map, known failure modes (splitting a pillared hall, swallowing an alcove), and width tolerance to within a cell. It stops short of covering output structure or the cost implications of the 4M-cell default.

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?

Purpose and the key caveat are front-loaded, and each sentence contributes distinct information rather than restating the schema. The em-dash-heavy, clause-stacked style is dense but not padded.

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 six-parameter geometric analysis tool with a separate output schema and minimal annotations, the description supplies the method, the accuracy regime, and the failure modes an agent needs before committing. The main gap is runtime/cost expectation for large maps, which neither annotations nor description address.

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 most parameters are already documented, including the step/doorway-resolution note. The description adds only indirect value by framing results as a heuristic reported 'with the parameters that produced it' and tying width error to a voxel cell; it gives no guidance on seeds, mergeLimit, or maxCells beyond what the schema states.

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?

The opening clause names a concrete resource (the rooms of a .vmf) and its outputs (openings and connections), and explicitly scopes it to geometry alone with no compilation. It differentiates itself from coordinate-query siblings by contrasting 'what a place IS' with 'what is at a coordinate,' though it never names a specific sibling tool.

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?

The final sentence gives an explicit use case (room counts, doorway widths, connectivity) and an explicit anti-pattern (coordinate lookups). No named alternative is offered for the coordinate case, so routing relies on the agent matching the phrase to sibling names like read_vmf_nearest_surface.

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