Skip to main content
Glama

read_vmf

Inspect a .vmf map source to list entities, outputs, and brush counts without compiling; Hammer IDs are preserved so reported items can be found again in the editor.

Instructions

Entities, outputs and brush counts of a .vmf, reported without judgement. Use it to see what a map source contains; use read_vmf_lint to find what is wrong with it. Unlike a compiled .bsp, a VMF keeps Hammer ids, so anything reported here can be found again in the editor. Needs the Python sidecar; see health.

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

Input Schema

NameRequiredDescriptionDefault
gameNoGame profile id. This fork supports only 'l4d2', which is also the default; any other id is refused rather than answered about the wrong game.
pathYesPath to the .vmf, absolute or relative to the repo root.
limitNo
classnameNoRestrict the entity list to one class.
collapseInstancesNoExpand every func_instance first, the way vbsp does at compile time. A map using instances otherwise reads as one entity where there is a whole building: counts are far too low, and outputs crossing an instance look like they target nothing. Off by default because it changes every count and every targetname.

Output Schema

NameRequiredDescriptionDefault
gameYes
pathYes
countsYes
matchedYes
entitiesYes
returnedYes
histogramYes
instancesYes

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 must supply behavior — and it does: output is descriptive not evaluative ('reported without judgement'), results are traceable back to Hammer ids unlike .bsp output, and there is a runtime prerequisite (Python sidecar). It does not state the read-only nature explicitly or discuss result size/pagination at the default limit of 200, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with what is returned, then routing, then format caveat, then prerequisite. Nothing is redundant and each sentence changes how the agent would call or interpret the tool.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers purpose, alternative, format caveat and dependency cleanly. It leaves the collapseInstances cost/benefit to the schema, which handles it well, so the only residual gap is guidance on large maps and the limit parameter.

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 description coverage is 80%, with particularly rich documentation for collapseInstances and game, so the schema does the heavy lifting. The description adds no parameter-level detail beyond implying an entity listing that classname would restrict; baseline 3 is appropriate.

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+resource: entities, outputs and brush counts of a .vmf, and explicitly contrasts with read_vmf_lint. It also distinguishes the format from a compiled .bsp, so an agent can tell which reader applies without opening any schema.

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?

Gives an explicit when-to-use ('see what a map source contains') and a named alternative with its own condition ('use read_vmf_lint to find what is wrong with it'). It also routes the agent to 'health' when the Python sidecar prerequisite matters.

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