Skip to main content
Glama

read_vmf_solids

Rebuilds every .vmf brush from its planes to verify it forms a closed convex volume, reporting corner count, bounds, volume and errors such as reversed sides or degenerate planes.

Instructions

Rebuilds every brush of a .vmf from its planes and checks that it is a closed convex volume. Reports each solid's corner count, bounding box and volume, plus what is wrong with it: a side wound the wrong way (the planes then enclose nothing), three collinear points that define no plane, a side that bounds no face, a corner outside the world, a texture axis pointing along its own face normal so the texture stretches without bound. It runs the opposite way round from anything that writes a brush -- planes to volume rather than volume to planes -- which is what makes it usable as an independent check rather than a restatement.

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

Input Schema

NameRequiredDescriptionDefault
gridNoGrid size corners are expected to land on. 1 (default) means integers; 0 disables.
pathYesPath to the .vmf, absolute or relative to the repo root.
limitNoMaximum solids to return. Default 50.
includeNoWhich solids to return. 'invalid' (default) returns only those with an error.
verticesNoInclude every corner's coordinates. Off by default: it is a lot of numbers.

Output Schema

NameRequiredDescriptionDefault
pathYes
solidsYes
returnedYes
truncatedYes
solidCountYes
validCountYes
findingCountsYes
gridHistogramYesSolids per grid size, coarsest first; key '0' means not on whole units.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4/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 does the behavioral work: it discloses that the tool recomputes geometry from planes, that the computation runs in the opposite direction from brush writers, and it itemizes the five defect conditions it flags. It never states outright that the file is left untouched, which is the one piece of behavior an agent still has to infer from the 'read_' name.

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?

Two sentences, front-loaded with the action and result, with the differentiation claim placed last where it lands as a conclusion. The middle clause chains five defect types into one long comma series, which is dense but each item is informative, so nothing is padding.

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 read/validation tool with a full output schema and fully documented parameters, the description supplies the missing conceptual layer: what 'valid' means for a brush and why an independent recomputation is worth running. Return-value explanation is unnecessary given the output schema, and nothing an agent needs to decide to call it is absent.

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 100%, so path, grid, limit, include and vertices are all documented in structured data. The description adds nothing about any of them — notably not about the grid tolerance or the invalid/all filter, which are the parameters most likely to change results. Baseline 3 is appropriate when the schema already does the heavy lifting.

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 operation on a specific resource: rebuilding every brush of a .vmf from its planes and checking for a closed convex volume. It then enumerates exactly what is reported (corner count, bounding box, volume) and the concrete failure classes it detects, so the agent knows the output shape without guessing.

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

Usage Guidelines3/5

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

The closing sentence positions this as an independent check rather than a restatement, and contrasts the direction of computation with 'anything that writes a brush'. That is real guidance, but it is generic — no sibling is named, and no explicit when-to-use/when-not condition is given, which matters here because close siblings like read_brush_volumes and read_vmf_lint sit in the same space.

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