Chat tools

The os.* tools the CEO chat offers a member: the company's directory, its tasks, and starting and checking runs.

Generated from the built-in tools registry. Do not edit by hand.

When the CEO talks to a member in the portal, the member can use these tools, and the member's own connected tools beside them. Chat has no gates of its own; spend still applies.

A conversation opened for one job, such as creating a task, also gets the tools kept for that job. A member’s everyday thread never does.

A run never answers a chat-only tool, so a task that declares one is refused when it is saved (tool_not_run_callable).

Tool What it does Effect
os.list_tasks The tasks of the roles the chatting member holds, plus OS-owned tasks. read
os.start_task Queue a run of a task of a role you hold, an OS task, or a colleague's task. write
os.get_run A run's status, why it stopped, and its recent events. read
os.read_run_log Read a bounded slice of a retained run log, including earlier command diagnostics. read
os.hand_off_task_brief Hand the brief a person agreed to over to the OS, which designs the task from it. write
os.list_runs The enterprise's runs, newest first, a page at a time. read
os.kpi_board The enterprise's KPI board: every signed-off company KPI and each team's key KPI, with its light. read
os.list_enterprise_kpis Every KPI of the enterprise, with its owner, target, cadence, light and last reading. read
os.finish_waiting Mark a Waiting row’s work finished, so it leaves the list. Touches no issue tracker. write
os.restart_waiting Restart a Waiting row’s work at a step of its pipeline, and get the new run. write
os.clear_blocker Take a stopped run off Blockers without running it again, as its Clear or Cancel does. write
os.inspect_task_contract Inspect the pinned or current task contract of a source run. read
os.inspect_execution Inspect a source run’s execution graph, history and latest continuation. read
os.preview_run_route Preview supported recovery targets without starting work. read
os.export_workflow_evidence Export a bounded, safe workflow evidence snapshot. read
os.return_file Hand back a text, Markdown or CSV file under your reply in this conversation. write
os.set_steps Record the steps you have lined up for the current request, each with its state, shown in the thread. write
os.connect_tool Show the person a Connect card for each tool they ask to connect, and hold what they asked to do with those tools until they are connected. write
os.use_tool Look up and call any other user-facing OS operation. write

Also offered here: memory.ask, memory.train, os.decide_gate, os.mail_list, os.mail_read, os.member_mailbox_actions, os.my_mail_list, os.my_mail_read, os.my_mail_attachment, os.my_mail_set_label, os.my_mail_set_handled, os.my_mail_set_many, os.my_mail_reply, os.my_mail_send, os.my_mail_forward, os.my_mail_delete, os.my_mail_actions, os.my_mail_start_action, os.my_mail_schedule_action, os.my_mail_unschedule_action, os.my_mail_contacts, os.my_mail_contact_save, os.my_mail_contact_delete, os.my_mail_signature, os.my_mail_signature_set, os.my_mail_addresses, os.my_mail_address_signature_set, os.get_enterprise_kpis, os.set_enterprise_kpis, os.get_team_kpis, os.set_team_kpis, kpi.record_reading, kpi.list_readings, role.list_kpis, role.define_kpi, role.edit_kpi, os.directory, os.list_blockers, os.list_open_gates, os.list_waiting, os.list_built_in_tools, os.chat_list, os.chat_read, os.chat_write, os.chat_open, os.list_roles, os.read_role, os.create_role, os.update_role, os.delete_role, os.add_role_task, os.remove_role_task, os.add_role_member, os.remove_role_member, os.list_task_definitions, os.read_task_definition, os.create_task, os.publish_task_version, os.set_task_run_status, os.set_task_schedule, os.remove_task_schedule, os.set_task_input_values, os.read_context, os.write_context, memory.upload, os.list_teams, os.read_team, os.create_team, os.update_team, os.delete_team, os.add_team_member, os.remove_team_member, os.add_work_item, os.list_work_items, os.read_work_item, os.update_work_item, os.close_work_item, os.publish_role, os.publish_team, which a run can call too.

os.list_tasks

The tasks of the roles the chatting member holds, plus OS-owned tasks.

What the model reads:

List every task of a role you hold, whatever team you sit on, plus OS-owned tasks. OS tasks are not a person.

No declared fields: the schema accepts any object.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: the CEO chat, the API.
  • API: GET /v1/tasks/held-by/:memberId (tasks:read)

os.start_task

Queue a run of a task of a role you hold, an OS task, or a colleague's task.

What the model reads:

