Repository Manager

Withdraw

rm_merge_queue_withdraw

Remove a pending candidate branch from a repository's serialized merge queue, optionally recording why it is being withdrawn.

Instructions

Withdraw (rm_merge_queue). Serialized merge queue for ANY git repository (CONCEPT:RM-MERGE-QUEUE).

The canonical driver of parallel development: lanes take worktrees, work, then hand branches here, and the queue gates them as merged, fast-forwards the base, and prunes the worktree and branch. Set push false when a scheduler must leave publication to phased push.

The queue does not know what a gate is. Gates are declared in the target repository's own .mergequeue.yaml — a command, a tier, a timeout, and how to compare its result against the base ref. agent-connector-sdk declares pytest + ruff + its contract scripts; epistemic-graph declares cargo check --all-features + clippy; a docs repo could declare only a link check. A repository with no declaration is REFUSED rather than defaulted, because "declared no gates" and "has no queue configured" must not be the same value.

Gating is differential: only a failure the base ref does not already produce blocks a candidate — the base is legitimately red here, and an absolute gate once deadlocked a queue and stranded 19 branches. A baseline that cannot be produced REFUSES the candidate; it never degrades to allow-all.

run holds that repository's reconciliation-merge LEASE. If another runner holds it the call returns deferred: true with the holder — defer, do not retry in a loop.

landed vs pushed (D-W3WPS-3). Each outcome carries both, separately: landed means the declared base ref fast-forwarded in the LOCAL canonical checkout (proven by re-reading it); when push is true, pushed means that commit also reached the configured remote via the repo's own gated push path (_gate_before_push + push_project — the same pre-commit gates and GH013/divergent-remote handling a manual push gets). With push false, publication is deliberately deferred to the phased-push scheduler. A push failure never fails the landing — landed: true, pushed: false is a legitimate, visible intermediate state; check push_error on the outcome for why. The queue's own run summary also reports pushed/landed_unpushed counts.

Input Schema

Name	Required	Description
`base`	No	Branch to land onto. Defaults to the repo's declared base.
`push`	No	Publish a landed base through the repository's gated push path. Set false for the fast queue timer; the phased-push scheduler then owns publication.
`prune`	No	Remove each landed candidate's worktree and branch through the guarded prune (merge-base re-checked at delete time, a refs/lane-backup anchor written first, `git branch -d` never -D, and a worktree holding uncommitted work is refused).
`branch`	No	Candidate branch for enqueue/withdraw. Defaults to that tree's HEAD.
`reason`	No	Why a candidate is being withdrawn.
`repo_path`	No	Any working tree of the target repository. This is what makes the queue cross-project: one server, N repositories, each with its own lease, candidate store, and gates. Defaults to the server's cwd.
`batch_size`	No	Candidates gated together per run (0 = the repo's declared batch_size).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.5.1Oct 19, 2026

TDQS

C2.4/5.0

Behavior3/5

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

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) already frame this as a non-read, non-destructive, non-idempotent operation, and nothing in the text contradicts them. The prose adds real system context — differential gating, the reconciliation-merge lease and `deferred: true`, and the landed/pushed split with `push_error` — but almost all of it belongs to the queue `run` path, so the specific behavioral traits of withdraw (reversibility, behavior when the branch is not queued) go undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Roughly 450 words are supplied for a withdraw operation, and most of them describe the merge queue's gating model, D-W3WPS-3 landed/pushed semantics, and push error handling — material that does not help call this tool. The tool's own action is never front-loaded or stated plainly, so the length is off-topic padding rather than concision.

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?

With 7 parameters, an output schema, and full annotations, the structured metadata covers much of the surface, but the description omits everything specific to withdraw: what happens to a withdrawn candidate, whether it is recoverable, and what error surfaces if the branch is not enqueued. Given the operation is the destructive-ish queue-mutating counterpart to enqueue, that omission is a real gap.

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 seven parameters, including `reason` ('Why a candidate is being withdrawn') and `branch`. The description's explanations of `push`, `prune`, and the base landing semantics largely restate the schema text rather than adding syntax or edge-case meaning, so the baseline 3 applies.

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

Purpose2/5

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

The definition opens with 'Withdraw (rm_merge_queue)' but then spends nearly all its text describing the merge queue itself — gates, leases, landed vs pushed — rather than what withdrawing a candidate actually does. It never states the concrete effect (removing a queued candidate so it is no longer gated/landed) and never distinguishes itself from siblings like rm_merge_queue_enqueue, rm_merge_queue_run, or rm_merge_queue_status. Only the schema's 'branch' description hints that withdraw is 'candidate branch for enqueue/withdraw'.

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?

There is no when-to-use guidance for this tool: no condition under which an agent should withdraw rather than enqueue, run, or query status, and no prerequisites. The one imperative present — 'defer, do not retry in a loop' — concerns the `run` lease, not the withdraw operation. The agent is left to infer the trigger entirely.

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

Deploy Server