Task: Reference

Tools for authoring, updating, and reviewing kid-facing tasks. See Task for the conceptual page.

The external task language is runMode-driven. Pick a mode (self_check, conversation, canvas), fill the matching *Spec object, set the scheduleSpec, optionally a rewardSpec. The full external contract lives at sprout://task/authoring-guide (your agent reads this resource before authoring).

`task.create`Safe to retry

Author a new task and assign it to one or more kids.

Scope: task:write

Parameters

Name	Type	Required	Description
`name`	`string`	yes	What shows on the kid's card.
`assignChildIds`	`string[]`	no	UUID(s) of kids. One of this or `assignAllChildren` required.
`assignAllChildren`	`boolean`	no	If true, assigns to every kid in the family.
`runMode`	`"self_check" \| "conversation" \| "canvas"`	no	Default `self_check`. Selects which spec object is required.
`conversationSpec`	`object`	no	Required iff `runMode:"conversation"`. Fields: `goalType`, `guidance` (non-empty, ≤1000 chars), `minResponses`, `effort`, `grading`, `dailyTarget`.
`canvasSpec`	`object`	no	Required iff `runMode:"canvas"`. Field: `canvasId`. Requires `assignmentSkillId` linking that canvas.
`scheduleSpec`	`object`	yes	Fields: `taskType` (`"schedule"` \| `"onetime"`), `days`, `oneTimeDate`, `startMinutes`, `durationMinutes`.
`rewardSpec`	`object`	no	`{ gems: int ≥ 0 }`. Omit for no reward.
`assignmentSkillId`	`string`	no	UUID of a skill to govern this task. Required when `runMode:"canvas"`.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.create",
    "arguments": {
      "name": "Daily check-in",
      "assignChildIds": ["a4b9-..."],
      "runMode": "conversation",
      "conversationSpec": {
        "goalType": "share",
        "guidance": "Ask about one highlight from today, one lowlight, and one thing they look forward to. Listen well; reflect back."
      },
      "scheduleSpec": {
        "taskType": "schedule",
        "days": ["mon","tue","wed","thu","fri"],
        "startMinutes": 1020
      },
      "rewardSpec": { "gems": 3 }
    }
  }
}

Returns. { taskId: string }

Response example

JSON

{
  "result": {
    "taskId": "01c0-...",
    "nextStep": "Task is live on the kid's iPad. Next, watch task.review for completions."
  }
}

Errors

BAD_INPUT conversation-needs-guidance: runMode:"conversation" without non-empty conversationSpec.guidance.
BAD_INPUT canvas-needs-a-skill: runMode:"canvas" without assignmentSkillId or with a skill that doesn't link the canvas.
BAD_INPUT one-mode-only: Spec object doesn't match the runMode.
PERMISSION_DENIED: assignChildIds contains an id outside the family.

`task.update`Safe to retry

Partial-patch update. Pass only the fields you want to change. Invariants are re-checked against the effective task (patch composed onto stored task).

Scope: task:write

Parameters

Name	Type	Required	Description
`taskId`	`string`	yes	The task to update.
`name`	`string`	no	Same shape as `task.create`.
`runMode`	`discriminator`	no	Flipping mode requires the matching spec object.
`conversationSpec / canvasSpec / scheduleSpec / rewardSpec`	`object`	no	Same shapes as `task.create`.
`assignChildIds`	`string[]`	no	Adds children (does not remove).
`assignAllChildren`	`boolean`	no	Assigns to every child. Wins over `assignChildIds` if both set.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.update",
    "arguments": {
      "taskId": "01c0-...",
      "rewardSpec": { "gems": 5 },
      "conversationSpec": {
        "goalType": "share",
        "guidance": "Updated: today, ask specifically about PE class."
      }
    }
  }
}

Returns. { taskId: string, changedFields: string[] }

Response example

JSON

{
  "result": {
    "taskId": "01c0-...",
    "changedFields": ["rewardSpec", "conversationSpec"]
  }
}

