Skip to main content
Glama

read_vmf_leak

Detect whether a .vmf map is sealed without compiling: flood open space from spawn points and report leak paths like a .lin pointfile, so geometry can be fixed before running vbsp.

Instructions

Whether a .vmf is sealed, WITHOUT compiling it. Today the only thing that can answer is vbsp, which costs a toolchain and minutes, and which refuses to run vvis afterwards. This floods the open space from a point inside -- a spawn entity, by default -- and reports where the flood got out, with the path to follow, the same shape as the .lin pointfile. A wall thinner than the cell size is not resolved, so this can miss a leak; it does not invent one, because a cell counts as free only when its whole interior is.

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_leak"
  }
}

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

Output Schema

NameRequiredDescriptionDefault
pathYes
stepYes
cellsYes
notesYes
seedsYes
sealedYes
leakPathYes
escapedAtYes
openCellCountYes
openVolumeUnitsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4.1/5.0
Behavior4/5

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

With no meaningful annotations, the description carries the burden and does well: it discloses the algorithm (flood fill from inside points), the default seed source (spawn entities), and the result shape (path following, like a .lin pointfile). It also discloses a real limitation — walls thinner than the cell size are missed, so false negatives are possible while false positives are not. Missing: performance/cost behavior for large maxCells values and error handling.

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?

Front-loads the core claim, then justifies it, then explains mechanism and caveat — a sound order. Some phrasing is awkward and dense ('This floods the open space from a point inside'), but nearly every sentence carries non-redundant information.

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 4-parameter analysis tool with an output schema, this covers purpose, mechanism, defaults, and known false-negative risk. The gaps are marginal: cost characteristics tied to maxCells and what happens when path is invalid or unreadable.

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 75% and already documents path, step, and seeds, including the 32-unit doorway rationale and the halving-cost note. The description reinforces 'seeds default to spawn entities' and ties thin-wall miss risk to cell size, which adds modest meaning, but it never explains maxCells — the one undocumented parameter.

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 — determine whether a .vmf is sealed — plus the key differentiator 'WITHOUT compiling it'. That contrast with vbsp/vvis makes it immediately distinguishable from compile-based siblings like read_leak and read_vmf_lint.

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?

Gives a clear when-to-use case: the only current alternative is vbsp, which 'costs a toolchain and minutes' and blocks vvis. That is an explicit alternative and the condition selecting this tool. It stops short of naming a sibling tool or stating when this tool is the wrong choice (e.g. versus a compiled .lin read).

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