Skip to main content
Glama

nightward_run

Run pytest after code edits to capture behaviors, compare them with a human-approved baseline, and return a boundary signal identifying unapproved changes.

Instructions

Run the tests, capture behaviors, and return the boundary signal.

Call this after every code edit: nightward_status only reports the last run.
path: what pytest runs (relative to the server's working directory); omit it to
run the project's capture suite ([tool.nightward] path, else ".");
dir: omit it - the server gates the store a human started it with
(`nightward mcp --dir`), and any other store is refused; timeout: seconds
before pytest is stopped (the store is then left untouched and the last
report invalidated).
Returns {boundary, unapproved, changes: [{name, kind, group, judged,
judge_model, judge_reason, judge_replayed, rejected, rejected_by, depth,
ask_human, diff, diff_cut}], judged_same,
not_run (approved behaviors whose test was deselected: not checked), narrowed,
stale, incomplete, generated_at, judge, scrub_rules (custom scrub rules of the run
and what they replaced), env_mismatch (changed behaviors approved on another OS or
Python than this run, or null: tell the human - it never makes a breach
acceptable), capture_coverage ({roots, functions, executed, uncovered}: public functions
no capture test ran, when [tool.nightward] coverage is set, else null - a change
there can't breach the gate; never part of boundary), store (absolute path of the gated
store), path (what pytest ran), warnings: {skipped, failed, errors, deselected,
xfailed, scrubbed,
scrub_unmatched (custom scrub rules that matched nothing), scrub_rules (per custom
rule: values and behaviors it replaced, and whether that changed since the last run),
judge_added (judge ruling files this run added to the store's judge/ dir - a human
commits them with the baseline), pytest_returncode, pytest_output_tail}}.
boundary is one of:
  "intact"     done: no unapproved change;
  "breached"   unapproved changes: fix the code, or ask a human to approve;
  "partial"    nothing unapproved among what ran, but approved behaviors were
               not checked (their test was deselected, see not_run): not done -
               run them (remove the -k/-m selection); you can't waive this;
  "incomplete" nothing unapproved, but capture tests failed or errored
               (see incomplete and pytest_output_tail): fix the tests;
  "stale"      the baseline, capture or rejections moved since the report: run again;
  "unknown"    no report yet: run.
diff is what moved (old "-", new "+"), cut to 40 lines (diff_cut: lines left out;
diff is null once 400 lines are shown): read it to tell an intended change
from a regression. Reading it marks nothing reviewed; don't run `nightward
review` or `nightward view` for the diffs - they record that a human saw them.
Done means boundary == "intact" and stale is false. Behaviors approved with
semantic=True are judged by the judge the humans committed
([tool.nightward] judge in pyproject.toml, or `nightward mcp --judge`);
"judge" says which, and why it was unavailable if it was. This tool cannot
approve changes: a human does that with the nightward CLI.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "nightward_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
dirNo
pathNo
timeoutNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so richly: timeout leaves the store untouched and invalidates the last report, dir is gated by the server, diffs must not be read via review/view because that records human review, and it cannot approve changes. These are non-obvious behavioral facts beyond any structured field.

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?

Purpose is correctly front-loaded and most content is necessary given no output schema, but the description is very long and dumps the entire nested return structure inline (e.g., every field of the changes array and warnings object). That level of field-by-field enumeration burdens readability beyond what a description needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, this complex tool's description still covers invocation, parameter meaning, the full return contract, all six boundary values, and the human-approval boundary. An agent has everything needed to call it and interpret the result correctly.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it does: path is what pytest runs relative to the server working dir (omit for the capture suite), dir should be omitted because the server gates the store, and timeout is seconds before pytest is stopped with a stated side effect. Every parameter gains meaning not present in the bare schema.

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?

First sentence states a specific verb sequence (run tests, capture behaviors, return boundary signal) for a specific resource, and immediately distinguishes from the sibling: 'nightward_status only reports the last run.' An agent can tell the two apart without opening either 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?

Explicit when-to-use ('Call this after every code edit') paired with the named alternative and its limitation. It also states an exclusion ('This tool cannot approve changes: a human does that with the nightward CLI') and defines the done condition ('boundary == intact and stale is false').

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

Deploy Server

Other Tools