Skip to main content
Glama

verify_staged

Run whitelisted checks on staged file writes via a temp copy before committing, so linting or typechecking sees new content without changing the target.

Instructions

Run a whitelisted command against a staged write WITHOUT touching the target file: the op's content is materialized to a temp file in the same directory (import/path resolution matches the real file), '{file}' in argv is replaced by the temp path (appended if absent), and the command runs under the command_whitelist. Use it to typecheck/lint a staged op before commit_write — running a checker on the original path sees the OLD on-disk content, not the stage. restore_paths lists files the command may rewrite (e.g. an auto-updated lint baseline) — snapshotted before, restored after. The temp file is always removed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory (must be inside allowed roots); defaults to the file's directory
argvYesWhitelisted command argv; '{file}' is replaced by the materialized temp path
op_idYes
timeout_sNoCommand timeout override (default: run_command_timeout_s config)
restore_pathsNoFiles to snapshot and restore after the run (e.g. auto-rewritten baseline files)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: temp-file materialization in the same directory, argv placeholder substitution and append-if-absent rule, whitelist enforcement, restore_paths snapshot/restore semantics, and guaranteed temp-file cleanup. It leaves little behavioral ambiguity about side effects on the target file.

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?

Dense but front-loaded, leading with the core action and scope before mechanics. Every sentence carries information, though the middle clause about import/path resolution is somewhat run-on and could be tightened.

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 complex 5-param mutation-adjacent tool with no annotations and no output schema, the description covers inputs and side effects thoroughly. The one remaining gap is what the command returns (exit status, stdout/stderr), which an agent would need to interpret the result.

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 80%, so the schema already documents cwd, argv, timeout_s, and restore_paths. The description still adds real meaning: how '{file}' is substituted/appended in argv and how restore_paths are snapshotted and restored. The only gap is op_id, which neither schema nor description clarifies.

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 ('Run a whitelisted command against a staged write') with a precise scope constraint ('WITHOUT touching the target file') that separates it from commit_write and propose_write. An agent can distinguish it from siblings without opening any schema.

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

Usage Guidelines5/5

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

Explicitly prescribes when to use it ('typecheck/lint a staged op before commit_write') and warns why the naive alternative fails ('running a checker on the original path sees the OLD on-disk content'). It names the alternative tool and the condition selecting this one.

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