Skip to main content
Glama

read_vmf_lint

Checks a .vmf against the game FGD and compiler rules to find unknown classes, invalid targets, bad texture scales, displacement errors, and L4D2 campaign issues before a long compile fails.

Instructions

Checks a .vmf against the game's FGD and against what the compilers accept, before a compile that can take forty minutes to fail. Finds unknown classes and keyvalues, outputs aimed at nothing, inputs a target class does not answer to, texture scales that become 'Bad surface extents', displacements on brush entities (with the real brush id, which vbsp does not print), props standing below the floor they were placed on because their model's origin is at its centre, and counts that approach the compiler limits. Knows the entities the installed FGD declares, so a class the game has is not reported as unknown. L4D2 campaign rules are included: a non-L4D2 changelevel, a missing landmark or checkpoint door, and a Standard finale are reported. Needs the Python sidecar and the Left 4 Dead 2 install; 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_lint"
  }
}

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.
ruleNoKeep only findings from this rule.
limitNo
severityNoKeep only findings at this severity.
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
totalYes
byRuleYes
countsYes
matchedYes
findingsYes
returnedYes
instancesYes
nearLimitYes
bySeverityYes
fgdsLoadedYes
toleratedHelpersYes

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 beyond a title, the description carries the disclosure burden and mostly succeeds: it describes false-positive avoidance ('knows the entities the installed FGD declares, so a class the game has is not reported as unknown'), the L4D2 campaign-rule coverage, and the environmental prerequisites (Python sidecar, L4D2 install). It does not explicitly state that it is a non-mutating read or mention runtime/performance, which keeps it just 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.

Conciseness3/5

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

It is front-loaded with the core purpose and every clause is substantive, but the body is a single long run-on enumeration (~145 words) with no sentence breaks or grouping, making the list of finding categories harder to scan than it needs to be. Length is defensible for a complex lint tool, but the structure costs it.

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 lint tool with six parameters and an output schema, the description covers what is checked, what false positives are avoided, game-specific rules, and prerequisites. Since an output schema exists, return-value detail is correctly omitted.

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 83%, so the schema already explains path, game, rule, severity, limit and the important collapseInstances semantics. The description adds no parameter-level meaning of its own, so the baseline of 3 applies — adequate because the schema does the work.

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 — checks a .vmf against the game's FGD and against what the compilers accept — and enumerates concrete finding categories (unknown classes/keyvalues, outputs aimed at nothing, bad texture scales, displacements, limit counts). This clearly separates it from siblings like read_vmf (parse) and check_vmf_rules (rules), and the pre-compile framing tells an agent exactly what it is for.

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?

Usage context is explicit and memorable: run it 'before a compile that can take forty minutes to fail', plus a named entry point ('see health') for prerequisites. It does not explicitly contrast itself with the rules-checking or entity-report siblings, so an agent must infer that boundary, but the when-to-use guidance itself is strong.

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