Start a run of a task of a role you hold, an OS task, or a colleague’s task. Pass taskId or slug, and input matching the task’s fields; a field you leave out takes the task’s default. The run goes to a free member holding the task’s role, who may not be you; when every holder is busy it queues as pending. This only queues the run: check it with os.get_run before reporting on it.
Field Type Required Description
taskId string no The task id; pass exactly one of taskId or slug.
slug string no The task slug; pass exactly one of taskId or slug.
input object no Input matching the task fields.
idempotencyKey string no Required over MCP/API: a stable key for this start, at most 200 characters. Reuse on retries; use a new key for new work.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Chat keys on its session and tool call. MCP/API requires an idempotencyKey, scoped to the authenticated caller and task; a replay returns the original run, even if inputs differ.
  • Called by: the CEO chat, the API, the OS MCP server.
  • Returns: { runId, status, taskId, slug, origin }.
  • API: POST /v1/runs (runs:write)
Error When What happens
task_not_found No task in this enterprise has that id or slug. Tool error

Example:

{
  "slug": "weekly-report",
  "input": {
    "week": "2026-W39"
  }
}

os.get_run

A run's status, why it stopped, and its recent events.

What the model reads:

One run's status, why it stopped (blockedReason, when it is blocked), task id and input, and its last eight events. Not found for another enterprise's run.
Field Type Required Description
runId string yes The run id.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the CEO chat, the API, the OS MCP server.
  • Returns: Status, blockedReason (why a blocked run stopped, otherwise null), task id, input, the last eight events, latestRun (the newest later run on the same work: its id, task and status now; null when this run is the newest) and handOff (state none, handed_on or not_started, the successor runs with their status, and each hand-off not started with its slug and reason).
  • API: GET /v1/runs/:runId/os-tool (runs:read)
Error When What happens
runId_required runId is missing. Tool error
run_not_found No run in this enterprise has that id. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004"
}

os.read_run_log

Read a bounded slice of a retained run log, including earlier command diagnostics.

What the model reads:

Read the retained log of a run in this enterprise, including earlier tool results and failure diagnostics that are no longer in its recent events. Pass a real runId from os.list_runs or os.get_run. Read from offset 0, then follow nextOffset until null; each slice is at most 16000 characters. A missing log is an evidence gap, not proof that no failure occurred. Read-only; never retries, routes, clears or changes a run.
Field Type Required Description
runId string yes The run id.
offset integer, at least 0 no Character offset, from 0; use the previous nextOffset to continue.
limit integer, 1 to 16000 no Characters to read, up to 16000. Defaults to 8000.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: { runId, url, offset, body, total, nextOffset }: the configured portal evidence link (null when no origin is configured), retained log text, its total character count, and the next offset or null when complete.
  • API: GET /v1/runs/:runId/log-slice (runs:read)
Error When What happens
runId_required runId is missing. Tool error
run_not_found No run in this enterprise has that id. Tool error
log_not_found The run has no retained log. Tool error
invalid_offset offset is not a nonnegative safe integer. Tool error
invalid_limit limit is not an integer from 1 to 16000. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004",
  "limit": 8000
}

os.hand_off_task_brief

Hand the brief a person agreed to over to the OS, which designs the task from it.

What the model reads:

Hand the brief the person agreed to over to the OS, which designs the new task from it and asks the CEO to sign off on its definition before anything is created. Call it once, only after they have said yes to your read-back summary, with every part of the brief in their own words. It starts the design and returns its run; it does not create the task.
Field Type Required Description
brief object yes What the person agreed to, each part in plain language.
brief.goal string yes What the job is.
brief.success string yes How to tell it was done well.
brief.owner string yes The existing team and role that should own it.
brief.trigger string yes When it runs: on demand, on a schedule said in words, or after another task.
brief.inputs string yes What it needs each time it runs.
brief.tools string yes The connected tools it needs, naming any that is not connected.
brief.limits string yes What it must never do, what needs approval, and its budget.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the conversation and the tool call: the same call sent twice starts one run.
  • Called by: the CEO chat, the API.
  • Offered in: a conversation opened for create_task only, never in a member's everyday thread.
  • Returns: { runId, status, taskId }: the run designing the task.
  • API: POST /v1/tasks/from-brief (tasks:write)
Error When What happens
brief_required brief is missing, or says nothing about what the job is. Tool error
task_designer_not_found The enterprise has no task-designing task to hand the brief to. Tool error

Example:

