Repository Manager

Explain

rm_gates_explain

Run and inspect two-tier pre-commit gates across repositories: fast stage executes pre-commit hooks, heavy stage executes pre-push tests and checks.

Instructions

Explain (rm_gates). Run and inspect the two-tier (fast/heavy) pre-commit gate across repos.

The single tool that can actually drive both tiers of the two-tier gate model: stage="fast" exercises a repo's pre-commit-stage hooks, stage="heavy" exercises its pre-push-stage hooks (pytest, cargo, uv lock --check, ...) via pre-commit run --hook-stage <stage>.

Input Schema

Name	Required	Description	Default
`repo`	No	Target one repo's latest gate job for 'status'/'explain'/'profile' (alternative to job_id).
`fleet`	No	For 'audit_fail_fast': scan every repository in the workspace rather than the ones named by 'repos'.
`repos`	No	Comma-separated repo names or absolute paths to target. Omit for 'run'/'retest' to target the whole workspace.
`stage`	No	'fast' -> `pre-commit run --hook-stage pre-commit` (formatters/linters, no network/tests). 'heavy' -> `--hook-stage pre-push` (pytest, cargo, `uv lock --check`, ...). For 'run'/'retest'.	fast
`start`	No	For 'phase_direction_here': directory to resolve the repository from (default: this process's current working directory).
`top_n`	No	'profile' with no job_id/repo: how many slowest hooks to report fleet-wide.
`job_id`	No	Target one gate job for 'status'/'explain'/'profile'.
`dry_run`	No	For 'xdist_apply': report what would change without writing. Defaults to True on purpose -- rewriting ~40 repositories' pre-commit configs must be an explicit choice, never the consequence of omitting an argument.
`summary`	No	'status': compact roll-up (counts + failed set) vs the full per-job detail.
`threads`	No	Parallel workers.
`timeout`	No	Per-repo pre-commit timeout in seconds.
`escalate`	No	'retest' only: when a repo's narrowed retest passes every requested hook, also submit a SECOND job for that repo's full wave (a narrowed pass alone is never sufficient evidence of shippability -- see gate_ledger.is_shippable).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.5.1Oct 19, 2026

TDQS

C2.6/5.0

Behavior2/5

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

Annotations declare readOnlyHint=false and destructiveHint=false, i.e. a non-destructive but state-mutating tool; the description never discloses what it writes (job submissions, ledger entries) or that running hooks can modify files via formatters. It adds the fast/heavy hook-stage mechanics, which is useful, but omits side effects and preconditions.

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?

Short and front-loaded, with the two-tier concept stated first and stage mechanics second. Slightly awkward framing ('The single tool that can actually...') costs a little credibility but the prose is not padded.

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

Completeness2/5

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

A 12-parameter tool supporting multiple actions (status/explain/profile/run/retest/audit_fail_fast/xdist_apply/phase_direction_here) gets only a run-focused description; the 'explain' behavior named by the tool itself is never described. An output schema exists, but the description is not adequate for the tool's surface area.

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 description coverage is 100% and each parameter already documents its action and semantics, so the baseline is 3. The description's stage explanation largely restates what the 'stage' schema description already says, adding little beyond the schema.

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

Purpose3/5

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

The description gives a verb and resource ('Run and inspect the two-tier ... pre-commit gate across repos') but never explains what the stated 'explain' action actually returns or analyzes. The claim that it is 'the single tool that can actually drive both tiers' is confusing given the presence of rm_gates_run and rm_gates_retest siblings, so an agent cannot cleanly separate this tool's job from theirs.

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

Usage Guidelines2/5

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

It clarifies what stage="fast" vs "heavy" executes for run/retest, but gives no guidance on when to use this tool rather than rm_gates_status, rm_gates_profile, or rm_gates_run. The routing information is left to the parameter descriptions rather than the tool description.

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

Deploy Server