Skip to main content
Every Substrate session starts cold — your agent has no memory of the last one. The 32 MCP tools are designed around that reality: a short, fixed sequence orients a fresh session, and every write returns an envelope that keeps the next step honest. Follow the loop below and the board stays trustworthy across sessions and agents.

​
The Loop

1

Orient

Call whoami first. It returns the project, every board with its id, and a set of hints. One call is enough to orient a session that has no memory of the last one.Then call get_board_substrate for the board you’ll work in. Cache the response — it carries the board’s groups, field_schema, policies, and resolved team. That payload stops your agent from guessing ids or inventing field names.
2

See what exists

Call list_tasks before planning anything. Reconcile your plan with the board rather than adding a parallel copy of work already tracked.Filters are top-level parameters, not nested:
An unrecognized key is silently ignored — a filter that doesn’t narrow results usually means the parameter name is wrong.
3

Record the work

Call create_task with board_id, group_id, title, and agent_name. Optionally include a markdown description and custom_data for any custom fields defined in the board’s field_schema.
4

Advance it

Call update_task to change fields or move groups. Send only what changed, plus the version from your last read and your agent_name. Substrate uses optimistic concurrency — sending a stale version is refused so you never silently overwrite a peer’s work.
5

Explain it

Call add_comment to record decisions and rationale. Call get_task_history to see what happened while you were away. State belongs in fields; reasoning belongs in comments.

​
Read the Envelope

Every write returns a response envelope. Read it every time.
Two things to do with it on every write:
  1. Keep the returned version for your next update_task. It is your concurrency token.
  2. Read policies_fired. A transition_guard entry means a rail engaged. An agent_responsibility entry carries a message written by whoever authored the board, aimed at exactly this moment — surface it or act on it. Do not treat it as noise.

​
When a Move Is Blocked

A blocked write returns transition_blocked with a message naming what is missing. Read the message, satisfy the prerequisite, and retry. If the missing field is human_only: stop trying. Your write tools refuse it by design — that refusal is what makes the gate real. Call list_pending_approvals and report what is waiting, grouped by board, naming the exact command for each item:
The human can also run substrate pending-approval for the same report, or see a “pending approval” pill on the task in the UI.

​
Verify a Gate Without a Throwaway Task

check_transition dry-runs “would moving task X to group Y be allowed?” against the real guards and writes nothing. It returns:
Use it to confirm a gate is live and to see exactly what a move needs before you attempt it.

Conventions for Reliable Agent Behavior

The habits that keep a shared Substrate board trustworthy across multiple sessions and concurrent agents.