{
  "brief": {
    "goal": "Chase unpaid invoices",
    "success": "Every invoice over 30 days old gets one polite reminder",
    "owner": "Finance team, accounts role",
    "trigger": "Every Monday morning",
    "inputs": "The list of overdue invoices",
    "tools": "Email, which is connected",
    "limits": "Never contact a customer twice in a week; refunds need approval; two dollars a run"
  }
}

os.list_runs

The enterprise's runs, newest first, a page at a time.

What the model reads:

List the enterprise's runs, newest first, one page at a time. Each run carries its status, task (id, name, slug), the member it runs as, compact work references, and when it was created, started and finished. The response is { data, total, page, limit, pages }.
Field Type Required Description
status string, one of pending, queued, running, waiting_on_gate, waiting_on_run, paused_spend, paused_plan, paused_team, paused, succeeded, failed, cancelled, skipped_overlap, blocked no Only runs in this status.
taskId string no Only runs of this task.
live boolean no true for only runs still in progress: not finished, not blocked, and not paused on spend, a plan limit or a switched-off team.
page integer, at least 1 no The page to read, from 1. Defaults to 1.
limit integer, 1 to 200 no Runs per page, up to 200. Defaults to 25.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: { data, total, page, limit, pages }, each run with status, task, member, compact work references and times. Full inputs, ceoAnswers, checkpoints and storage keys are omitted. To a run: its own enterprise's runs alone, each { id, status, taskId, taskName, taskSlug, memberId, assigneeName, input, blockedReason, stoppedReason, notBefore, createdAt, startedAt, finishedAt }.
  • API: GET /v1/runs/summary (runs:read)

Example:

{
  "status": "failed",
  "limit": 5
}

os.kpi_board

The enterprise's KPI board: every signed-off company KPI and each team's key KPI, with its light.

What the model reads:

The enterprise's KPI board, as HQ shows it: every company KPI the owner has signed off and each team's key KPI with its light (red off target, amber at risk, green on target), its trend (up, down, flat), when it was last read, the cadence it is read on, and whether that reading is overdue. A KPI nobody has read yet has no light (`rag` is null): it is never read and overdue, not green. A KPI still waiting for sign-off is not on the board. A team that has set no key KPI is named with none rather than left out. The response is { enterprise, teams }. Read-only: recording a reading is not a tool here.

Takes no arguments: no fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: the API, the CEO chat, the OS MCP server.
  • Returns: { enterprise, teams }: each signed-off company KPI, and each team with its key KPI or key: null when it has none. Every KPI carries its light, trend, lastReadAt, cadenceDays and whether it is overdue — derived from the readings themselves, so it matches HQ's board KPI for KPI.
  • API: GET /v1/enterprise/kpis (enterprise:read)

os.list_enterprise_kpis

Every KPI of the enterprise, with its owner, target, cadence, light and last reading.

What the model reads:

List every KPI of the enterprise, whatever layer owns it and whether or not it has been signed off, ordered by name then id. Each row carries its id (the kpiId the readings tools take), name, owner (layer and id), source (kind and ref), target (value, direction, AMBER band, on-target-worsening rule), cadence, current light, whether it is overdue, when it was signed off (null while it waits for sign-off, when it takes no reading), and its latest reading. The light is null when the KPI has no target or no reading yet. No arguments. Never another enterprise's KPIs.

Takes no arguments: no fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: the API, the CEO chat, the OS MCP server.
  • Returns: One row per KPI, each with id, name, ownerLayer (company, team, role, task, or null for a company KPI set before layers), ownerId, sourceKind (task or person), sourceRef, target, cadenceMinutes, light, overdue, signedOffAt (ISO 8601, or null) and lastReading (id, value, takenAt, recordedBy, runId), or null before the first reading.
  • API: GET /v1/kpis (kpis:read)

Example:

{}

os.finish_waiting

Mark a Waiting row’s work finished, so it leaves the list. Touches no issue tracker.

What the model reads:

Mark one piece of work on the Waiting list finished, as its Mark finished button does. Pass pipeline as os.list_waiting names it. The finish is recorded on the work’s newest run, attributed to you (a task’s call is attributed to its run), and takes it off the list; no run is started or stopped, and the issue or pull request is not touched. Refused when the work is not on the list, or when its execution is still doing other work. A later run on the same pipeline lists it again once that run ends.
Field Type Required Description
pipeline string yes The work, as owner/name#<number>, the way os.list_waiting names it.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A finished row is off the list, so a repeat is refused with not_waiting and records nothing more.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: { finished: true }.
  • API: POST /v1/waiting/finish (runs:write)
