AIWorkhub

Overview Schema Source Related Servers Discussions Admin

aiworkhub_task_retry_terminal

Requeue a blocked task after a cancelled, timed-out, launch, worker, process, or liveness failure using the exact prior request ID and substatus, preserving append-only audit history.

Instructions

COORDINATOR WRITE: retry one exact operational terminal episode.

Only blocked cancelled/timed-out/launch/worker/process/liveness failures are eligible. The exact prior request id and substatus are mandatory; semantic validation/review failures remain on their established review workflow. The same task ID is requeued and its append-only audit history is preserved.

Replies with a receipt (aiworkhub.retry_terminal_receipt.v1): task_id, status, worker_status, card_sha256/card_bytes, and every server-derived key the transition attached -- retried_request_id, terminal_substatus, request_linkage, workspace_retention, idempotent. One measured call echoed the whole requeued card at 67,395 chars, review_feedback and rework_predecessor included (NF-2026-01447); include_card = none (default) | summary | full brings it back.

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": {
      "task_id": "<task_id>",
      "request_id": "<request_id>",
      "terminal_substatus": "<terminal_substatus>"
    },
    "name": "aiworkhub_task_retry_terminal"
  }
}

Input Schema

Name	Required	Description	Default
`reason`	No	Why the episode is retried, cut to 500 characters; default empty.
`task_id`	Yes	Id of the blocked card to requeue.
`request_id`	Yes	Exact launch request id of the blocked episode being retried, at most 120 characters.
`include_card`	No	Card view to attach to the receipt: none (default), summary (baselines and evidence folded) or full (the exact post-transition card).	none
`terminal_substatus`	Yes	The card's current terminal substatus; one of cancelled, timed_out, output_budget_exceeded, launch_failed, worker_failed, finalize_failed, process_lost or liveness_lost.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.12.67Oct 26, 2026

addedInput schema / properties / include_card / description

Added value: +"Card view to attach to the receipt: none (default), summary (baselines and evidence folded) or full (the exact post-transition card)."

addedInput schema / properties / reason / description

Added value: +"Why the episode is retried, cut to 500 characters; default empty."

addedInput schema / properties / request_id / description

Added value: +"Exact launch request id of the blocked episode being retried, at most 120 characters."

addedInput schema / properties / task_id / description
```
Added value: +"Id of the blocked card to requeue."
```

addedInput schema / properties / terminal_substatus / description

Added value: +"The card's current terminal substatus; one of cancelled, timed_out, output_budget_exceeded, launch_failed, worker_failed, finalize_failed, process_lost or liveness_lost."

First observedv0.1.0Oct 20, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: the same task ID is requeued, append-only audit history is preserved, and the reply includes a documented receipt schema. It also discloses the large-card echo risk and how include_card controls that output, which is valuable for a write/retry tool.

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-loads purpose and eligibility, then receipt and include_card behavior. It is mostly efficient, though the incident reference and exact 67,395-character example are somewhat over-specific for a tool definition.

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?

Given annotations, 100% schema coverage, and an output schema, the description is complete enough to call correctly: eligibility, required identifiers, requeue semantics, audit preservation, receipt shape, and include_card behavior are all covered.

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 still adds value by emphasizing that request_id and terminal_substatus are mandatory and by explaining include_card's practical effect, including the risk of a very large full card response. One gap: the description's eligible failure list does not explicitly map to every enum value in terminal_substatus.

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?

Starts with a specific verb and resource: 'COORDINATOR WRITE: retry one exact operational terminal episode.' It scopes the operation to an exact prior episode and implicitly separates it from semantic/review failure handling, so an agent can identify it without opening the 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?

Explicitly states eligibility: only blocked cancelled/timed-out/launch/worker/process/liveness failures. It also states a when-not condition: semantic validation/review failures remain on their established review workflow. Required prior request id and substatus further constrain correct use.

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

Deploy Server