Skip to main content
Glama

validate_io

Checks VMF/BSP entity output wiring against the game's FGD to catch missing targets or inputs that pass compile checks but silently do nothing in game.

Instructions

Checks a map's entity wiring against the game's own FGD. read_fgd_class has been able to say what inputs a class has since the beginning and nothing has ever used it to judge a map, so an output aimed at an entity that does not exist, or at an input its class does not have, passes every check here and every check vbsp makes -- and then does nothing in game. That is the quietest failure a map has. Targets the engine resolves at runtime (!activator, !self, !player) are reported as unresolvable rather than as broken, and a class with no FGD schema is not judged at all: absence of a definition is not evidence of a fault. Needs the Python sidecar and the game's FGD.

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

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 or .bsp, absolute or relative to the repo root.
limitNo

Output Schema

NameRequiredDescriptionDefault
gameYes
pathYes
formatYes
findingsYes
nextStepYes
warningsYes
errorCountYes
warningCountYes
classesCheckedYes
connectionCountYes
unresolvedTargetsYes

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 most of the work and does it well: it discloses the two exemptions (runtime-resolved targets like !activator/!self/!player are reported as unresolvable, and classes with no FGD schema are not judged) and the external dependency on the Python sidecar plus FGD. It stops short of stating that the operation is read-only or what the report shape is, though an output schema covers the latter.

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?

The purpose is front-loaded in the opening sentence, but the aside about read_fgd_class having existed since the beginning without being used to judge a map is editorial filler that does not help an agent invoke the tool. The exemptions and prerequisites do earn their place, leaving a paragraph that is useful but noticeably 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?

With an output schema present, the description rightly avoids explaining return values and instead covers the things structured fields cannot: the failure class it targets, the exemptions, and the runtime dependencies. Only the 'limit' parameter's effect on results is left entirely to the schema.

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 67%, and the description adds no parameter-level meaning at all — 'path' is only implied by 'a map's entity wiring', the 'game' profile restriction lives entirely in the schema, and the 'limit' parameter is never mentioned. Baseline 3 is appropriate when the schema carries most of the load.

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?

The first sentence gives a specific verb and resource ('Checks a map's entity wiring against the game's own FGD'), and the following sentences make the scope concrete: entity output targets and input names are validated against class schemas. It is clearly distinguished from the sibling read_fgd_class, which only reports schema data rather than judging a map.

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 description establishes the situation that calls for this tool (silent in-game failures that vbsp does not catch) and states prerequisites ('Needs the Python sidecar and the game's FGD'). It does not explicitly route the agent away from any sibling or say when not to bother, but the context is strong enough to select it confidently.

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