Error When What happens
waiting_field_required pipeline is missing or empty (400). Tool error
not_waiting The work is not on the Waiting list, or its execution is still doing other work (409). Tool error

Example:

{
  "pipeline": "acme/rocket#935"
}

os.restart_waiting

Restart a Waiting row’s work at a step of its pipeline, and get the new run.

What the model reads:

Restart one piece of work on the Waiting list at a step, as its Restart button does. Pass pipeline as os.list_waiting names it, and task: the slug of the step to run. The same task as the newest run retries it; another task of its pipeline routes the work there. The new run is open, so the work leaves the list, and the newest run records that you restarted it and where. Refused when the work is not on the list. A task’s restart is attributed to its run. Every restart is refused while the work’s execution is still doing other work, and preserves os.retry_run’s existing cap: a chain may be retried, routed or restarted 3 times; past that, escalate it.
Field Type Required Description
pipeline string yes The work, as owner/name#<number>, the way os.list_waiting names it.
task string yes The slug of the task to run: the newest run’s own task to retry it, or another task of its pipeline.

No other fields are accepted.

  • Effect: write.
  • Side effects: Starts a paid run of the task named.
  • Retry: Not retry-safe: a repeat acts again. While the run it started is open the work is off the list, so a repeat is refused with not_waiting. Once that run ends, a repeat starts another. A task’s call is keyed on the tool call: the same call sent twice starts one run and the repeat answers with it.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: The new run: its id, status (queued, or pending while its task or member is busy), taskId and input, with the rest of the run’s fields. A task’s call answers with id, status, taskId and input.
  • API: POST /v1/waiting/restart (runs:write)
Error When What happens
active_continuation The execution is still doing other work. Tool error
gate_authoritative A waiting, rejected or changes-requested gate still controls this work. Tool error
waiting_field_required pipeline or task is missing or empty (400). Tool error
not_waiting The work is not on the Waiting list (409). Tool error
task_not_in_pipeline The task is neither a successor of the newest run’s task nor one that already ran on this pipeline (409). Tool error
retry_limit_reached This chain has already been retried, routed or restarted 3 times. Waiting restart preserves the existing retry budget for people and tasks alike. Tool error

Example:

{
  "pipeline": "acme/rocket#935",
  "task": "review-pr"
}

os.clear_blocker

Take a stopped run off Blockers without running it again, as its Clear or Cancel does.

What the model reads:

Take one stopped run off Blockers without running it again, because nothing more is needed: its issue or pull request is closed, merged or parked, or it is a stale escalation nobody has to decide. A failed run, or one that finished on an outcome nothing follows, is cleared; a blocked run is cancelled. Pass runId as os.list_blockers names it, and note: why nothing more is needed, recorded on the run with your name. Choose workItemState: done only when you verified the work is complete, dropped when no longer wanted, ready only when it should be picked up again, or held to keep it parked. Omitted means held; clearing alone never requeues or completes work. A later run keeps its item.
Field Type Required Description
runId string yes The run id, as os.list_blockers names it.
workItemState string, one of held, ready, done, dropped no What happens to the stopped pipeline’s work item: held (default), ready to retry, done when verified complete, or dropped when no longer wanted.
note string yes Why nothing more is needed, in one line.

No other fields are accepted.

  • Effect: write.
  • Side effects: Settles the stopped pipeline’s held item only as workItemState requests; omission keeps it held. Records the decision in the item history.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A cleared or cancelled run is off Blockers, so a repeat is refused and changes nothing.
  • Called by: the API, the CEO chat, the OS MCP server.
  • Returns: The run as it now stands: cancelled for a blocked run, otherwise its own status with clearedAt set.
  • API: POST /v1/runs/:runId/clear-stopped (runs:write)
Error When What happens
invalid_work_item_state workItemState is not held, ready, done or dropped (400). Tool error
note_required note is missing or empty (400). Tool error
run_not_found No run with that id in this enterprise (404). Tool error
not_stopped:<status> The run is not on Blockers: it is still working, or it finished on an outcome its task follows (409). Tool error
already_retried A later run already retried or routed it (409). Act on that run instead. Tool error
already_cleared Someone already cleared it (409). Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000003",
  "note": "Parked until its sibling closes; the escalation has nothing to decide"
}

os.inspect_task_contract

Inspect the pinned or current task contract of a source run.

What the model reads:

