Skip to main content
Glama

claim_task

Destructive

CLAIMS a task ATOMICALLY, so that no other agent of the queue takes it at the same time: it goes from "to do" to "in progress" in ONE conditional write, and the claim is signed (agentLabel, otherwise the name of your key; and the time). This is the action that replaces update_task({ status: "doing" }), which does not stop anyone from taking the same task. taskId omitted = the FIRST ready task of the queue (priority, then position) — if another agent takes it in the same second, you get the next one. Response: { claimed: true, task } — or { claimed: false, reason, message }; a refusal is never reported as a success. reason: not-found · already-claimed (with heldBy/heldAt when the claim was signed, null otherwise — a task set to "in progress" by hand has no holder) · done · archived · blocked ("blocked" status set by hand) · open-dependencies (with openDependencies) · arbitrage (an arbitration, a question to decide, is not work to claim: it follows its update_task.arbitrageAction cycle) · awaiting-validation / awaiting-approval (the task carries the LABEL a-valider / a-approuver: a human must validate or approve — it can neither be claimed nor reclaimed, EVEN if it is already "in progress"; these labels are not removed to claim the task: they are set and lifted by a human, and a status change through update_task does not count as a claim) · awaiting-triage (the task carries the LABEL etat-tri:a-trier: awaiting triage — neither claimable nor listed by executable; the triage, run according to the project flow (by the human or by the designated agent), replaces the label with etat-tri:trie; evaluated AFTER done and already-claimed, which keep their reason) · no-ready-task (without taskId: no ready task) · conflict (the row changed during the claim: a re-read, then a new attempt, settle it) · write-locked (agent writes are LOCKED on this block or on this project for this account: the message says what to unlock — without taskId, the tasks of a locked view are skipped). A refusal writes NOTHING. Claiming a CHILD task of an arbitration already DECIDED (step arbitre) STARTS it in your name — startedBy/startedAt, and startedArbitrages in the response, absent otherwise: carry out a decision through CHILD tasks of the arbitration, not through tasks that DEPEND on it (a dependent task cannot be claimed before its closure). update_task({ arbitrageAction: { type: "start" } }) remains allowed. A claimed task is no longer in list_tasks({ executable: true }). To hand a task back: update_task({ status }). A task marked executor: "human" is refused with human-task (evaluated AFTER done and already-claimed) and is left out of executable: an agent does not take a human's task. LEASE: a claim is a LEASE of 15 minutes. The response carries claimToken (a SECRET that identifies you as the holder and stays out of every written text), leaseUntil (the deadline) and leaseMinutes. Once the deadline has passed, another agent MAY take over the task: an "in progress" task whose lease has expired is RECLAIMABLE — claim_task takes it over (response claimed: true with reclaimed: { reason: "lease-expired", previousHolder, expiredAt }: this is a TAKEOVER, not a refusal) and list_tasks({ executable: true }) lists it. already-claimed then also carries leaseUntil. A task set to "in progress" by hand (without a signed claim) has no deadline. RENEW with renew_claim (at least once per lease, DECLARING your progress). During the lease, any agent write on the task (update_task, archive_task, unarchive_task) requires claimToken: without it CLAIM_HELD, with an expired token CLAIM_LOST. The token does NOT cover the tracking of the implementation plan (impl-2026-10-* tasks), which this tool never "claims": no claim, no token.

Input Schema

