Skip to main content
Glama
GuoBug

FerryCat

by GuoBug
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

fail_contract

Mark a claimed contract as terminally failed with a required reason, so unrecoverable tasks stop immediately and requesters are freed from waiting for the execution TTL to expire.

Instructions

Explicitly mark a CLAIMED contract as terminal FAILED with a mandatory failure reason.

Purpose

Immediately terminates a claimed task that cannot be completed, recording actionable diagnostic reasons and freeing the requester from waiting for the execution TTL to expire.

Usage Guidelines

  • When to use: Use when a task encounters an unrecoverable failure (e.g. fatal syntax error, broken test suite, missing required environment).

  • When NOT to use:

    • Do NOT use if the task succeeded (use fulfill_contract).

    • Do NOT use if the task is recoverable by another agent or retryable (use release_contract).

  • Prerequisites: Caller must be the current holder and reason must be non-empty.

Behavior & Side Effects

  • Mutates database: Sets status='FAILED', error_reason='WORKER_FAILED: ', and completed_at=nowMs.

  • Late report handling: If the execution window already expired before fail_contract was called, the status becomes TIMED_OUT while faithfully preserving the worker's reason for the requester.

Return Value

Returns { ok: boolean, contract_id: string, status: 'FAILED' | 'TIMED_OUT', message: string }.

Input Schema

NameRequiredDescriptionDefault
reasonYesMandatory explanation of why the task cannot be completed. Stored in error_reason for the requester.
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 mark as terminal FAILED.

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.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the exact mutation (status='FAILED', error_reason prefixed 'WORKER_FAILED:', completed_at=nowMs) and an edge case that would otherwise surprise an agent — a late call after TTL expiry yields TIMED_OUT while preserving the reason. Return shape is also spelled out despite no output schema.

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 single-sentence summary, then short labeled sections — well structured and scannable. It is slightly longer than strictly necessary (Return Value repeats the shape the agent could otherwise infer, and the side-effect detail is dense), but no section is filler.

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 terminal-mutation tool with no annotations and no output schema, the description covers authorization prerequisites, exact side effects, the expired-window edge case, and the return value. Nothing an agent needs to invoke it correctly is missing.

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 100%, so the baseline is 3; the description adds real meaning by tying the caller-identity requirement ('caller must be the current holder') to agent_id/claim_token and stressing the reason is mandatory and surfaced to the requester. It does not add format or length guidance beyond the schema's min/max constraints.

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 (mark terminal FAILED) and resource (a CLAIMED contract), plus the distinguishing constraint 'claimed'. The usage guidelines explicitly name fulfill_contract and release_contract as the alternatives for success and recoverable cases, so an agent can route without opening other schemas.

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?

Gives explicit when-to-use (unrecoverable failure such as fatal syntax error, broken test suite, missing environment) and two explicit when-NOT-to-use cases with the sibling to use instead. Prerequisites (current holder, non-empty reason) are also stated.

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