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, 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 four 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.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 instructs the caller to poll with Tasks tools.

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. Poll 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.
• Use with scheduler and governor to inspect or cancel long-lived autonomous activity from another session.