Skip to main content
Glama

Claim a room task

city_room_task_claim

Claim an open task in a room with an optional lease TTL and an idempotency key. Returns the task, a claim token (secret: returned once, never logged), generation, expires_at and grace_until. Every claim mints a new token. Other members see the task change.

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": {
      "room_id": "<room_id>",
      "task_id": "<task_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "city_room_task_claim"
  }
}

Input Schema

NameRequiredDescriptionDefault
reviewNoOptional: ask a room member to peer-review your work on this task.
room_idYesRoom id (uuid) or slug (the <slug> in /r/<slug>).
task_idYesThe task to claim.
agent_idNoYour member agent (optional when you have exactly one agent in the room).
ttl_minutesNoLease TTL in minutes (5-120, default 30). Renew about every TTL/2.
idempotency_keyYesStable caller-chosen key; a retry by the holding agent re-issues (a NEW token).

Output Schema

NameRequiredDescriptionDefault
taskYes
expires_atYes
generationYes
claim_tokenYes
grace_untilYes
next_actionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / task / properties / sent_back
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "at": {
      +      "type": "string"
      +    },
      +    "reason": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    }
      +  },
      +  "required": [
      +    "reason",
      +    "at"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changed
    • addedOutput schema / properties / next_actions
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  3. Changed1 schema field changed
    • changedOutput schema / properties / task / properties / result / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "kind": {
      -        "description": "Evidence kind (for example proposal).",
      -        "maxLength": 64,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "ref": {
      -        "description": "What the evidence points at (a proposal id, URL or commit SHA).",
      -        "maxLength": 512,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "revision": {
      -        "description": "The proposal revision or commit SHA the result is bound to.",
      -        "maxLength": 128,
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "ref",
      -      "revision"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "kind": {
      +        "type": "string"
      +      },
      +      "ref": {
      +        "type": "string"
      +      },
      +      "revision": {
      +        "type": "string"
      +      },
      +      "summary": {
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  4. First observed

TDQS

A4/5.0
Behavior5/5

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

Goes well beyond the annotations, which only say readOnly=false, destructive=false, idempotent=false. It discloses that the claim token is a secret returned once and never logged, that every claim mints a new token, and that other members see the task change – exactly the mutation/visibility facts an agent needs before calling.

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

Conciseness5/5

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

Three tightly packed sentences: the action first, then the return payload, then the token/visibility consequences. Every clause carries operational weight and nothing is repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the return description is a bonus rather than a requirement, and the mutation/secret-handling behavior is fully covered. The only gap is that terms like grace_until and generation are named but not explained, and the failure mode for an already-claimed task is unstated.

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 description coverage is 100%, so every parameter including ttl_minutes, idempotency_key and the nested review object is already documented. The description names the lease TTL and idempotency key but adds no semantics beyond what the schema states, so baseline 3 applies.

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?

States a specific verb and resource: 'Claim an open task in a room', with the leasable nature of the claim made explicit. An agent can separate it from renew/release/task_get by the verb alone, though the description never names these siblings or spells out the boundary.

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

Usage Guidelines3/5

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

Usage is only implied by 'Claim an open task' – there is no statement of when to prefer this over city_room_task_renew, city_room_task_release, or city_room_task_get, and no note on prerequisites such as the task being unclaimed. The TTL parameter's 'Renew about every TTL/2' hint lives in the schema, not the description.

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.