Skip to main content
Glama

run_pack

Embeds custom assets into a compiled .bsp with bspzip so maps don't show purple checkerboards on clients missing them; can auto-derive the list from loose files the map references.

Instructions

Packs files into a compiled .bsp with bspzip, so custom assets ship with the map instead of appearing as purple checkerboards on every client that lacks them. Takes explicit pairs of in-game path and source file. With auto:true it also derives the list from the map itself, via read_map_dependencies: every asset the map references that resolves from a LOOSE file in the game's content tree rather than from a VPK. Those are the ones that ship broken -- they work at home because they are on that disk. VPK content is never packed: every player who owns the game has it. The derived list is returned, so what was packed is visible rather than inferred. Verifies afterwards by re-reading the pakfile: bspzip reports success whether or not anything was added.

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": {
      "bsp": "<bsp>"
    },
    "name": "run_pack"
  }
}

Input Schema

NameRequiredDescriptionDefault
bspYesTarget .bsp. It is rewritten in place.
autoNoDerive the list from the map: assets it references that sit loose in the game's content tree rather than in a VPK. Needs the Python sidecar.
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.
filesNoExplicit pairs. Required unless auto is set; combined with it otherwise.
confirmNo
excludeNoSubstrings of in-game paths auto should skip. For the occasional stock file that ships loose -- Garry's Mod keeps detail.vbsp in its own root -- which auto would otherwise pack harmlessly but pointlessly.
toolchainNoWhich compilers to drive. The default 'plusplus' is ficool2's Hammer++ rebuild: much faster vvis and flags the stock chain does not have. Falls back to 'stock' when it is not installed, and the result says which one ran. 'stock' forces the compilers that ship with the game, which is what a comparison between the two needs.plusplus

Output Schema

NameRequiredDescriptionDefault
okYes
bspYes
gameYes
addedYes
derivedYes
autoNoteNo
exitCodeYes
requestedYes
toolchainYes
bytesAfterYes
filesAfterYes
stdoutTailYes
bytesBeforeYes
filesBeforeYes
toolchainNoteYes
missingSourcesYes
toolchainRequestedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4.5/5.0
Behavior5/5

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

Only a title annotation is supplied, so the description carries the full burden and does so: it discloses in-place rewriting, that the derived list is returned rather than inferred, and the important caveat that bspzip reports success even when nothing was added, hence the post-hoc pakfile re-read verification. It also explains the rationale for excluding loose stock files and how the toolchain falls back.

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 purpose, then modes, then rationale, then the verification caveat -- a sensible ordering with no filler. It runs long and repeats some schema content (in-place rewrite, l4d2-only, plusplus fallback), which keeps it from a 5.

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?

For a mutating, multi-mode tool with seven parameters, it covers the decision points an agent needs and an output schema exists so return shape need not be spelled out. The one real hole is the confirm parameter and its default, left unexplained by both schema and description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 86%, so the baseline is 3; the description adds conceptual meaning beyond the schema for auto (derives from map references resolved from loose files, not VPK), exclude (why stock loose files would otherwise be packed pointlessly), and the combination of files with auto. It never mentions the confirm parameter, which is undocumented in both places and is material for a mutating tool.

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 -- packs files into a compiled .bsp with bspzip -- and immediately frames the outcome users care about (assets ship with the map instead of purple checkerboards). This clearly separates it from run_vpk_pack and run_pakfile_extract without needing their schemas.

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?

Explains the two modes well: explicit in-game/source pairs, or auto:true which derives the list from the map via read_map_dependencies. It also names the scope exclusion that VPK content is never packed, which tells the agent what this tool will not do. It stops short of explicit sibling routing (e.g. when to prefer run_vpk_pack), so it is not a full 5.

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