Skip to main content
Glama

edit_vmf

Edits a .vmf in place by splicing byte ranges, preserving untouched bytes, and adds, updates, or removes entities and outputs without reserializing the file.

Instructions

Edits a .vmf in place by splicing byte ranges of the original file: everything not touched stays byte-identical, so a one-entity change is a one-entity diff. Adds, updates and removes entities, and adds or removes their outputs. Never reserialises the file: comments, blank lines and hand-written indentation would be lost silently. Does not create brush geometry -- that is write_vmf_solid, which has the checks that job needs. Run read_vmf_lint after editing.

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>",
      "ops": "<ops>"
    },
    "name": "edit_vmf"
  }
}

Input Schema

NameRequiredDescriptionDefault
opsYes
pathYesPath to the .vmf, absolute or relative to the repo root.
backupNoCopy the file to <file>.bak before writing. Nothing is copied on a no-op.
dryRunNoCheck and report without writing. Every verification runs either way.
confirmNoRequired (true) to run this tool: it writes or executes.

Output Schema

NameRequiredDescriptionDefault
noteYes
pathYes
dryRunYes
writtenYes
outcomesYes
warningsYes
unchangedYesTrue when the ops produced the exact same bytes. Nothing is written then.
backupPathYes
bytesAfterYes
bytesBeforeYes
entitiesAfterYes
entitiesBeforeYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A3.9/5.0
Behavior3/5

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

With only a title annotation, the description carries the burden, and it does disclose real behavior: minimal diffs, no reserialisation, and silent loss of comments/blank lines/indentation if that contract were broken. It says nothing about atomicity, what happens when a match hits zero or many entities, partial failure of an op array, or permission requirements — gaps that matter for a mutation tool.

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-loaded with the core mechanism, then operations, then the invariant, then the alternative and follow-up — a logical, waste-free ordering. The reserialisation sentence is slightly redundant with the byte-identical claim, though it justifies the design rather than merely repeating it.

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 and parameter coverage is high, so return values and argument details need not be restated. What remains missing is failure-mode context (unmatched matches, mid-array errors) and the confirm/backup behavior, which are only discoverable in 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 coverage is 80%, so the schema already documents path, keys, match fields, id-vs-index preference, and value syntax. The description's operation list loosely maps to the op enum but adds no detail on backup, dryRun, confirm, or match semantics beyond what the schema states. Baseline 3 applies.

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 concrete verb and resource plus the exact mechanism ('splices byte ranges of the original file') and enumerates the operations: add, update, remove entities and add/remove outputs. It also explicitly excludes a sibling ('Does not create brush geometry -- that is write_vmf_solid'), so an agent can distinguish it without opening another schema.

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 clear positive guidance (in-place entity/output edits) and an explicit exclusion with the alternative named (write_vmf_solid for brush geometry), plus a mandated follow-up ('Run read_vmf_lint after editing'). It stops short of saying when to prefer a full rewrite via write_vmf or when in-place editing is inappropriate.

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