Tasks Tools

The Tasks suite gives agents a durable control plane for long-running work. When a tool call is promoted to the background, DataGrout returns a task_ref instead of forcing the caller to wait inline. The Tasks tools let the caller poll, reattach briefly, inspect, retrieve, and cancel that work.

Why it exists

Autonomous systems regularly trigger work that may outlive a single MCP response:

• multi-step plans that need more than one round-trip
• slow upstream APIs
• workflows waiting on approval or feedback
• jobs intentionally detached from the inline response path

Rather than losing that work, DataGrout persists a task record and exposes it through five first-party tools.

Tools

tasks.status

Check the current state of a task by task_ref.

Use it when:

• you want to know whether a promoted task is still running
• you need the current status message or poll interval
• you want to confirm whether the task finished, failed, or was cancelled

Example:

{
  "name": "data-grout@1/tasks.status@1",
  "arguments": {
    "task_ref": "task_abc123"
  }
}

tasks.wait

Wait up to a bounded window for a task to finish.

Use it when:

• you want a reattach-like experience without committing to pure polling
• the task might complete soon, but you still need to stay under MCP/client timeout ceilings
• you want either the terminal result or a fresh in-progress snapshot in one call

Example:

{
  "name": "data-grout@1/tasks.wait@1",
  "arguments": {
    "task_ref": "task_abc123",
    "wait_ms": 25000
  }
}

tasks.list

List recent background tasks for the current server context.

Use it when:

• you lost the original response but want to rediscover active tasks
• you want to review recent background activity
• you want to locate a task before calling tasks.status or tasks.result

Example:

{
  "name": "data-grout@1/tasks.list@1",
  "arguments": {}
}

tasks.result

Fetch the final result payload for a completed task.

Use it when:

• tasks.status shows the task is completed
• you want the background result without re-running the original tool

Example:

{
  "name": "data-grout@1/tasks.result@1",
  "arguments": {
    "task_ref": "task_abc123"
  }
}

tasks.cancel

Cancel a running background task.

Use it when:

• the user no longer wants the result
• the task is stale or no longer relevant

Example:

{
  "name": "data-grout@1/tasks.cancel@1",
  "arguments": {
    "task_ref": "task_abc123"
  }
}

MCP timeout promotion

The MCP gateway can automatically promote work to a background task shortly before the protocol timeout wall. In that case, the inline response includes a task_ref and points agents toward tasks.wait for ergonomic reattach, while keeping tasks.status and tasks.result as the canonical explicit polling APIs.

Typical flow:

1. Call a long-running tool.
2. Receive a response saying the work was moved to the background, with a task_ref.
3. Reattach with tasks.wait, or poll with tasks.status.
4. Call tasks.result when the task is complete.

Composing with other suites

• Use with flow.into when a workflow may outlive a single inline response.
• Use with discovery.perform when an execution plan is promoted to background work. Task-monitoring reads routed through discovery.perform are fast-pathed so intelligent-interface clients can reattach cheaply without tripping duplicate-call protections.
• Use with scheduler and governor to inspect or cancel long-lived autonomous activity from another session.