Skip to main content
Glama

read_leak

Reads a .lin leak pointfile beside a .vmf or .bsp and names the entities nearest the path start, revealing which entity sees the void. Returns leaked:false when no pointfile exists.

Instructions

Turns a leak into a location. vbsp says only 'leaked!' and writes a .lin pointfile beside the map: this reads it and names the entities nearest to where the path starts, which is the entity that can see the void. Pass the .lin, or the .vmf or .bsp beside it. Both ends of the path are correlated, because vbsp does not guarantee which end holds the entity -- on a two-point pointfile it was the last. No pointfile is an ANSWER, not an error: it returns leaked:false, and compiled tells a map that did not leak from one nothing has compiled here. A .bsp that arrived from somewhere else -- a Workshop .gma, a copy, a download -- carries no .lin and never could, so establishedBy says whether the answer rests on evidence or on the absence of a file that was never going to be there.

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

Input Schema

NameRequiredDescriptionDefault
pathYesThe .lin pointfile, or the .vmf/.bsp it sits beside.
limitNo

Output Schema

NameRequiredDescriptionDefault
endNo
noteYes
startNo
leakedYes
pointsNo
compiledYes
evidenceYes
pointfileYes
spanUnitsNo
pointCountNo
nearestToEndNo
establishedByYes
leakingEntityNo
nearestToStartNo
correlatedAgainstNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A4.1/5.0
Behavior5/5

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

Annotations carry no hints beyond a title, so the description bears the full burden and does so: it explains that both ends of the path are correlated because vbsp does not guarantee which end holds the entity, that a missing pointfile yields leaked:false rather than an error, that `compiled` separates a clean map from an uncompiled one, and that `establishedBy` distinguishes evidence-based answers from absence of a file that could never exist. Those are exactly the non-obvious behaviours an agent would otherwise get wrong.

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 claim ('Turns a leak into a location') before any caveats, and the em-dash asides carry real information rather than padding. The final sentence about Workshop .gma and copied .bsp files is long but earns its place by preventing a false 'clean' conclusion.

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?

The output schema exists, and the description still adds value by explaining how to read `leaked`, `compiled`, and `establishedBy` rather than restating them. What is missing is any statement about what the returned entity listing looks like in shape or ordering, and the meaning of `limit`; everything else an agent needs to call this correctly is present.

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 50%: `path` is documented in the schema and the description reinforces it by listing the three acceptable extensions. `limit` has no schema description at all, and the description only implies it via 'names the entities nearest' without ever saying it caps the number of returned entities or what the default of 5 means.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb+resource and a concrete problem solved: it reads the .lin pointfile that vbsp writes and names the entities nearest where the leak path starts. It even states the underlying goal ('which is the entity that can see the void'). It stops short of distinguishing itself from the sibling read_vmf_leak, which it partially overlaps with by accepting a .vmf, so an agent must infer the split.

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 clear: invoke after vbsp reports 'leaked!', and pass either the .lin or the .vmf/.bsp beside it. It also pre-empts a misread by stating that no pointfile is an ANSWER, not an error, so the agent knows a leaked:false result is not a failure to retry. There is no explicit exclusion or named alternative for the overlapping cases.

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