Skip to main content
Glama

claim_task

Claims a ready task for an external agent—or releases its claim—and returns the task card plus worktree. Omit task_id to claim the first ready task; claims expire after 15 minutes idle.

Instructions

External agents only: claim a ready task (all dependencies accepted, nobody holding it) or, with release: true, give yours back (its leases are released; the work stays in the worktree). Without task_id, the first ready task (your team's first) is claimed. Returns the task card and the worktree to work in. External workers' claims expire after 15 minutes without a tool call.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "execution_id": "<execution_id>",
      "agent_token": "<agent_token>"
    },
    "name": "claim_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoWhy you release it (recorded).
releaseNoRelease your claim instead.
task_idNo
agent_tokenYesThe agent token join_execution returned (once).
execution_idYesThe heads-down run (exe-…).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.0.0

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds genuinely non-obvious behavior: the 15-minute expiry for external workers without a tool call, and that releasing keeps the work in the worktree. Those are useful additions, but return-shape detail is handled in prose only and failure modes (claim conflicts, no-ready-task) are undisclosed.

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-loads the audience restriction, then the primary mode, then the default, then the return value, then expiry — a sensible ordering with no filler sentences. The opening sentence carries heavy nested parentheticals, which slightly slows parsing but every clause conveys distinct information.

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?

For a five-parameter mutation tool with no output schema, the description covers audience, both modes, default selection, return contents ('the task card and the worktree'), and claim lifetime. An agent can call it correctly on the first attempt without further context.

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 80%, so baseline is 3; the description earns above that by explaining the semantics of omitting task_id (claims the first ready task, your team's first) and of release: true, which the schema only labels as 'Release your claim instead'. The interplay between task_id and release mode is spelled out rather than left to inference.

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?

Names a specific verb and resource ('claim a ready task') and defines 'ready' inline as 'all dependencies accepted, nobody holding it'. It also declares the inverse mode ('with release: true, give yours back'), so an agent knows the tool is a bidirectional claim/release operation and can distinguish it from lease-style or execution-control siblings.

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?

Gives explicit branch conditions: external agents only, omit task_id to take the first ready task, set release: true to hand one back. The scoping restriction and the default-selection behavior remove most ambiguity. It stops short of naming any alternative tool or stating what happens when no ready task exists, so it is clear context rather than full when/when-not routing.

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