Read the task and exact version a source run was pinned to (default version: pinned), or version: current for comparison. Includes structured outcome/finish contract, successors with conditions and caps, tools and approval gates. Skill text is paged (offset in characters, limit up to 16000), with its content hash and exact version provenance. A repaired current task does not change a historical pinned contract. No binding values, checkpoints or storage addresses.
Field Type Required Description
runId string yes The source run id in this enterprise.
version string, one of pinned, current no Pinned historical contract (default) or current task version.
offset integer, at least 0 no Offset from the previous nextOffset; starts at zero.
limit integer, 1 to 16000 no Skill characters per page, defaults to 4000.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: Tenant-scoped evidence with exact run and version provenance, pagination and explicit omissions. Refusals are evidence gaps; never infer success, rerun work or ask for credentials.
  • API: GET /v1/runs/:runId/task-contract (runs:read)
Error When What happens
run_not_found The source run does not exist in this enterprise. Tool error
task_contract_unavailable The source task or selected version is unavailable. Ask the workflow owner to inspect the retained definition. Tool error
execution_not_found No retained execution can be read. Preserve this evidence gap. Tool error
invalid_offset The offset is not a nonnegative integer. Tool error
invalid_limit The limit is outside the documented bound. Tool error
workflow_diagnostics_unavailable The API deployment does not provide the inspectors. Send the deployment gap to the workflow owner. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004"
}

os.inspect_execution

Inspect a source run’s execution graph, history and latest continuation.

What the model reads:

Read the source execution graph with version provenance, runs, causal links, paged event headers and latest continuation. Inspect the latest continuation before routing or escalating: pending and running work must not be restarted. Raw input, ceoAnswers, payloads, credentials and checkpoints are omitted. Acceptance of a continuation is separate from validation and delivery.
Field Type Required Description
runId string yes The source run id in this enterprise.
offset integer, at least 0 no Offset from the previous nextOffset; starts at zero.
limit integer, 1 to 100 no Event headers per page, at most 100; defaults to 25.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: Tenant-scoped evidence with exact run and version provenance, pagination and explicit omissions. Refusals are evidence gaps; never infer success, rerun work or ask for credentials.
  • API: GET /v1/runs/:runId/execution-evidence (runs:read)
Error When What happens
run_not_found The source run does not exist in this enterprise. Tool error
task_contract_unavailable The source task or selected version is unavailable. Ask the workflow owner to inspect the retained definition. Tool error
execution_not_found No retained execution can be read. Preserve this evidence gap. Tool error
invalid_offset The offset is not a nonnegative integer. Tool error
invalid_limit The limit is outside the documented bound. Tool error
workflow_diagnostics_unavailable The API deployment does not provide the inspectors. Send the deployment gap to the workflow owner. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004"
}

os.preview_run_route

Preview supported recovery targets without starting work.

What the model reads:

List actual supported recovery targets for this source run, or validate task (a target slug). Reports supported/allowed and actionable refusal, latest continuation and the unchanged retry limit. A preview is read-only and reserves nothing. os.route_run revalidates at acceptance; caps, spend and gates still apply. Workflow contract defects go to the workflow owner, never an invented application test stage.
Field Type Required Description
runId string yes The source run id in this enterprise.
task string no Optional target slug to validate; omit to list supported targets.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: Tenant-scoped evidence with exact run and version provenance, pagination and explicit omissions. Refusals are evidence gaps; never infer success, rerun work or ask for credentials.
  • API: GET /v1/runs/:runId/route-preview (runs:read)
Error When What happens
run_not_found The source run does not exist in this enterprise. Tool error
task_contract_unavailable The source task or selected version is unavailable. Ask the workflow owner to inspect the retained definition. Tool error
execution_not_found No retained execution can be read. Preserve this evidence gap. Tool error
invalid_offset The offset is not a nonnegative integer. Tool error
invalid_limit The limit is outside the documented bound. Tool error
workflow_diagnostics_unavailable The API deployment does not provide the inspectors. Send the deployment gap to the workflow owner. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004"
}

os.export_workflow_evidence

Export a bounded, safe workflow evidence snapshot.

What the model reads:

Export pinned/current structured task contracts with text hashes, execution graph, causal history and route diagnostics. Includes capture time, exact provenance, pagination and explicit omissions. Omits skill prose, raw inputs/ceoAnswers, tool and result payloads, binding values, checkpoints and storage addresses. Follow execution.history.nextOffset; inspect_task_contract explicitly pages skill text when needed.
Field Type Required Description
runId string yes The source run id in this enterprise.
offset integer, at least 0 no Offset from the previous nextOffset; starts at zero.
limit integer, 1 to 100 no Event headers per page, at most 100; defaults to 25.

