Skip to main content
Glama

Claim the next issue

next_issue

Pull the next issue to work on, project-scoped — atomically claims the highest-priority unblocked issue and returns it with a claim_token. Dispatch is NOT todo-only (RTSC-257): a review — finished work awaiting acceptance — is claimable work in its reviewer's lane and is handed out here too, ahead of a todo at equal rank, and it is never handed back to whoever submitted it. A todo claims into 'doing'; a review pick STAYS 'review' (the lease is on the review, so a release or a reclaim returns it to review, never to todo). Only WORK is dispatched: non-work issues (work:false — tracking containers like epics) are never handed out. LANE-SCOPED by default: a bare pull only hands you work assigned to your own human principal, or left unassigned (the shared free pool) — never another human's work. Pass allLanes:true to reach into the whole ready pool (e.g. an owner is away and their work should still move). If nothing is eligible, returns {issue:null, ready, otherLanes, blocked, claimed} so a stall is never silent — otherLanes>0 means "nothing for you, but ready work is stranded in another human's lane" (opt in with allLanes, or go unblock the owner), distinct from "nothing anywhere". In that case the response also carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN and let them answer. Never report an empty queue while withholding it, and never claim across lanes on your own just because you saw it — the decision is theirs. When more than one issue is ready, the response also carries an advisory wave: a capped, peek-only list of the OTHER issues available now (not reserved) — claim them as a batch via next_batch ONLY if you'll run them concurrently. Keep the claim_token: you need it to release/heartbeat. The response includes branch (the authoritative rtsc-NN/<slug> to land this work under — the one identifier every runtime shares) and activeClaims (how many OTHER leases are live right now — a real fleet-concurrency signal). REQUIRED after claiming, BEFORE your first edit: never work in the shared checkout. Create an isolated git worktree for branch and work ONLY there — e.g. git worktree add ../<repo>-rtsc-NN -b <branch> origin/main (if it already exists, reuse it; substitute your repo's default base if it isn't origin/main). 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
allLanesNoReach into the whole ready pool, including 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.6/5.0
Behavior5/5

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

Annotations declare this is a non-read-only, non-idempotent mutation, and the description adds substantial behavioral context beyond that: atomic claiming, lease TTLs, renewal rules, exhaustion response shapes, billing refusal behavior, and lane scoping. Nothing contradicts the annotations, and the added detail is unusually rich.

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 purpose is front-loaded, but the description is extremely long and dense, with extensive operational guidance about worktrees, dependency setup, lease renewal modes, proxy behavior, session IDs, and billing errors. Much of that material is useful, but the overall size and repetition make it harder to scan than it needs to be.

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?

Given the complexity of atomic claiming, lane scoping, lease renewal, and no output schema, the description is complete enough to call the tool correctly. It describes the success path, empty-result diagnostics, claim_token, branch, activeClaims, claimExpiresAt, and tellHuman behavior.

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

Parameters4/5

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

Schema coverage is 100% for the sole allLanes parameter, so the baseline is 3. The description adds real semantic value by explaining the default lane-scoped behavior, the meaning of opting into allLanes, and the policy that the agent should not cross lanes on its own.

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?

The first sentence gives a specific verb and resource: atomically claim the highest-priority unblocked issue and return it with a claim_token. It also distinguishes this from siblings like next_batch, claim_issue, heartbeat, and checkpoint, so an agent can identify the tool's role without opening other schemas.

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?

The description explicitly covers when to use next_issue, when to opt into allLanes, and when to use next_batch for concurrent batch work. It also routes the agent to heartbeat/checkpoint/release/check_claim for lease management, leaving little ambiguity about alternatives.

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