> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ishlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# participant tools

> MCP tool reference for the participant domain.

## `participant_cancel`

**Tier:** write · **Tags:** participant, write

Cancel queued or running simulations - the reversible "stop" half of
the cancel/extend pair; a cancelled run can be resumed from its last
interaction via `participant_extend` (`docs_get("concepts/extending-a-simulation")`).

Walks each affected participant to `cancelled`. Persisted artifacts
(participant rows, interactions, transcripts) survive - a status flip,
not a data removal, hence `WRITE` not `DESTRUCTIVE`. Participants
already terminal are skipped without dispatch.

Set exactly one scope of `participant_id` / `study_id` /
`iteration_id` / `ask_id`:

* `participant_id`: cancel that single participant's simulation.
* `study_id`: cancel every active participant under any iteration of the
  study.
* `iteration_id`: cancel every active participant under one iteration.
* `ask_id` (+ optional `round`): cancel active participants in that ask,
  scoped to one round when `round` is given (1-indexed) or all rounds
  otherwise.

`participant_id`: UUID or alias (`pt-...`) of one participant.
`study_id`: UUID or alias (`s-...`) - fans out across all iterations.
`iteration_id`: UUID or alias (`i-...`) - fans out across one iteration.
`ask_id`: UUID or alias (`a-...`) - fans out across the ask's people.
`round`: 1-indexed round filter (only meaningful with `ask_id`).

Each cancelled row carries `participant_id` / `success`; each skipped
row `participant_id` / `reason` (`"already_terminal"` for one that
was terminal before the call); the `summary` carries `total` /
`cancelled_count` / `skipped_count`.

**Returns** `{"cancelled": [...], "skipped": [...], "summary": {...}}`.
`cancelled[*].success` is `False` when the per-participant endpoint
returned an error envelope, the text in the row's optional `status`.

### Parameters

<ParamField body="participant_id" type="string">
  UUID or short alias (e.g. 'w-6ec', 'p-abc', 'pt-072')
</ParamField>

<ParamField body="study_id" type="string">
  UUID or short alias (e.g. 'w-6ec', 'p-abc', 'pt-072')
</ParamField>

<ParamField body="iteration_id" type="string">
  UUID or short alias (e.g. 'w-6ec', 'p-abc', 'pt-072')
</ParamField>

<ParamField body="ask_id" type="string">
  UUID or short alias (e.g. 'w-6ec', 'p-abc', 'pt-072')
</ParamField>

<ParamField body="round" type="integer">
   
</ParamField>

## `participant_extend`

**Tier:** long-running · **Tags:** dispatch, participant

Resume a terminal participant with `additional_steps` more turns - the
reversible "start" half of the `participant_cancel` + extend pair
(`docs_get("concepts/extending-a-simulation")`).

The source must be terminal (`completed` / `failed` / `cancelled`).
The backend spawns a **new** participant under the same iteration,
branched from the source's last interaction; the source row is untouched.

Bills credits per completed added step; live rates in
`account_usage().rates`.

`participant_id`: UUID or alias (`pt-...`) of the source participant.
`additional_steps`: more interactions to allow past the original cap.
Default 10; capped server-side (the failure envelope names the bound).
`instruction`: optional user message injected as overriding direction for
the rest of the run (e.g. "Stop browsing - switch to the German picker.").
`wait`: when True, block until the new participant is terminal. Default
False - return immediately with the dispatched id.
`timeout`: seconds to wait when `wait=True`. Default 240 - under the
\~300 s idle limit at which Claude Code kills a silent call. On elapse a
`wait_timeout` envelope returns while the run continues server-side,
carrying the ids and a `next_action` hint that points at the resume
poll. See `docs_get("reference/long-running-jobs")`.

**Returns** a `RunStudyResponse` keyed by `ok`;
`dispatch.participant_ids` carries the new participant id, and
`wait_timeout` means the dispatch worked but the wait poll ran out.
Full shape: docs\_get("reference/responses").

### Parameters

<ParamField body="participant_id" type="string" required>
  UUID or short alias (e.g. 'w-6ec', 'p-abc', 'pt-072')
</ParamField>

<ParamField body="additional_steps" type="integer">
  Default: `10`.
</ParamField>

<ParamField body="instruction" type="string">
   
</ParamField>

<ParamField body="wait" type="boolean">
  Default: `false`.
</ParamField>

<ParamField body="timeout" type="number">
  Default: `240.0`.
</ParamField>