No other fields are accepted.

  • Effect: read.
  • Retry: Safe: repeating the call changes nothing.
  • Called by: a run, the API, the CEO chat, the OS MCP server.
  • Returns: Tenant-scoped evidence with exact run and version provenance, pagination and explicit omissions. Refusals are evidence gaps; never infer success, rerun work or ask for credentials.
  • API: GET /v1/runs/:runId/workflow-export (runs:read)
Error When What happens
run_not_found The source run does not exist in this enterprise. Tool error
task_contract_unavailable The source task or selected version is unavailable. Ask the workflow owner to inspect the retained definition. Tool error
execution_not_found No retained execution can be read. Preserve this evidence gap. Tool error
invalid_offset The offset is not a nonnegative integer. Tool error
invalid_limit The limit is outside the documented bound. Tool error
workflow_diagnostics_unavailable The API deployment does not provide the inspectors. Send the deployment gap to the workflow owner. Tool error

Example:

{
  "runId": "5f0c1d2e-0000-4000-8000-000000000004"
}

os.return_file

Hand back a text, Markdown or CSV file under your reply in this conversation.

What the model reads:

Hand the person a file in this conversation: a drafted document as Markdown or text, or an export as CSV. Pass the filename, ending .md, .txt or .csv, and the whole file as text; it is saved as UTF-8. The file shows under the reply that ends this turn, where anyone who may work in this conversation can download it. A person’s file limits apply: 10 MB per file and 5 files per reply, within the plan’s storage. A refused file comes back as an error saying why, and nothing is saved. The response is { id, filename, sizeBytes, type }.
Field Type Required Description
filename string yes The name the file is saved under, ending .md, .txt or .csv.
content string yes The whole file, as text.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the conversation and the tool call: the same call sent twice stores one file.
  • Called by: the CEO chat, the API.
  • Returns: { id, filename, sizeBytes, type }: the file as it shows under your reply.
  • API: POST /v1/chats/:id/files (chats:write)
Error When What happens
filename_required filename is missing or empty. Tool error
content_required content is missing or is not text. Tool error
chat_file_unsupported_type The filename does not end .txt, .md or .csv: a teammate returns text, Markdown or CSV only. Tool error
chat_file_limit_exceeded The file is over 10 MB, or 5 files already wait for this reply. Tool error
plan_limit_reached The file would take the enterprise past its plan’s storage. Tool error
chat_files_not_stored This conversation has nowhere to store a file. Tool error

Example:

{
  "filename": "q3-revenue.csv",
  "content": "Quarter,Revenue\nQ3,1200\n"
}

os.set_steps

Record the steps you have lined up for the current request, each with its state, shown in the thread.

What the model reads:

Write down the steps you have lined up for the person’s current request, and where each one stands, so the person sees them in this conversation just above where they write. Send the whole list every time, in order: each call replaces the list this conversation keeps, so send every step again with its state brought up to date, and send an empty list to clear it. A state is todo, in_progress, done or skipped; mark a step skipped when the person tells you to skip it, rather than leaving it out. At most 20 steps, each title one line of at most 200 characters. The list belongs to this conversation alone, and you are shown it again at the start of every turn. The response is { steps }: the list as it is now kept.
Field Type Required Description
steps array of object yes The whole list, in order: at most 20 steps. An empty list clears it.
steps[].title string yes What the step is, in a few words: at most 200 characters.
steps[].state string, one of todo, in_progress, done, skipped yes Where the step stands: todo, in_progress (under way), done, or skipped when the person said to skip it.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the conversation and the tool call: the same call sent twice sets the list once. Each call replaces the whole list, so a repeat leaves the same list.
  • Called by: the CEO chat.
  • Returns: { steps }: the whole list as it is now kept, each { title, state }, and an empty list once cleared.
Error When What happens
steps_required steps is missing or is not a list. Tool error
steps_too_many The list has more than 20 steps. Nothing is kept. Tool error
step_title_required A step’s title is missing, or blank once trimmed. Nothing is kept. Tool error
step_title_too_long A step’s title is over 200 characters once trimmed. Nothing is kept. Tool error
step_state_invalid A step’s state is not todo, in_progress, done or skipped. Nothing is kept. Tool error

Example:

{
  "steps": [
    {
      "title": "Read the brief",
      "state": "done"
    },
    {
      "title": "Draft the plan",
      "state": "in_progress"
    },
    {
      "title": "Send it round for comments",
      "state": "todo"
    }
  ]
}

os.connect_tool

Show the person a Connect card for each tool they ask to connect, and hold what they asked to do with those tools until they are connected.

