Skip to main content
Glama
Sign In

SKEIN

by net.skein
OverviewDiscussionsAdmin

skein_unclaim

Release the caller's lock on an issue AND atomically transition status to the caller-declared nextStatus. Three valid intents: nextStatus="in_progress" = handoff (status stays in_progress so a teammate can claim and continue; pair with a comment describing what's done); nextStatus="open" = give up (status reverts to open so the issue is visible again in skein_ready); nextStatus="deferred" = punt (status → deferred; set defer_until via a follow-up skein_update if needed). nextStatus="closed" is rejected — use skein_close instead, which carries reason + commits[]. reason is required (non-empty after trim) and lands on both the issue.unclaimed event and (when status actually changed) the issue.status_changed event. Idempotent on an already-unlocked issue (returns the issue post-state unchanged; nextStatus is ignored — use skein_update directly if you want to flip status without a lock). Caller must hold the lock or pass force=true (force_unlock: project owner, space owner, instance admin; others get force_unlock_forbidden); event reason becomes " (force-overridden)" on the force path. ANSWERS WITH AN ACKNOWLEDGEMENT by default — the id, the applied state and the new version, no issue card and no prose — so the expectedVersion cycle continues without a re-read; pass verbose for the full IssueDetail.

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": {
      "id": "<id>",
      "nextStatus": "<nextStatus>",
      "reason": "<reason>"
    },
    "name": "skein_unclaim"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesFull hierarchical issue id (e.g. "demo-42").
forceNoBypass the lock-holder predicate. Needs force_unlock on the issue's project (project owner, space owner, instance admin); others get `force_unlock_forbidden`. Default: false.
reasonYesFree-form reason annotation (non-empty after trim). Lands on issue.unclaimed.reason and, when status changed, issue.status_changed.reason.
verboseNoReturn the full IssueDetail, prose included. Default false = acknowledgement: `id`, `ok`, `version` plus the post-state stamps that apply (`status`, `assignee`, lock / claim / close stamps) — no issue card and no free text. The version is always there, so the expectedVersion cycle needs no extra read. Details: skein_get_instructions.
nextStatusYesRequired intent declaration: "in_progress" (handoff), "open" (give up), or "deferred" (punt). "closed" is rejected — use skein_close.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Goes well beyond the annotations: it discloses the atomicity of unlock+status change, where `reason` lands (issue.unclaimed and, when status changes, issue.status_changed), the exact force-override permissions and the `force_unlock_forbidden` failure, and the "<reason> (force-overridden)" event suffix. It also explains the default acknowledgement payload versus `verbose`, which annotations do not cover. Note a mild tension with idempotentHint=false, but the claim is explicitly scoped to an already-unlocked issue while the normal path emits events and mutates state, so it reads as a narrowing rather than a contradiction.

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 action and then the three intents in a scannable ordered form; nearly every clause carries information. It is a dense single block, though, and the return-shape material at the end competes with the intent guidance for attention.

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 lock-mutating tool with no output schema, the description covers preconditions, failure modes, event side effects and the exact return shape (id, state, version, ack vs full IssueDetail). Nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, yet the description still adds meaning the schema does not: what each `nextStatus` enum value intends and implies downstream, that `reason` must be non-empty after trim and is copied onto two events, and what `verbose`/`force` actually change in behavior and output.

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?

States a specific verb pair and resource — release the caller's lock AND atomically transition status — and names the alternative for the rejected case (skein_close) and the no-lock case (skein_update), so it is distinguishable from siblings without opening any 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?

Enumerates the three valid intents with the situation each represents (handoff / give up / punt) and their downstream consequences (stays in_progress for a teammate, reappears in skein_ready, moves to deferred). It also states what is rejected (nextStatus="closed" → use skein_close), what the idempotent path means and when to bypass it (use skein_update), and the precondition for force.

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

All SKEIN toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources