Skip to main content
Glama
GuoBug

FerryCat

by GuoBug
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

fulfill_contract

Submit final deliverables for a claimed FerryCat contract, verify the code baseline is unchanged, validate structured output against its schema, and transition the contract to COMPLETED.

Instructions

Submit execution or review deliverables for a CLAIMED contract, with TOCTOU soft-failure buffering and Ajv JSON Schema validation.

Purpose

Delivers the final output of a task, verifies that the code baseline was not mutated during execution, validates structured payloads, and transitions the contract to terminal COMPLETED.

Usage Guidelines

  • When to use: Use after completing task work to deliver result_summary, optional structured_output, and optional artifacts_pointers.

  • When NOT to use:

    • Do NOT use if you cannot complete the task (use release_contract to re-queue, or fail_contract to record failure).

    • Do NOT use if you modified pointer files directly on disk. If modified accidentally, run "git stash" or restore the files, run verify_contract, and pass proposed fixes inside structured_output.fixes.

Behavior & Side Effects

  • Authorization: Caller agent_id must match target_agent of the claimed contract.

  • TOCTOU Guard & Soft-Failure Buffer (ADR-0004) — exactly ONE recoverable rejection:

    • 1st blocked fulfill: returns status='RETRY_NEEDED', keeps the contract CLAIMED, renews the execution window (claimed_at=now), and lists dirty_files with restore instructions.

    • 2nd blocked fulfill: transitions to terminal status='POINTER_STALE', preserving your summary and payload in salvaged_result_json so the work is not lost.

    • Only ONE rejection is recoverable: restore/stash the files BEFORE retrying, and call verify_contract first so a stray second attempt cannot burn the buffer.

  • Schema Validation: If contract_schema was defined, validates structured_output via cached Ajv validator. Failures 1 & 2 return RETRY_NEEDED with flattened error paths and renew the execution window; 3rd failure transitions to terminal VALIDATION_FAILED.

  • On Success: Transitions to terminal status='COMPLETED', recording result_summary, structured_output, artifacts_pointers, and verified SHA-256 snapshot.

Return Value

Returns { ok: boolean, contract_id: string, status: 'COMPLETED' | 'RETRY_NEEDED' | 'POINTER_STALE' | 'VALIDATION_FAILED', retry_count: number, max_retries: number, toctou_strike?: number, max_toctou_strikes?: number, dirty_files?: Array<{ path, reason, detail }>, validation_errors?: string[], message: string }.

Input Schema

NameRequiredDescriptionDefault
agent_idNoWorker agent identifier. Must match the contract target_agent (defaults to AGENT_NAME env var).
claim_tokenNoExclusive lease token returned in contract.claim_token by poll_next_task (FC-301). Mutating operations must provide matching claim_token to prevent cross-worker interference.
contract_idYesThe contract ID returned by poll_next_task that is currently in CLAIMED status.
result_summaryYesDetailed markdown or plain text summary of review findings, implementation details, or test execution outcomes (1-20000 chars).
structured_outputNoStructured JSON payload matching contract_schema. Bounded to 1MB and max 32 depth (FC-302). For code reviews, pass proposed patches in fixes: [{ path, patch, description }] rather than editing pointer files directly (ADR-0004).
artifacts_pointersNoOptional pointers to new or modified artifact files created during task execution (max 50 files).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields 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). Mutating operations must provide matching claim_token to prevent cross-worker interference.",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / structured_output / description
      Previous value: -"Structured JSON payload matching contract_schema. For code reviews, pass proposed patches in fixes: [{ path, patch, description }] rather than editing pointer files directly (ADR-0004)."New value: +"Structured JSON payload matching contract_schema. Bounded to 1MB and max 32 depth (FC-302). For code reviews, pass proposed patches in fixes: [{ path, patch, description }] rather than editing pointer files directly (ADR-0004)."
  2. Changed7 schema fields changedv0.3.0
    • changedInput schema / properties / agent_id / description
      Previous value: -"Worker agent identifier (defaults to AGENT_NAME env var)"New value: +"Worker agent identifier. Must match the contract target_agent (defaults to AGENT_NAME env var)."
    • changedInput schema / properties / artifacts_pointers / description
      Previous value: -"Optional pointers to files created or modified during task execution"New value: +"Optional pointers to new or modified artifact files created during task execution (max 50 files)."
    • addedInput schema / properties / artifacts_pointers / items / properties / description / description
      Added value: +"Description of the artifact and its role"
    • addedInput schema / properties / artifacts_pointers / items / properties / path / description
      Added value: +"File path of created or modified artifact relative to workspace_root"
    • changedInput schema / properties / contract_id / description
      Previous value: -"The contract ID returned by poll_next_task"New value: +"The contract ID returned by poll_next_task that is currently in CLAIMED status."
    • changedInput schema / properties / result_summary / description
      Previous value: -"Human-readable summary of findings or implementation"New value: +"Detailed markdown or plain text summary of review findings, implementation details, or test execution outcomes (1-20000 chars)."
    • changedInput schema / properties / structured_output / description
      Previous value: -"Structured JSON payload matching the contract_schema"New value: +"Structured JSON payload matching contract_schema. For code reviews, pass proposed patches in fixes: [{ path, patch, description }] rather than editing pointer files directly (ADR-0004)."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

No annotations exist, and the description carries the full burden well: it discloses the authorization requirement (agent_id must match target_agent), the exact TOCTOU soft-failure policy with strike counts and terminal outcomes, the Ajv validation retry ladder (2 recoverable, 3rd terminal VALIDATION_FAILED), and what data is preserved on failure. These are non-obvious side effects an agent could not infer from the 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?

Well front-loaded with a one-sentence summary, then headed sections that map to purpose, usage, behavior and returns. It is long but nearly all of it is load-bearing; the return-value enumeration and repeated strike-buffer detail are slightly redundant but justified given there is no output schema.

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 complex 6-param mutating tool with no annotations and no output schema, the description covers prerequisites (claim_token, CLAIMED status), failure modes and terminal statuses, and spells out the return shape itself. 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.

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter, including claim_token and the fixes pattern. The description reinforces the roles of result_summary, structured_output and artifacts_pointers but adds little syntax or format detail beyond what the schema states; baseline 3 applies.

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?

Names a specific verb and resource (submit deliverables for a CLAIMED contract) and explicitly describes the scope: delivery, baseline verification, schema validation, transition to COMPLETED. It distinguishes itself from release_contract and fail_contract by name, so an agent can route between them 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 an explicit 'When to use' and a 'When NOT to use' section that names the correct alternatives (release_contract to re-queue, fail_contract to record failure) along with a concrete accidental-modification recovery path (git stash, verify_contract, fixes in structured_output).

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