What the model reads:

Answer a request to connect tools, such as "connect Slack" or "connect Slack to Linear and post this week’s open bugs". Pass the person’s words as request, each tool they named as they wrote it in tools, and anything they asked you to do once the tools are connected in afterwards. Each tool is answered in its own result: card (a Connect card is shown in the thread; the person signs in there), connected (it already is: say so and carry on), expired (its sign-in no longer works, so a card is shown to connect it again), which_one or did_you_mean (ask the person the question in message before anything else), not_in_chat (it cannot be connected from the chat yet: give the person the message, which links the Tools page) or not_allowed (this person may not connect tools: tell them who can, in the message’s own words). With afterwards and a tool still to connect, the request is held: say up front what you will do once they are connected, and do nothing of it until then. The OS tells you here when they are, and you do it then. Never ask the person for a key, a token or a password: the card is how a tool is connected. Disconnecting is only on the Tools page.
Field Type Required Description
request string yes What the person asked, in their own words.
tools array of string yes Each tool the person asked to connect, as they named it.
afterwards string no What the person asked you to do once the tools are connected, in a few words. Leave it out when they only asked to connect.

No other fields are accepted.

  • Effect: write.
  • Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A tool asked for twice in one conversation keeps one card, and a repeat holds the same request again in place of the one held.
  • Called by: the CEO chat.
  • Returns: { results, held?, message }: one result per tool named, each { name, kind, state?, message } with display names only, held ({ request, afterwards, waitingFor, done }) when what the person asked waits on a tool, and message, what to tell the person.
Error When What happens
tools_required tools is missing or names no tool. Tool error
not_allowed Whoever sent the turn may not connect the company’s tools. No card is shown and nothing is held. Tool error

Example:

{
  "request": "connect Slack to Linear and post this week’s open bugs",
  "tools": [
    "Slack",
    "Linear"
  ],
  "afterwards": "post this week’s open bugs"
}

os.use_tool

Look up and call any other user-facing OS operation.

What the model reads:

