agent_name. Task writes require the version from your last read of that task; comment writes do not. All return a write envelope.
Tasks
create_task
Creates a new task and places it in the specified group.
string
required
The board to create the task on.
string
required
The group to place the task in.
string
required
The task title.
string
required
A stable identifier for the calling agent. Recorded as the creator in the event log.
string
Task description. Markdown is supported.
object
Custom field values. Validated lazily against the board’s
field_schema.string
Providing a parent task id makes this a subtask.
custom_data cannot include a human_only field. The tool refuses it — that refusal is the mechanism behind human gates. If a required field is human_only, create the task without it and use list_pending_approvals to surface the approval request.update_task
Updates an existing task. Send only the fields you are changing — omitted fields are left as-is.
string
required
The task id.
integer
required
The version from your last read. A stale version returns
version_mismatch.string
required
A stable identifier for the calling agent.
string
New title.
string
New description. Markdown is supported.
object
Merges key-by-key into existing
custom_data. Set a key to null to delete it.string
Moving the task to a different group. This change is what a transition guard inspects.
transition_blocked error and appends a move_blocked event to the task’s history. Read the error message, satisfy the requirement, and retry. If the blocking field is human_only, you have no path to clear it yourself — call list_pending_approvals and report the approval command to the human.
archive_task
Soft-deletes a task. Sets archived_at; preserves the full history. Nothing hard-deletes a task in Substrate.
string
required
The task id.
integer
required
The version from your last read.
string
required
A stable identifier for the calling agent.
unarchive_task
Restores an archived task. Clears archived_at; history is preserved.
string
required
The task id.
integer
required
The version from your last read.
string
required
A stable identifier for the calling agent.
Comments
add_comment
Adds a comment to a task. Top-level comments and threaded replies are both supported.
string
required
The task to comment on.
string
required
Comment body. Markdown is supported.
string
required
A stable identifier for the calling agent.
string
Providing a parent comment id makes this a reply in that thread.
object
Custom field values. Validated against
field_schema.comments.edit_comment
Edits the body or custom data of an existing comment. Comments are last-write-wins — there is no version requirement.
string
required
The comment id.
string
required
A stable identifier for the calling agent.
string
Replacement body. Markdown is supported.
object
Merges key-by-key. Set a key to
null to delete it.Because comments are last-write-wins, the envelope returns
version: null for comment writes.archive_comment
Archives a comment. The comment body is retained in history.
string
required
The comment id.
string
required
A stable identifier for the calling agent.
Fields or Comments?
When deciding where to store information, apply this rule:- Put it in a field if a policy must read it, if you will filter on it, or if it represents the task’s current state.
- Put it in a comment if it is reasoning — why this approach was chosen, what was rejected, what the next session needs to know.