Skip to main content
Glama
GuoBug

FerryCat

by GuoBug
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

release_contract

Returns a claimed contract to the queue as SUBMITTED with a fresh window when an agent claimed it by mistake, lacks dependencies, or must switch branches.

Instructions

Hand a CLAIMED contract back to the queue tail as SUBMITTED with a fresh queue window.

Purpose

Allows an agent holding a claimed task to safely release ownership back to the queue without failing or aborting the task.

Usage Guidelines

  • When to use: Use when your agent claimed a task by mistake, encounters missing local dependencies/tools, or needs to switch git branches before processing.

  • When NOT to use:

    • Do NOT use if the task permanently failed or cannot ever be completed (use fail_contract).

    • Do NOT use if you simply need more time to finish active execution (use extend_ttl).

  • Prerequisites: Caller must be the current holder (agent_id matches target_agent) and contract status must be CLAIMED.

Behavior & Side Effects

  • Mutates database: Resets claimed_at=NULL, updates queued_at=nowMs, resets extend_count=0 (renewal quota is per holder), and increments release_count.

  • Preserves retry_count: The schema validation circuit-breaker quota is contract-level; releasing a contract cannot launder previously consumed retry attempts.

  • Audit history: Appends reason to error_reason history ("RELEASED_BY_HOLDER: | prev: ...").

  • Limits: Maximum 3 releases per contract. Refused once the contract reaches its absolute lifetime ceiling (nowMs >= created_at + 4 * queue_ttl_sec).

Return Value

Returns { ok: boolean, contract_id: string, status: 'SUBMITTED' | 'CLAIMED' | 'TIMED_OUT', release_count: number, max_releases: number, message: string }.

Input Schema

NameRequiredDescriptionDefault
reasonNoOptional reason for releasing (e.g., "wrong context", "missing tool", "switching git branch"). Appended to error_reason history.
agent_idNoCurrent holder agent identifier. Must match target_agent of the claimed contract (defaults to AGENT_NAME env var).
claim_tokenNoExclusive lease token returned in contract.claim_token by poll_next_task (FC-301).
contract_idYesThe CLAIMED contract ID to release back to the queue tail as SUBMITTED.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.2
    • addedInput schema / properties / claim_token
      Added value: +{
+  "description": "Exclusive lease token returned in contract.claim_token by poll_next_task (FC-301).",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}
  2. Addedv0.3.0

TDQS

A4.6/5.0
Behavior5/5

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

No annotations exist, so the description carries the full burden and it does: it discloses exact DB mutations (claimed_at=NULL, queued_at=nowMs, extend_count=0, release_count incremented), what is deliberately preserved (retry_count circuit-breaker quota, with the anti-laundering rationale), the audit-trail format appended to error_reason, and hard limits (max 3 releases, absolute lifetime ceiling of 4 * queue_ttl_sec). This is exactly the side-effect detail a mutation tool needs.

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 verb/effect in the first sentence, then cleanly partitioned into Purpose, Usage, Behavior, and Return Value. Slightly longer than necessary — the one-line Purpose section largely repeats the headline — but every other sentence carries distinct operational 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?

Although there is no output schema, the description spells out the full return shape ({ ok, contract_id, status, release_count, max_releases, message }). Combined with the side-effect and limit disclosures, an agent has everything needed to invoke this safely and interpret the result.

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 each of the four parameters, including claim_token's provenance from poll_next_task, is already documented in the schema. The description restates the agent_id/target_agent match and CLAIMED-status prerequisite but adds no new syntax or format detail beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (release), resource (contract), and target state (back to queue tail as SUBMITTED with a fresh queue window). The usage-guidelines section explicitly contrasts it with fail_contract and extend_ttl, so an agent can distinguish it from every sibling without opening a 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?

Provides explicit 'when to use' (claimed by mistake, missing local deps, need to switch branches) and an explicit 'when NOT to use' pair that names the correct alternative for each case (fail_contract for permanent failure, extend_ttl for needing more time). Prerequisites are stated outright (caller must be the current holder, status must be CLAIMED).

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