Notes. If you change sourceSkillId and assignChildIds in the same call, the newly-assigned children are linked to the new skill in one transaction.

`task.list`

List tasks with cursor pagination. Filter by child, status, type.

Scope: task:read

Parameters

Name	Type	Required	Description
`assignedChildIds`	`string[]`	no	Filter to tasks assigned to these kids.
`status`	`"open" \| "completed" \| "all"`	no	Default `open`.
`taskType`	`"schedule" \| "onetime"`	no	Optional.
`cursor`	`string`	no	From a previous response's `nextCursor`.
`limit`	`int`	no	Default 50.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.list",
    "arguments": {
      "assignedChildIds": ["a4b9-..."],
      "status": "open",
      "limit": 50
    }
  }
}

Returns. { items: TaskSummary[], nextCursor: string | null }

Response example

JSON

{
  "result": {
    "items": [
      {
        "taskId": "01c0-...",
        "name": "Daily check-in",
        "runMode": "conversation",
        "status": "open",
        "nextFireAt": "2026-05-24T17:00:00-04:00"
      }
    ],
    "nextCursor": null
  }
}

`task.describe`

Read a task back in the external runMode + *Spec shape. Use to confirm exactly what a task is without guessing.

Scope: task:read

Parameters

Name	Type	Required	Description
`taskId`	`string`	yes	The task to describe.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.describe",
    "arguments": { "taskId": "01c0-..." }
  }
}

Returns. Task (external shape)

Response example

JSON

{
  "result": {
    "taskId": "01c0-...",
    "name": "Daily check-in",
    "assignChildIds": ["a4b9-..."],
    "runMode": "conversation",
    "conversationSpec": {
      "goalType": "share",
      "guidance": "Ask about one highlight..."
    },
    "scheduleSpec": {
      "taskType": "schedule",
      "days": ["mon","tue","wed","thu","fri"],
      "startMinutes": 1020
    },
    "rewardSpec": { "gems": 3 }
  }
}

Errors

DOMAIN_NOT_FOUND: Task not visible to this family.

`task.complete`

Fuzzy-match a kid's description against their open tasks and complete the match.

Scope: task:write

Parameters

Name	Type	Required	Description
`childId`	`string`	yes	Whose task.
`description`	`string`	yes	What the kid says they did.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.complete",
    "arguments": {
      "childId": "a4b9-...",
      "description": "I tidied my room"
    }
  }
}

Returns. { matched: { taskId, name } | null, suggestions: TaskSummary[] }

Response example

JSON

{
  "result": {
    "matched": { "taskId": "01c0-...", "name": "Tidy your room" },
    "suggestions": []
  }
}

Notes. If suggestions is returned (ambiguous match), confirm with the user before approving.

`task.review`

Approve or deny a completed task. Required to release any reward.

Scope: task:write

Parameters

Name	Type	Required	Description
`taskId`	`string`	yes	The completed task.
`action`	`"approve" \| "deny"`	yes	Outcome.
`reason`	`string`	no	Required on `deny`.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.review",
    "arguments": {
      "taskId": "01c0-...",
      "action": "approve"
    }
  }
}

Returns. { taskId, status }

Response example

JSON

{
  "result": { "taskId": "01c0-...", "status": "approved" }
}

Notes. Confirm with parent before deny.

`task.delete`

Permanently delete a task. Destructive; confirm with parent.

Scope: task:write

Parameters

Name	Type	Required	Description
`taskId`	`string`	yes	The task to delete.

Request example

JSON

{
  "method": "tools/call",
  "params": {
    "name": "task.delete",
    "arguments": { "taskId": "01c0-..." }
  }
}

Returns. { deleted: true }

Response example

JSON

{
  "result": { "deleted": true }
}

Task

task.createSafe to retry

task.updateSafe to retry

task.list

task.describe

task.complete

task.review

task.delete

See also

`task.create`Safe to retry

`task.update`Safe to retry

`task.list`

`task.describe`

`task.complete`

`task.review`

`task.delete`