Skip to main content
Glama

Claim an issue

claim_issue

Claim one specific issue by id (instead of letting next_issue pick). Fails if it's already held (active lease), blocked, non-work (work:false — tracking containers aren't claimable), or in a status that isn't todo, doing or review. A review IS claimable, and claiming one is how a reviewer takes the work (RTSC-257): the issue stays in review, and accepting it later with save_issue status:"done" is REFUSED unless you hold that lease (CLAIM_REQUIRED). You cannot claim the review of work you submitted yourself (AUTHOR_CANNOT_REVIEW). Returns a claim_token. ALSO THE RESUME DOOR: if you were restarted or /resume'd, your client may have started a NEW session, in which case the server sees a different session holding your issue and done fails with CLAIM_MISMATCH. You don't have to wait out the lease or give the work back — call this with the claimToken you were given before the restart and the lease moves onto your new session (a fresh token, rebound: true, status and progress untouched; if THIS session already held it, nothing moves, the same token comes back with renewedOnly: true, and it costs a 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
claimTokenNoONLY to resume your own claim after a restart: the claim_token from before, which moves that live lease onto this session. Omit when claiming new work. It proves you are the same agent continuing — a session that never held the issue doesn't have it, and it can never move a claim to a different agent.
identifierYese.g. XEN-12

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added
  2. Removed
  3. Changed1 schema field changed
    • addedInput schema / properties / claimToken
      Added value: +{
      +  "description": "ONLY to resume your own claim after a restart: the claim_token from before, which moves that live lease onto this session. Omit when claiming new work. It proves you are the same agent continuing — a session that never held the issue doesn't have it, and it can never move a claim to a different agent.",
      +  "type": "string"
      +}
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

The description adds extensive behavior beyond the annotations: lease TTL dependent on proxy/no-proxy, renewal mechanics, sweep consequences, CLAIM_REQUIRED and AUTHOR_CANNOT_REVIEW errors, worktree isolation requirements, and billing refusal handling. No annotation contradiction is present.

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 critical purpose and refusal conditions are front-loaded, but the description becomes a dense wall of operational detail with long parentheticals and all-caps warnings. Most content is relevant to correct use, but the extreme length and embedded lifecycle rules make it harder to scan than necessary.

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 no output schema and a complex lease-based workflow, the description fills in every important behavior: return fields (`claim_token`, `branch`, `activeClaims`, `claimExpiresAt`, `rebound`, `renewedOnly`), renewal responsibilities by client type, failure codes, and required post-claim worktree setup.

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%, so the baseline would be 3, but the description adds meaningful semantics for `claimToken` beyond the schema: it resumes a prior lease onto a new session, is refused if the session never held the issue, and returns rebound/renewedOnly states. `identifier` is only lightly covered beyond the schema example.

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 description opens with a specific verb and resource: 'Claim one specific issue by id.' It explicitly contrasts this with 'instead of letting next_issue pick,' making the tool's role distinct from the sibling that auto-selects work.

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?

It states precisely when to use this tool versus next_issue and enumerates the refusal conditions (already held, blocked, work:false, invalid status). It also explicitly clarifies edge cases like claiming a `review` issue and resuming after a restart.

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