Repository Manager

Xdist Plan

rm_gates_xdist_plan

Run and inspect two-tier pre-commit gates across repositories: execute fast pre-commit or heavy pre-push hooks, then report status, failures, and profiles for gate audits.

Instructions

Xdist plan (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.7/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is partly covered. The description adds useful context about what 'heavy' actually executes (pytest, cargo, `uv lock --check`, pre-commit run --hook-stage) and that heavy work touches the network/tests, but it does not disclose concurrency/timeout side effects, what a plan versus an actual run produces, or any permission requirements.

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?

The first sentence is front-loaded and useful, but the second paragraph opens with a promotional claim ('The single tool that can actually drive both tiers') that is unsupported and arguably false given sibling gate tools, and then re-explains the stage enum that the schema already covers. It is not bloated, but it spends words on redundancy and self-promotion.

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?

The input schema exposes no 'action' parameter, yet the description and every parameter description route behavior by action ('status', 'explain', 'profile', 'run', 'retest', 'xdist_apply', 'audit_fail_fast', 'phase_direction_here'). With 12 optional parameters and no documented way to select the operation, the agent lacks the single most important piece of information needed to call this tool correctly.

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%, so the schema already documents all 12 parameters including the stage enum and the dry_run safety default, making 3 the correct baseline. The description's explanation of fast/heavy largely restates the stage field rather than adding syntax or interaction semantics beyond it.

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 does name a concrete resource (the two-tier fast/heavy pre-commit gate across repos) and a verb ('Run and inspect'), and it distinguishes itself by claiming to be 'the single tool that can actually drive both tiers.' But that claim sits in tension with the tool's own name ('Xdist Plan') and with siblings like rm_gates_run, rm_gates_retest and rm_gates_status, so an agent cannot cleanly tell whether this plans, runs, or both.

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 never states when to choose this tool over rm_gates_run, rm_gates_retest, rm_gates_status, rm_gates_explain or rm_gates_profile, even though it references those tools' action names ('status'/'explain'/'profile'/'run'/'retest'/'xdist_apply'). There are no exclusions and no prerequisites, so routing decisions are left entirely to inference.

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

Deploy Server