NameRequiredDescriptionDefault
taskIdNoThe task to CLAIM. Omitted, the FIRST ready task of the queue is claimed (same definition as `list_tasks({ executable: true })`, by priority then position) — the "my next task" action.
agentLabelNoThe label that SIGNS the claim ("agent-doc", "worker-2"…) — it is what another agent will read in the refusal "already claimed by …". Optional: omitted, the claim is signed with the NAME OF THE API KEY of the call (without a named key, in the chat for example, it stays without a label: `claimedBy: null`). Two agents of the same key therefore sign the same way: `agentLabel` serves to tell them apart as soon as several agents share a queue.
expectedProjectIdNoUUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / agentLabel / description
      Previous value: -"Le libellé qui SIGNE la prise (« agent-doc », « worker-2 »…) — c’est lui qu’un autre agent lira dans le refus « déjà prise par … ». Facultatif : omis, la prise est signée du NOM DE LA CLÉ d’API de l’appel (sans clé nommée, dans le chat par exemple, elle reste sans libellé : `claimedBy: null`). Deux agents d’une même clé signent donc pareil : `agentLabel` sert à les distinguer dès que plusieurs agents partagent une file."New value: +"The label that SIGNS the claim (\"agent-doc\", \"worker-2\"…) — it is what another agent will read in the refusal \"already claimed by …\". Optional: omitted, the claim is signed with the NAME OF THE API KEY of the call (without a named key, in the chat for example, it stays without a label: `claimedBy: null`). Two agents of the same key therefore sign the same way: `agentLabel` serves to tell them apart as soon as several agents share a queue."
    • changedInput schema / properties / expectedProjectId / description
      Previous value: -"UUID du projet visé par CET appel. Cible RÉELLEMENT ce projet au lieu du projet de session. Refusé sans rien modifier si l'accès n'est pas accordé."New value: +"UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted."
    • changedInput schema / properties / taskId / description
      Previous value: -"La tâche à PRENDRE. Omis, c’est la PREMIÈRE tâche prête de la file qui est prise (même définition que `list_tasks({ executable: true })`, par priorité puis position) — le geste « ma prochaine tâche »."New value: +"The task to CLAIM. Omitted, the FIRST ready task of the queue is claimed (same definition as `list_tasks({ executable: true })`, by priority then position) — the \"my next task\" action."
  2. Changed2 schema fields changed
    • changedInput schema / properties / agentLabel / description
      Previous value: -"Le libellé qui SIGNE la prise (« agent-doc », « worker-2 »…) — c’est lui qu’un autre agent lira dans le refus « déjà prise par … ». Facultatif : omis, la prise est signée du NOM DE LA CLÉ d’API de l’appel (sans clé nommée, dans le chat par exemple, elle reste sans libellé : `claimedBy: null`). Deux agents d’une même clé signent donc pareil : pose `agentLabel` dès que plusieurs agents partagent une file, pour qu’on les distingue."New value: +"Le libellé qui SIGNE la prise (« agent-doc », « worker-2 »…) — c’est lui qu’un autre agent lira dans le refus « déjà prise par … ». Facultatif : omis, la prise est signée du NOM DE LA CLÉ d’API de l’appel (sans clé nommée, dans le chat par exemple, elle reste sans libellé : `claimedBy: null`). Deux agents d’une même clé signent donc pareil : `agentLabel` sert à les distinguer dès que plusieurs agents partagent une file."
    • changedInput schema / properties / taskId / description
      Previous value: -"La tâche à PRENDRE. OMIS = prends la PREMIÈRE tâche prête de la file (même définition que `list_tasks({ executable: true })`, par priorité puis position) — c’est le geste « donne-moi ma prochaine tâche »."New value: +"La tâche à PRENDRE. Omis, c’est la PREMIÈRE tâche prête de la file qui est prise (même définition que `list_tasks({ executable: true })`, par priorité puis position) — le geste « ma prochaine tâche »."
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only mark this as a non-read-only, destructive write; the description supplies the real behavioral picture: a 15-minute lease, `claimToken` as a secret holder credential, what happens on expiry (takeover, not refusal), that a refusal writes NOTHING, that `CLAIM_HELD`/`CLAIM_LOST` gate other writes, and the exception for `impl-2026-10-*` tracking tasks. This is dense, non-obvious behavior an agent could not infer from structured fields.

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

Conciseness4/5

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

Front-loaded with the core atomic-claim idea before any of the refusal taxonomy, and every block is information-bearing. It is nonetheless very long with heavy capitalization and some overlap between the refusal list and the lease section, which costs it the top score.

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?

No output schema exists, so the description carries the return contract — `{ claimed: true, task }` versus `{ claimed: false, reason, message }`, the full `reason` enumeration, `reclaimed` on takeover, and `startedArbitrages` — plus the lease fields. For a zero-required-parameter, race-sensitive mutation tool, nothing an agent needs to call it safely is missing.

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 is 3, but the description adds genuine meaning: `taskId` omitted means "the FIRST ready task ... priority, then position" with a race caveat, and `agentLabel` signing is explained along with the key-name fallback and the notion that the token never appears in written text. `expectedProjectId` is left entirely to the schema.

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?

Opens with a specific verb and mechanism: "CLAIMS a task ATOMICALLY ... it goes from 'to do' to 'in progress' in ONE conditional write". It explicitly distinguishes itself from the nearest sibling by naming `update_task({ status: "doing" })` and explaining why that alternative is insufficient, so an agent can route correctly without opening either schema.

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?

Gives explicit when/when-not: use this instead of a status update to avoid double-taking; omit `taskId` to take the next ready task; use `renew_claim` to hold the lease; use `update_task({ status })` to hand a task back; carry out arbitrations through child tasks, not dependents. It also names many refusal conditions that indicate when the tool is the wrong choice (arbitrage, human-task, awaiting-validation, write-locked).

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.