Access the full OS tool catalog. Pass tool only to read its exact input schema and instructions. Then call again with tool and arguments to perform it. Calls use the current requester’s permissions, attribution and normal confirmations. Only the listed OS operations are accepted; run-only and vendor tools cannot be called through this entry point.
memory.ask: Ask enterprise memory a question, and get an answer with its evidence.
memory.train: Teach enterprise memory one note about a task, at the task's layer by default.
os.mail_list: List a member's inbox, newest first: metadata and a snippet, no bodies.
os.mail_read: Read one message from a member's inbox.
os.member_mailbox_actions: List the one-click buttons a member's mailbox offers: the tasks that declare a mailbox action and run as a role the member holds.
os.my_mail_list: List the mail in your own mailbox, newest first: metadata and a snippet, no bodies.
os.my_mail_read: Read one message from your own mailbox.
os.my_mail_attachment: Fetch one attachment of a message in your own mailbox, base64-encoded.
os.my_mail_set_label: Set the labels on a message in your own mailbox.
os.my_mail_set_handled: Record where a message in your own mailbox stands: unhandled, replied, skipped, or snoozed until a date.
os.my_mail_set_many: Set the labels, the handled state, or both on many messages in your own mailbox at once.
os.my_mail_reply: Reply to a message in your own mailbox, from your own address, with no approval step.
os.my_mail_send: Send a new mail from your own address, with no approval step.
os.my_mail_forward: Forward a message from your own mailbox to somebody else, from your own address, with no approval step.
os.my_mail_delete: Delete a message from your own mailbox for good.
os.my_mail_contacts: List or search your own contacts: the people you have written to, and those you added.
os.my_mail_contact_save: Add a contact to your own mailbox, or name one already there.
os.my_mail_contact_delete: Remove a contact from your own mailbox.
os.my_mail_signature: Read the signature the OS adds to every mail you send, reply and forward.
os.my_mail_signature_set: Set or clear the signature the OS adds to every mail you send.
os.my_mail_addresses: List your own extra addresses, each with the signature mail from it carries.
os.my_mail_address_signature_set: Set or clear the signature mail from one of your extra addresses carries.
os.get_enterprise_kpis: The company's KPI targets, bands, cadence and source.
os.set_enterprise_kpis: Replace the company's KPI target list.
os.get_team_kpis: A team's KPI targets, including its key KPI.
os.set_team_kpis: Replace a team's KPI target list and key KPI.
kpi.record_reading: Record one reading of a KPI by hand: the value, when it was taken, and who or what took it.
kpi.list_readings: One KPI's readings, newest first, corrected ones included.
role.list_kpis: A role's KPIs, oldest first, with the team KPI each serves, its sign-off, light, trend and readings.
role.define_kpi: Propose a KPI on a role, waiting for a person to sign it off.
role.edit_kpi: Change a role KPI's fields; a signed-off one only a person changes.
os.list_blockers: What has stopped: failed, stalled, blocked and spend-paused runs, and stopped pipelines, with who owns each.
os.list_waiting: Open work nothing is working on: no live or queued run, no waiting decision, not on Blockers, not finished.
os.list_built_in_tools: Every built-in tool a run can call, with its summary and whether it reads or writes.
os.chat_list: List chat threads, most recently active first: who each is with, its state and its last message.
os.chat_read: Read one chat thread: its messages, oldest first.
os.chat_write: Write one message in a chat thread, as yourself.
os.chat_open: Open a new chat thread with a member.
os.read_run_log: Read a bounded slice of a retained run log, including earlier command diagnostics.
os.list_runs: The enterprise's runs, newest first, a page at a time.
os.kpi_board: The enterprise's KPI board: every signed-off company KPI and each team's key KPI, with its light.
os.list_enterprise_kpis: Every KPI of the enterprise, with its owner, target, cadence, light and last reading.
os.finish_waiting: Mark a Waiting row’s work finished, so it leaves the list. Touches no issue tracker.
os.restart_waiting: Restart a Waiting row’s work at a step of its pipeline, and get the new run.
os.clear_blocker: Take a stopped run off Blockers without running it again, as its Clear or Cancel does.
os.inspect_task_contract: Inspect the pinned or current task contract of a source run.
os.inspect_execution: Inspect a source run’s execution graph, history and latest continuation.
os.preview_run_route: Preview supported recovery targets without starting work.
os.export_workflow_evidence: Export a bounded, safe workflow evidence snapshot.
os.create_task: Create one of the enterprise’s own tasks.
os.publish_task_version: Publish a new version of one of the enterprise’s tasks, naming the version it was read from.
os.set_task_run_status: Enable or disable a task.
os.set_task_schedule: Set a task schedule.
os.remove_task_schedule: Remove a task schedule.
os.set_task_input_values: Set this enterprise's own values for a task's inputs.
os.read_context: Read enterprise workflow context outside a run.
os.write_context: Set enterprise workflow context outside a run.
memory.upload: Upload one note to a team or the whole enterprise.
os.publish_role: Publish one of the enterprise’s roles to the catalog, by its portable name and slug.
os.publish_team: Publish one of the enterprise’s teams to the catalog, with its roles, as the portal’s Share does.
Field Type Required Description
tool string, one of memory.ask, memory.train, os.mail_list, os.mail_read, os.member_mailbox_actions, os.my_mail_list, os.my_mail_read, os.my_mail_attachment, os.my_mail_set_label, os.my_mail_set_handled, os.my_mail_set_many, os.my_mail_reply, os.my_mail_send, os.my_mail_forward, os.my_mail_delete, os.my_mail_contacts, os.my_mail_contact_save, os.my_mail_contact_delete, os.my_mail_signature, os.my_mail_signature_set, os.my_mail_addresses, os.my_mail_address_signature_set, os.get_enterprise_kpis, os.set_enterprise_kpis, os.get_team_kpis, os.set_team_kpis, kpi.record_reading, kpi.list_readings, role.list_kpis, role.define_kpi, role.edit_kpi, os.list_blockers, os.list_waiting, os.list_built_in_tools, os.chat_list, os.chat_read, os.chat_write, os.chat_open, os.read_run_log, os.list_runs, os.kpi_board, os.list_enterprise_kpis, os.finish_waiting, os.restart_waiting, os.clear_blocker, os.inspect_task_contract, os.inspect_execution, os.preview_run_route, os.export_workflow_evidence, os.create_task, os.publish_task_version, os.set_task_run_status, os.set_task_schedule, os.remove_task_schedule, os.set_task_input_values, os.read_context, os.write_context, memory.upload, os.publish_role, os.publish_team yes The OS operation to look up or call.
arguments object no Omit to look up the schema. Supply an object (including {} for no inputs) to call the operation.

No other fields are accepted.

  • Effect: write.
  • Retry: Not retry-safe: a repeat acts again. A schema lookup only reads. An executed operation retains its own effect and retry rules.
  • Called by: the CEO chat.
Error When What happens
tool_not_offered The requested tool is not in the user-facing OS catalog. Tool error