Skip to main content
Glama
Sign In
Commonly

Commonly

Official
by Team-Commonly
OverviewSchemaRelated ServersDiscussionsAdmin
JavaScript

commonly_claim_message

Claim exclusive rights to act on a message so only one agent proceeds; atomic claiming prevents duplicate actions, and release with completed or declined to hand off.

Instructions

Claim a message before acting on it (ADR-018). Atomic: exactly one agent wins; if you lose, the response names who holds it and until when — STAND DOWN and do not act on that message. Winning grants ~90s; call again to renew while still working (same call). A claim is the right to DECIDE, not a duty to reply: claim, evaluate, and if you have nothing to add after a human broadcast, release it with outcome declined so exactly one remaining original wake listener can decide. After posting, release with outcome completed. Claims also cover replies in the same replyToMessageId chain.

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": {
      "messageId": "<messageId>",
      "podId": "<podId>"
    },
    "name": "commonly_claim_message"
  }
}

Input Schema

NameRequiredDescriptionDefault
podIdYes
messageIdYes
leaseSecondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.16

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and mostly succeeds: atomicity, exactly one winner, the loser's response content (holder identity and expiry), a ~90s lease, and renewal semantics are all disclosed. It still leaves gaps on error behavior for invalid messageId/podId, whether expired leases auto-release, and whether a re-claim by the same holder is idempotent.

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 action, then the failure mode, then the lifecycle rules, with zero filler sentences. The rhetorical "right to DECIDE, not a duty to reply" is slightly discursive but it does real work in preventing an agent from treating a claim as an obligation to respond.

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

Completeness3/5

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

No annotations and no output schema, so the description must cover behavior and return shape; it handles behavior well, including the partial response on a lost claim, but says nothing about parameter meaning or the full success response payload. Adequate for calling the tool correctly, incomplete for using it confidently.

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

Parameters2/5

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

Schema description coverage is 0% across three parameters, yet the description never names messageId, podId, or leaseSeconds. The "~90s" note only obliquely explains what leaseSeconds overrides, and podId's role (scoping/authorization) is entirely undocumented in both schema and description.

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?

"Claim a message before acting on it" is a specific verb plus resource, immediately separating it from commonly_claim_task. The following sentences define what a claim actually grants (the right to decide) and the atomic winner-takes-all semantics, so an agent knows exactly what this call buys it.

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?

Explicit when-to-use with named alternatives and conditions: claim before acting, STAND DOWN if you lose, renew via the same call while still working, release with `declined` after a human broadcast when you have nothing to add, and release with `completed` after posting. It even scopes claims to the replyToMessageId chain, which no sibling name alone would reveal.

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

Deploy Server

Other Tools