Skip to main content
Glama

Plan or claim a batch of issues

next_batch

Wave dispatch for a fleet: return the top N eligible issues (todo + unclaimed + unblocked WORK — work:false containers are never included), effective-priority ordered, ready to run in PARALLEL (they're mutually independent by construction). Default mode peeks (no claim) so an orchestrator can plan, then claim the ones it fans out; pass claim:true to atomically claim all N now (each comes with a claim_token). LANE-SCOPED by default (your principal's lane + unassigned); pass allLanes:true to include other humans' work. Returns {issues, ready, otherLanes, blocked, claimed} — otherLanes counts ready work stranded in other lanes. When the wave comes back EMPTY and otherLanes>0, the response also carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN and let them answer, rather than reporting an idle queue. Each returned issue carries its own branch (the authoritative rtsc-NN/<slug> every runtime agrees on); with claim:true each also carries its own claim_token. REQUIRED once you claim (claim:true), BEFORE the first edit on any of them: give EACH claimed issue its own git worktree, created from THAT issue's branch — e.g. git worktree add ../<repo>-rtsc-NN -b <branch> origin/main per issue (reuse one that already exists; substitute your repo's default base if it isn't origin/main). Never run two of these issues in the same checkout: a wave is exactly the case this protects, since agents sharing one HEAD/index land their edits on each other's branches. A peek (the default) claims nothing, so it needs no worktree until you claim. Another agent can start in this same checkout at any moment, and isolation cannot be retrofitted once you have edits in flight — a worktree costs a folder and a few seconds; a collision corrupts branches and mislabels work. Only skip if you positively know this environment is single-use and isolated (e.g. an ephemeral per-task container) — and even then a worktree is harmless. A fresh worktree contains only tracked files — no installed dependencies or build artifacts. Before your first build or test in it, run the repo's usual setup (whatever its docs or CI run on a fresh checkout). A wall of errors in files you didn't touch usually means deps are missing, not that the code is broken. Your claim is a LEASE, not a permanent assignment: it expires 30 minutes after you take it behind the retasc mcp-proxy and 2 hours after with no proxy (the response carries the exact claimExpiresAt). Behind the retasc mcp-proxy, ONLY heartbeat and checkpoint renew it — nothing else does, not comments, not status updates, not reading the issue. With NO proxy, if your client echoes the Mcp-Session-Id we hand you at initialize, your own calls renew instead (RTSC-858): every call renews every claim THIS session took, a read as much as a write. Each renewal is a FULL reset to the lease's length from that moment, so one call is enough however little was left. Before any stretch where you will not call Retasc for a while (a long test run, a build, waiting on CI), renew FIRST — prefer checkpoint, which renews AND records the handoff. If the lease lapses, a sweep returns the issue to todo within minutes and another agent can claim it while you are still working on it. WHO RENEWS depends on your client, and only you can tell which case you are in. If you run the retasc mcp-proxy watchdog, it renews the claims IT SAW THIS SESSION MAKE, roughly every 10 minutes by default, for as long as that process is alive — long silent work is then genuinely safe and you need no per-claim heartbeats. Nothing renews a claim the proxy did not see (made in another terminal, over direct HTTP MCP, or by a previous proxy before a restart), and nothing renews once the proxy stops: those run on their bare TTL and are yours to renew. With no watchdog and no session id echoed, every renewal is yours. With no watchdog but a session id, your own calls carry it, right up until your client RECONNECTS, which starts a new session and stops renewal for claims taken under the old one; claim_issue with your claimToken moves them onto the new session and renewal resumes. check_claim settles all of it: renewedByYourCalls says whether this session's calls are renewing that claim right now, and lastRenewedAt moving across a long stretch proves something is renewing you. If this call is refused for billing (BILLING_INACTIVE or MONTHLY_CAP_REACHED), the response carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN. You cannot fix it yourself — only an owner can — so do NOT absorb the refusal and continue with read-only work as if the session were healthy; every value-bearing write will keep failing until they act.

Input Schema

NameRequiredDescriptionDefault
nNoHow many to return (default 5, max 25).
claimNoAtomically claim all returned issues now (default false = peek).
allLanesNoInclude issues assigned to other humans (default false = only your own lane + unassigned).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added
  2. Removed
  3. First observed

TDQS

A4/5.0
Behavior5/5

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

Goes far beyond the annotations: discloses lease TTLs (30 min behind proxy, 2 h without), exactly which calls renew it, the worktree-per-issue isolation requirement with rationale, dependency-setup gotcha on fresh worktrees, and billing-refusal behavior. The annotations only say readOnly=false / not idempotent; the description supplies the entire operational contract.

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?

The first sentence is well front-loaded, but the body balloons into several hundred words of lease renewal policy, session-id echo rules, proxy watchdog behavior, and billing refusal handling that apply across many tools, not just this one. The actionable call-shape content (peek vs claim, lane scope, worktree) is buried and an agent must wade through renewal minutiae to reach it.

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 output schema, the description still names the full response shape ({issues, ready, otherLanes, blocked, claimed}) plus per-issue branch and claim_token. Combined with the empty-wave and billing-refusal paths, an agent has everything needed to call this correctly and interpret the result.

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 coverage is 100% with each of the three params already documented (n default 5/max 25, claim default false, allLanes default false). The description restates those defaults rather than adding format or edge-case meaning beyond them, so the baseline 3 applies. It does add that each claimed issue carries a claim_token and branch, but that is about return values, not parameter semantics.

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

Purpose4/5

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

The opening sentence states a specific verb+resource+scope: return the top N eligible issues (todo + unclaimed + unblocked WORK), priority-ordered, parallel-safe. It even defines 'eligible' inline. It stops short of naming the obvious siblings (next_issue, claim_issue, list_issues) that an agent must distinguish this batch tool from.

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

Usage Guidelines4/5

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

Clear mode-selection guidance: default peeks for planning, claim:true atomically claims, allLanes:true widens scope, and empty-wave-plus-otherLanes has an explicit prescribed action (relay tellHuman). What is missing is explicit routing against alternatives — nothing says when to prefer next_issue or list_issues over this.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources