OS tools
The os.* tools a run can call: execution labels, gate summaries, questions for the CEO, self-improvement, mail, company state, shared context, unblocking runs, planning, the CEO’s brief and chat threads.
Generated from the built-in tools registry. Do not edit by hand.
os.* tools are answered by the OS itself. They need no vendor binding, and none of them calls a vendor. A task still declares each one it calls in its tools, like any other tool.
Shared context (os.set_context, os.get_context, os.delete_context) is a JSON value one run stores and a later run of any task can read. A task version names the key prefixes it wants, and those keys arrive in the run input as context before the model is called. It is bookkeeping between runs. It is not memory, and it is not a place for a secret.
Everything the OS does not have to do itself (send mail, post a message, file an issue) is a vendor tool the enterprise binds, never an os.* tool. The CEO chat has a few os.* tools of its own: see Chat tools.
Chat reaches every person-facing OS tool exposed over the API or MCP under the requester’s current permissions. Gates can be listed and decided directly, on the person’s instruction. Other operations are reached through os.use_tool: look up the named tool’s schema, then pass its arguments to call it. A tool written for a run (a member’s mailbox, a note about a task) is looked up in a person’s shape that names the member or task the run would supply, shown under “What chat reads”. Newly exposed writes ask for confirmation on every call; private mail remains the requester’s alone. Run-only tools keep their run context.
The company-state tools (os.inspect_enterprise, os.directory, os.list_blockers, os.list_open_gates, os.list_waiting) only read. None of them approves, rejects, retries or clears anything, and calling one never opens or resolves a gate. The Waiting list is worked with os.finish_waiting and os.restart_waiting: by a person’s own agent over the API and the OS MCP server, and by a task that declares them, answered as its run under the same rules, a restart also sharing os.retry_run’s task retry cap (see Chat tools). A person’s own agent takes a stopped run off Blockers with os.clear_blocker, as its Clear or Cancel does; a run does not call that one. A person’s own agent decides a waiting gate with os.decide_gate, over the API and the OS MCP server under their own gates:write, as the card in Needs you does: the decision is recorded as them, and the run resumes, routes or ends as it does from the portal. A run never calls it, so a task that declares it is refused when it is saved (tool_not_run_callable).
The unblocking tools (os.retry_run, os.route_run, os.clear_run, os.escalate_run) move the runs on Blockers: start one again, send its work to another stage of its pipeline, take one off, or hand one to its team lead or the CEO. None of them decides a gate.
When work stops on a red default branch, the OS holds it on that shared cause and starts one run of the repair task the successor edge names, with the cause in its input as sharedCause. That run files the repair issue with the enterprise’s own code-host tools, then reports its number with os.attach_repair. The OS files nothing itself. Once the repair issue’s work item is done, the OS re-queues every run the cause held.
The chat thread tools (os.chat_list, os.chat_read, os.chat_write, os.chat_open) are a member’s conversations with the enterprise’s people, as the mail tools are their mailbox. Every caller reads and writes as who it is. A run is its assigned member: it sees that member’s threads only, and what it writes is the member speaking, left for the people to read, so the run never waits for a reply. An API token or the MCP server is the person’s side: what it writes is a message to the member, who replies. A message a run writes is not something the member remembers when a person later talks to them in that thread.
The Organisation tools (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) are the portal’s role forms for a person’s own agent, over the API, the OS MCP server and the CEO chat, under the person’s own roles:read or roles:write. A run never calls them, so a task that declares one is refused when it is saved (tool_not_run_callable): inside a run, a change to the organisation is a plan a person signs off.
The task definition tools (os.list_task_definitions, os.read_task_definition) read the enterprise’s tasks as they are live, for a person’s own agent over the API and the OS MCP server, under the person’s own tasks:read. The list marks each task builtIn when it is a shared built-in definition, and the read gives one task’s skill text, declared fields, version number and current version id. They are not os.list_tasks and os.read_task, which answer which tasks a member may start. A run never calls them either, so a task that declares one is refused when it is saved (tool_not_run_callable): a task must not read and rewrite itself.
The task write tools (os.create_task, os.publish_task_version) create an enterprise task and publish a new version of one, for a person’s own agent over the API and the OS MCP server, under the person’s own tasks:write. Publishing names the version that was read (baseVersionId, from os.read_task_definition). A field left out keeps its current value. Setting visibility to public or private on that publish also needs catalog:write. A run never calls them by these names, so a task that declares one is refused when it is saved (tool_not_run_callable); the names stay undeclarable. A task may reach them only through a bound connection to the OS’s own MCP server, with a gate on every write that server serves, and a run cannot publish the task it is running (self_publish_refused). A built-in task is not created or edited this way.
The team tools (os.list_teams, os.read_team, os.create_team, os.update_team, os.delete_team, os.add_team_member, os.remove_team_member) are the portal’s team forms on the same terms as the Organisation tools, under the person’s own teams:read or teams:write. A model that proposes a team change starts the built-in team-create, team-update or team-delete task instead, with its CEO gate. A task belongs to a role, not a team: a team’s tasks are the tasks of the roles its members hold, so a team gets a task’s work by seating a holder of its role. A team’s charter is not an argument yet (#1433).
The Work items tools (os.add_work_item, os.list_work_items, os.read_work_item, os.update_work_item, os.close_work_item) keep a team’s work list: a run, a person, the CEO chat and an outside agent add, list, read, change and close items under the same rules, under teams:read or teams:write. A run reaches only the teams its member sits on or leads: it adds to and lists the first of them, claims from each in turn, a teamId it passes is ignored, another team’s item is work_item_not_found, and a run whose member sits on no team gets no_team. Who added or changed an item is always the caller. Every change is kept as the item’s history, and a closed item stays readable and can no longer change.
The catalog publish tools (os.publish_role, os.publish_team) publish one of the enterprise’s roles or teams to the catalog, where any company can clone it, for a person’s own agent over the API and the OS MCP server, under the person’s own catalog:write: the same as Share on a team’s page. A role travels as its name and slug. A team travels as one entry with its roles, a teammate slot per member carrying the roles they hold and nothing of the member, its KPIs and its schedule cadences, and publishing it again brings that entry up to date. A plan without catalog publishing is refused with its reason (catalog_publish_not_in_plan), as is a role slug another publisher holds (catalog_role_slug_taken) and a team with no roles (team_has_no_roles), and nothing is written. A run never calls them by these names, so a task that declares one is refused when it is saved (tool_not_run_callable); a task may reach them only through a bound connection to the OS’s own MCP server, with a gate on every write that server serves.
| Tool | What it does | Effect |
|---|---|---|
os.set_execution_name |
Replace the execution's default title with a human-readable name. | write |
os.add_execution_link |
Attach an http(s) link to the execution: an issue, a pull request, a preview. | write |
os.wait_execution |
Hold unfinished work with an owned follow-up and an explicit evidence condition. | write |
os.stop_execution |
End the whole execution this run belongs to, because its work is already done or abandoned. | write |
os.read_execution |
Read the execution this run belongs to as a whole: every run in order, and what repeats. | read |
os.set_gate_summary |
Write what the person approving this run's next gate is deciding on. | write |
os.decide_gate |
Decide one waiting gate as its Needs you card does: approve, reject, or send the work back. | write |
os.ask_ceo |
Ask the CEO questions, each with a recommended answer, and end the run on their decision. | write |
os.list_recommendations |
List self-improvement recommendations: pending, decided, task-record, or outcomes to check. | read |
os.record_issue_outcome |
Record how an issue or pull request a recommendation cites ended. | write |
os.get_recommendation |
One recommendation with its evidence. | read |
os.decide_recommendation |
Decide one pending recommendation: decline, actioned, or implement. | write |
os.mail_list |
List the assigned member's inbox, newest first: metadata and a snippet, no bodies. | read |
os.mail_read |
Read one message from the assigned member's inbox. | read |
os.mail_reply |
Reply to a stored mail using its mailbox reply identity, once the CEO approves. | write |
os.mail_send |
Send a new mail from the assigned member’s mailbox, once the CEO approves. | write |
os.mail_contacts |
List or search the assigned member's contacts: the people its mailbox has written to, and those added. | read |
os.mail_contact_save |
Add a contact to the assigned member's mailbox, or name one already there. | write |
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. | read |
os.mail_set_label |
Set the labels on a mail in the assigned member’s inbox. | write |
os.mail_set_handled |
Record whether a mail in the assigned member’s inbox has been handled. | write |
os.mail_set_many |
Set the labels, the handled state, or both on many mails in the assigned member’s inbox at once. | write |
os.mail_quiet_threads |
The threads the assigned member replied to that have gone quiet, oldest first, at most ten. | read |
os.mail_mark_chased |
Record that a quiet thread was answered today, so no second run today raises it again. | write |
os.mail_snooze |
Leave a quiet thread alone until a date, instead of drafting a follow-up. | write |
os.my_mail_list |
List the mail in your own mailbox, newest first: metadata and a snippet, no bodies. | read |
os.my_mail_read |
Read one message from your own mailbox. | read |
os.my_mail_attachment |
Fetch one attachment of a message in your own mailbox, base64-encoded. | read |
os.my_mail_set_label |
Set the labels on a message in your own mailbox. | write |
os.my_mail_set_handled |
Record where a message in your own mailbox stands: unhandled, replied, skipped, or snoozed until a date. | write |
os.my_mail_set_many |
Set the labels, the handled state, or both on many messages in your own mailbox at once. | write |
os.my_mail_reply |
Reply to a message in your own mailbox, from your own address, with no approval step. | write |
os.my_mail_send |
Send a new mail from your own address, with no approval step. | write |
os.my_mail_forward |
Forward a message from your own mailbox to somebody else, from your own address, with no approval step. | write |
os.my_mail_delete |
Delete a message from your own mailbox for good. | write |
os.my_mail_actions |
List the one-click buttons your inbox offers: the tasks that declare a mailbox action. | read |
os.my_mail_start_action |
Press one of your inbox’s buttons: start that task over your own mailbox. | write |
os.my_mail_schedule_action |
Press one of your inbox’s buttons on a cadence: each firing runs it over your own mailbox. | write |
os.my_mail_unschedule_action |
Stop pressing one of your inbox’s buttons on a cadence. | write |
os.my_mail_contacts |
List or search your own contacts: the people you have written to, and those you added. | read |
os.my_mail_contact_save |
Add a contact to your own mailbox, or name one already there. | write |
os.my_mail_contact_delete |
Remove a contact from your own mailbox. | write |
os.my_mail_signature |
Read the signature the OS adds to every mail you send, reply and forward. | read |
os.my_mail_signature_set |
Set or clear the signature the OS adds to every mail you send. | write |
os.my_mail_addresses |
List your own extra addresses, each with the signature mail from it carries. | read |
os.my_mail_address_signature_set |
Set or clear the signature mail from one of your extra addresses carries. | write |
os.escalate_mail |
The gate a mail that needs the CEO opens: the mail, why it matters, and what is suggested. | write |
os.mail_reply_draft |
The gate a drafted reply opens, so no reply leaves without a decision on it. | write |
os.list_kpis |
List the signed-off KPIs the run's teams own and those its task is the source of, with their lights. | read |
os.record_kpi_reading |
Record a reading for a KPI whose source is this run's task. | write |
os.get_enterprise_kpis |
The company's KPI targets, bands, cadence and source. | read |
os.set_enterprise_kpis |
Replace the company's KPI target list. | write |
os.get_team_kpis |
A team's KPI targets, including its key KPI. | read |
os.set_team_kpis |
Replace a team's KPI target list and key KPI. | write |
os.set_context |
Store a JSON value for the enterprise under a key, so a later run can read it. | write |
os.get_context |
Read one enterprise context value, or null when the key has never been set. | read |
os.delete_context |
Remove one enterprise context key. A missing key is a success. | write |
kpi.record_reading |
Record one reading of a KPI by hand: the value, when it was taken, and who or what took it. | write |
kpi.list_readings |
One KPI's readings, newest first, corrected ones included. | read |
role.list_kpis |
A role's KPIs, oldest first, with the team KPI each serves, its sign-off, light, trend and readings. | read |
role.define_kpi |
Propose a KPI on a role, waiting for a person to sign it off. | write |
role.edit_kpi |
Change a role KPI's fields; a signed-off one only a person changes. | write |
os.inspect_enterprise |
A snapshot of the company: teams, members, roles, and the tasks of the roles each member holds. | read |
os.directory |
Teams, members, roles, and the tasks of the roles each member holds: who to offload work to. | read |
os.list_blockers |
What has stopped: failed, stalled, blocked and spend-paused runs, and stopped pipelines, with who owns each. | read |
os.list_open_gates |
Every gate waiting on a decision, oldest first: the CEO inbox's own rows. | read |
os.list_waiting |
Open work nothing is working on: no live or queued run, no waiting decision, not on Blockers, not finished. | read |
os.retry_run |
Start a stopped run again, with the same input, so its work moves. | write |
os.route_run |
Send a stopped run's work to another task of its pipeline, instead of running the same task again. | write |
os.clear_run |
Take a stopped run off Blockers without running it again. | write |
os.escalate_run |
Hand a stopped run to its team lead, or to the CEO, and record that you did. | write |
os.read_enterprise |
The whole enterprise: teams, charters, roles, members and every task in full. | read |
os.search_catalog |
Published catalog tasks that match a plain-English intent, best first. | read |
os.list_tool_bindings |
The tool types this enterprise has bound, at which layer, and the tools each exposes. | read |
os.list_built_in_tools |
Every built-in tool a run can call, with its summary and whether it reads or writes. | read |
os.read_task |
One task in full, its pending recommendations, and the tasks that start it. | read |
os.assess_impact |
What points at a role, team, task or member a plan would delete. | read |
os.write_plan |
Write or replace this conversation's plan, checked before the CEO sees it. | write |
os.read_plan |
This conversation's plan as it stands, with its version. | read |
os.chat_list |
List chat threads, most recently active first: who each is with, its state and its last message. | read |
os.chat_read |
Read one chat thread: its messages, oldest first. | read |
os.chat_write |
Write one message in a chat thread, as yourself. | write |
os.chat_open |
Open a new chat thread with a member. | write |
os.list_roles |
The enterprise's roles, by slug. | read |
os.read_role |
One role, with the members who hold it and the tasks that run as it. | read |
os.create_role |
Create a role. | write |
os.update_role |
Change a role's name or slug. | write |
os.delete_role |
Remove a role nobody holds and no task runs as. | write |
os.add_role_task |
Give a role a task: the task runs as that role. | write |
os.remove_role_task |
Take a task away from a role. | write |
os.add_role_member |
Give a role a member: the member holds it. | write |
os.remove_role_member |
Take a member away from a role. | write |
os.list_task_definitions |
The enterprise's tasks, built-in ones included, a page at a time, each marked builtIn. | read |
os.read_task_definition |
One task in full: its skill text, declared fields, version number and current version id. | read |
os.create_task |
Create one of the enterprise’s own tasks. | write |
os.publish_task_version |
Publish a new version of one of the enterprise’s tasks, naming the version it was read from. | write |
os.set_task_run_status |
Enable or disable a task. | write |
os.set_task_schedule |
Set a task schedule. | write |
os.remove_task_schedule |
Remove a task schedule. | write |
os.set_task_input_values |
Set this enterprise's own values for a task's inputs. | write |
os.read_context |
Read enterprise workflow context outside a run. | read |
os.write_context |
Set enterprise workflow context outside a run. | write |
os.list_teams |
The enterprise's teams, by name. | read |
os.read_team |
One team, with its members and the tasks its members’ roles run. | read |
os.create_team |
Create a team, optionally with its own concurrent run limit. | write |
os.update_team |
Change a team's name or concurrent run limit. | write |
os.delete_team |
Remove a team. | write |
os.add_team_member |
Put a member on a team, optionally in a role. | write |
os.remove_team_member |
Take a member off a team. | write |
os.add_work_item |
Add an item to a team's work list. | write |
os.list_work_items |
A team's work list, open items by default. | read |
os.read_work_item |
One work item, with every field. | read |
os.update_work_item |
Change an open work item's fields. | write |
os.close_work_item |
Close a work item as done or dropped. | write |
os.claim_work_item |
Take the next ready item of this run's team lists, so no other run can take it. | write |
os.read_work_item_draft |
An item's draft as it is now: its latest version, text included. | read |
os.write_work_item_draft |
Write a new version of an item's draft. | write |
os.publish_role |
Publish one of the enterprise’s roles to the catalog, by its portable name and slug. | write |
os.publish_team |
Publish one of the enterprise’s teams to the catalog, with its roles, as the portal’s Share does. | write |
os.attach_repair |
Report the repair issue you filed for the shared cause this run was started for. | write |
os.set_execution_name
Replace the execution's default title with a human-readable name.
What the model reads:
Set a human-readable name for this execution, shown on Executions and run detail instead of the first task name. Later calls replace it. Pass name, e.g. "GitHub Issue #105 - Work keeps moving while decisions wait on the CEO".
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Shown on Executions instead of the first task name |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The last successful call in the execution wins, so a repeat leaves the same name.
- Called by: a run, the API.
- Returns: The name as stored: whitespace collapsed and trimmed.
- API:
POST /v1/runs/self/execution-name(run:self)
| Error | When | What happens |
|---|---|---|
name_required |
name is missing, or blank once whitespace is trimmed. |
Tool error |
name_too_long:200 |
name is over 200 characters. |
Tool error |
Example:
{
"name": "Issue #12 - Export the monthly report as CSV"
}
os.add_execution_link
Attach an http(s) link to the execution: an issue, a pull request, a preview.
What the model reads:
Attach a helpful http(s) link to this execution (issue, PR, preview, CRM profile). Shown on Executions and run detail. The same URL later updates the label. Pass name and url.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Label, e.g. GitHub issue, Pull request, Preview |
url |
string | yes | http(s) URL |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same URL updates its label rather than adding a second link.
- Called by: a run, the API.
- API:
POST /v1/runs/self/execution-links(run:self)
| Error | When | What happens |
|---|---|---|
name_required |
name is missing, or blank once whitespace is trimmed. |
Tool error |
name_too_long:200 |
name is over 200 characters. |
Tool error |
url_required |
url is missing or blank. |
Tool error |
url_too_long:2000 |
url is over 2000 characters. |
Tool error |
url_invalid |
url is not an http: or https: URL. |
Tool error |
Example:
{
"name": "Pull request",
"url": "https://git.example.com/acme/app/pull/34"
}
os.wait_execution
Hold unfinished work with an owned follow-up and an explicit evidence condition.
What the model reads:
Use for temporary dependency, CI or operator waits. Park this run on Blockers, retaining its member as owner, claimed work and lineage. Pass reason, resumeCondition (the fresh evidence required before continuing) and reviewAfterMinutes (1-1440). The durable follow-up is visible in run history; the owner must reassess it by reviewAt through normal retry/route. No automatic external action or approval is granted. Missing operational evidence stays unresolved. Do not cancel unfinished work. Existing human gates, rejection, retry caps and completed work remain authoritative.
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string | yes | Nonempty, at most 160 characters |
resumeCondition |
string | yes | Nonempty, at most 2000 characters |
reviewAfterMinutes |
integer | yes | Integer from 1 to 1440 |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: a run, the API.
- Returns: The stored reason, resumeCondition, ownerMemberId, runId and reviewAt.
- API:
POST /v1/runs/self/wait-execution(run:self)
| Error | When | What happens |
|---|---|---|
run_not_active |
The caller is not running or already waiting on this follow-up. | Tool error |
wait_owner_required |
No member owns the calling run. | Tool error |
gate_authoritative |
A human gate is waiting, rejected or requests changes. | Tool error |
Example:
{
"reason": "dependency_pending",
"resumeCondition": "Dependency complete and operational evidence recorded",
"reviewAfterMinutes": 15
}
os.stop_execution
End the whole execution this run belongs to, because its work is already done or abandoned.
What the model reads:
End the whole execution this run belongs to: every open run in it, this one included, ends cancelled, their gates close and nothing new starts. Call it when the work is already done or abandoned elsewhere. Temporary dependency, CI and operator waits use os.wait_execution with an evidence condition and an owner instead. Pass reason, a short text shown on the execution (e.g. pr_merged), and needsHuman: false ends the pipeline clean with no alert, true leaves it blocked for a human.
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string | yes | Why the execution stops, shown on Executions, e.g. pr_merged |
needsHuman |
boolean | yes | true leaves the work blocked for a human; false ends it clean |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat call on an execution already stopped changes nothing and succeeds.
- Called by: a run, the API.
- Returns: The reason as stored (trimmed) and needsHuman.
- API:
POST /v1/runs/self/stop-execution(run:self)
| Error | When | What happens |
|---|---|---|
reason_required |
reason is missing, or blank once trimmed. |
Tool error |
reason_invalid |
reason is not text. |
Tool error |
reason_too_long:160 |
reason is over 160 characters. |
Tool error |
needs_human_required |
needsHuman is missing. |
Tool error |
needs_human_invalid |
needsHuman is not true or false. |
Tool error |
run_not_active |
The calling run is not running. | Tool error |
Example:
{
"reason": "pr_merged",
"needsHuman": false
}
os.read_execution
Read the execution this run belongs to as a whole: every run in order, and what repeats.
What the model reads:
Read the execution this run belongs to, as the OS recorded it: timeline (every run oldest first, with its task, version, status, outcome, the run it came from, cost, duration and failed tool calls), findings (laps per task, cycles, repeated outcomes, loop caps tripped, dead ends, whether its size or cost is an outlier against earlier executions that began with the same task, and how it ended) and evidence (the runs that matter, each with its latest events and failed tool calls). Facts only, never a model's reading of them. A long execution is shortened oldest first, and trimmed says how much; findings are always whole. Takes no arguments: it reads only this run's own execution.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Returns:
{ lineageId, entryTaskId, timeline, evidence, findings, trimmed }.findingsis read from the whole execution before anything is trimmed. - API:
POST /v1/runs/self/tools/os.read_execution(run:self)
| Error | When | What happens |
|---|---|---|
execution_not_found |
The OS holds no run of this execution, which only a run of another enterprise could see. | Tool error |
Example:
{}
os.set_gate_summary
Write what the person approving this run's next gate is deciding on.
What the model reads:
Write, for whoever approves this run’s next gate, what they are deciding on. Markdown bullets: what the action does, and anything to watch out for. Shown on the approval card in Gates and the run page. Required before os.mail_reply, and before any call whose gate the task marks requiresSummary (a merge, say) — the call is handed back until you write one. A later call replaces it, title, why and previewUrl included, but never rewrites a gate already waiting. Pass summary, and the card’s title, why and previewUrl when you have them.
| Field | Type | Required | Description |
|---|---|---|---|
summary |
string | yes | Markdown. Short headed sections of "- " bullets, e.g. "## What changed" then "## Watch out for". No preamble. |
title |
string | no | Optional. The card’s title: what approving does, in plain words, e.g. "Merge “Fix page titles” to production". One line, at most 120 characters. Without it the card is titled with the task. |
why |
string | no | Optional. One line under the title: why this waits for a person, e.g. "Leaves the building: changes the live app". At most 160 characters. |
previewUrl |
string | no | Optional. An https address the person can open to see the result before deciding: a pull request, a preview deploy, a draft. Shown as Preview on the card. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A later call replaces the summary, so a repeat leaves the same one.
- Called by: a run, the API.
- Needs:
- Called before
os.mail_reply, which is handed back until it is.
- Called before
- Returns: The summary, and any title, why and previewUrl, as stored. The gate copies them when it opens, so a later call never rewrites a gate already waiting or decided.
- API:
POST /v1/runs/self/gate-summary(run:self)
| Error | When | What happens |
|---|---|---|
summary_required |
summary is missing or blank. |
Tool error |
summary_too_short:40 |
summary is under 40 characters. |
Tool error |
summary_too_long:6000 |
summary is over 6000 characters. |
Tool error |
title_too_long:120 |
title is over 120 characters. |
Tool error |
title_one_line |
title runs over more than one line. |
Tool error |
why_too_long:160 |
why is over 160 characters. |
Tool error |
why_one_line |
why runs over more than one line. |
Tool error |
preview_url_not_https |
previewUrl is not an https address, or is over 2048 characters. |
Tool error |
summary_needs_bullets |
summary has no markdown bullet (- , * or 1. ). |
Tool error |
gate_summary_required |
A reply, or a call whose gate row is marked requiresSummary, arrives before this run has written a summary. | Handed back |
incomplete_read:<tool> |
A paged read in this run ended incomplete (tool_result_truncated with complete: false: still too big at a page of 1, or its server ignores the page size), and that same target has not since been read through as pages 1 onward at one page size, ending in a short or empty page. Nothing is recorded; the refusal lists each such read with its tool, arguments and size. |
Handed back |
Example:
{
"summary": "## What changed\n- Adds CSV export to the monthly report\n\n## Watch out for\n- A migration runs on release",
"title": "Merge “CSV export for the monthly report” to production",
"why": "Leaves the building: changes the live app",
"previewUrl": "https://example.com/pull/42"
}
os.decide_gate
Decide one waiting gate as its Needs you card does: approve, reject, or send the work back.
What the model reads:
Decide one gate waiting on a person, as its card in Needs you does. Pass gateId as os.list_open_gates lists it, and decision: approve, reject or request_changes. A question gate (toolName os.ask_ceo) is approved by answering it: answers holds one row per question, { number, answer }, or { number, requiresMoreDetail: true } to ask the run for more; a reject declines the whole ask and needs no answers. request_changes sends the work back with note as the feedback, only on a gate whose requestChanges is true. A gate that offers choices is decided through one: pass choice as its key, decision as the decision that choice records, and what the choice asks for in note (a time as ISO 8601). edit, with approve only, is the whole payload as it should run, changed only in the fields the gate’s editableFields names. The decision is recorded as you, and the run resumes, routes or ends exactly as it does from the portal. A gate already decided is refused.
| Field | Type | Required | Description |
|---|---|---|---|
gateId |
string | yes | The gate, by the id os.list_open_gates lists it under. |
decision |
string, one of approve, reject, request_changes |
yes | approve runs the gated call, or answers the questions; reject declines it; request_changes sends the work back with note as the feedback. |
note |
string | no | Optional. The reason for a rejection, the feedback for request_changes (required then), or what a choice asks for: a time as ISO 8601 for a datetime input. |
answers |
array of object | no | Approving a question gate: one object per question, { number, answer }, or { number, requiresMoreDetail: true } to ask for more. Every question the gate asks needs one. |
choice |
string | no | Optional. The key of the choice this decision is made through, from the gate’s choices; decision must be the decision that choice records. |
edit |
object | no | Optional, with approve only. The gate’s whole payload as it should run, changed only in the fields its editableFields names. |
No other fields are accepted.
- Effect: write.
- Side effects: The run the gate holds moves: an approve runs the gated call or resumes the run with the answers, request_changes resumes it with the feedback, a rejected question resumes it with the refusal, and a rejected action ends its run as decision_rejected. A rejected mail gate closes the mail it held.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A decided gate is no longer waiting, so a repeat is refused with gate_not_waiting and decides nothing more.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The decided gate:
status(approved,rejectedorchanges_requested),decidedAt,decisionNote,decisionChoice,answers(each question with its answer, on an answered question gate) andeditedPayloadwhen an edit was sent, with therunId,toolNameandpayloadit holds. - API:
POST /v1/gates/:gateId/decision(gates:write)
| Error | When | What happens |
|---|---|---|
decision_required |
decision is missing, or not approve, reject or request_changes (400). |
Tool error |
answers_must_be_array |
answers is given and is not a list (400). |
Tool error |
gate_not_found |
No gate by that id in your enterprise (404). | Tool error |
gate_not_waiting |
The gate was already decided, or cancelled with its run (409). | Tool error |
answer_required:<number> |
Approving a question gate with that question unanswered: no answer text and no requiresMoreDetail (400). |
Tool error |
answer_unknown_question |
An answers row names a question number the gate did not ask (400). |
Tool error |
note_required |
request_changes without a note, or a choice whose input is required without one (400). |
Tool error |
request_changes_not_routed |
The gate cannot be sent back: its task routes no feedback, so requestChanges is false (409). |
Tool error |
choice_unknown |
choice is not one the gate’s tool offers (400). |
Tool error |
choice_decision_mismatch |
decision is not the decision that choice records (400). |
Tool error |
note_not_a_time |
A choice with a datetime input, and note is not a time (400). |
Tool error |
edit_only_with_approve |
edit sent with reject or request_changes (400). |
Tool error |
field_not_editable:<field> |
edit changes a field the gate’s editableFields does not name (400). |
Tool error |
Example, Answering a question gate: every question the gate asks gets a row.:
{
"gateId": "4b3e9c1a-0000-4000-8000-000000000001",
"decision": "approve",
"answers": [
{
"number": 1,
"answer": "Yes, schedule it now."
}
]
}
Example:
{
"gateId": "4b3e9c1a-0000-4000-8000-000000000002",
"decision": "reject",
"note": "Not this quarter."
}
Example:
{
"gateId": "4b3e9c1a-0000-4000-8000-000000000003",
"decision": "request_changes",
"note": "Set the epic priority to High before filing."
}
Example, A gate with choices, decided through one: the choice’s input goes in note.:
{
"gateId": "4b3e9c1a-0000-4000-8000-000000000004",
"decision": "approve",
"choice": "snooze",
"note": "2026-11-03T09:00:00Z"
}
os.ask_ceo
Ask the CEO questions, each with a recommended answer, and end the run on their decision.
What the model reads:
Ask the CEO questions and stop. This run waits for their decision, then ends. Pass questions: one decision each, numbered from 1, each answerable on its own, each with context (why it blocks, the options you see) and ctoRecommendation (the answer you recommend and why; required). Give the card a title (what the CEO is deciding, e.g. "Scope the CSV export") and a why (one line on why only they can answer) when you have them. The CEO answers each one: accepts your recommendation, answers it themselves, or asks you to explain further. Submit → outcome ceo_approved, Reject → ceo_rejected; the next task gets their answers as ceoAnswers and any note as ceoNote. Call it last.
| Field | Type | Required | Description |
|---|---|---|---|
questions |
array of object, at least 1 | yes | |
questions[].number |
integer, at least 1 | yes | |
questions[].question |
string | yes | One decision, answerable on its own |
questions[].context |
string | no | Why it blocks, and the options you see |
questions[].ctoRecommendation |
string | yes | The answer you recommend, and a one-line reason. Never empty. |
context |
string | no | One line on what is blocked, and the issue URL |
title |
string | no | Optional. The card’s title: what the CEO is deciding, in plain words, e.g. "Scope the CSV export". One line; cut at 120 characters. Without it the card is titled with the task. |
why |
string | no | Optional. One line under the title: why this waits for the CEO, e.g. "Changes what customers are promised". Cut at 160 characters. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The gate is found again by run and tool call, so a repeat never asks twice.
- Called by: a run, the API.
- Needs:
- A gate: the CEO decides every call, whatever the task declares.
- Returns: The CEO's decision, as the run's outcome:
ceo_approvedwithceoAnswers(one per question) andceoNote, orceo_rejectedwithceoNote. The next task receives them. - API:
POST /v1/runs/self/ask-ceo(run:self)
| Error | When | What happens |
|---|---|---|
ceo_questions_invalid |
No questions, or a question with a repeated or invalid number, no text or no ctoRecommendation. Recorded as ceo_questions_invalid:<why>, before any gate opens. |
Handed back |
Example:
{
"questions": [
{
"number": 1,
"question": "Should the export include archived reports?",
"context": "Customers asked for both; including them doubles the file size.",
"ctoRecommendation": "No: archived reports are rarely opened, and a filter can add them later."
}
],
"context": "Scoping https://git.example.com/acme/app/issues/12",
"title": "Scope the CSV export",
"why": "Changes what customers are promised"
}
os.list_recommendations
List self-improvement recommendations: pending, decided, task-record, or outcomes to check.
What the model reads:
List self-improvement recommendations. view: pending (default, oldest first, to decide), decided (the last 60 days across every task, to spot recurrence), task-record (actioned for implementation in the last 14 days, to follow up their issues), or outcomes (the issues and pull requests decided recommendations cite whose outcome is not known yet: read each with your own tools and record it with os.record_issue_outcome). Optional limit.
| Field | Type | Required | Description |
|---|---|---|---|
view |
string, one of pending, decided, task-record, outcomes |
no | |
limit |
integer, at least 1 | no |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.list_recommendations(run:self)
| Error | When | What happens |
|---|---|---|
view_invalid |
view is not one of the four. |
Tool error |
Example:
{
"view": "pending",
"limit": 10
}
Example:
{
"view": "outcomes"
}
os.record_issue_outcome
Record how an issue or pull request a recommendation cites ended.
What the model reads:
Record what became of an issue or pull request that decided recommendations cite, as you read it with your own tools: open, completed, not_planned, duplicate, merged (a pull request merged) or closed (closed with nothing more known, or a pull request closed unmerged). Every recommendation citing issueUrl keeps it as issueOutcome, which self-improvement reads so a change turned down is not proposed again. Pass issueUrl and outcome.
| Field | Type | Required | Description |
|---|---|---|---|
issueUrl |
string | yes | The issue or pull request URL, as the recommendation cites it |
outcome |
string, one of open, completed, not_planned, duplicate, merged, closed |
yes |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Recording the same outcome twice leaves the same state.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.record_issue_outcome(run:self)
| Error | When | What happens |
|---|---|---|
issue_url_invalid |
issueUrl is not an issue or pull request URL. |
Tool error |
outcome_invalid |
outcome is not one of the six. |
Tool error |
issue_not_cited |
No recommendation cites issueUrl. Record outcomes for the URLs view outcomes lists. |
Tool error |
Example:
{
"issueUrl": "https://git.example.com/acme/app/issues/12",
"outcome": "completed"
}
os.get_recommendation
One recommendation with its evidence.
What the model reads:
One recommendation with its evidence: the source run (status, recent events, failed tool calls), task versions newer than the one the source run ran, and every other recommendation for the same task. When the recommendation came from an execution (`recommendation.sourceLineageId`, with its `patternKey` and `recurrenceCount`), `execution` carries that execution as the self-improvement pass judged it: its `lineageId`, its `findings` untrimmed (laps by task, cycles, repeated outcomes, caps tripped, dead ends, outlier, how it ended, pattern key), a `timeline` of its newest 30 runs oldest first, and `trimmed.timelineRows`, the older runs left out. `execution` is null for a recommendation from one run, or when the execution has no runs left. Pass id.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.get_recommendation(run:self)
| Error | When | What happens |
|---|---|---|
id_required |
id is missing. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000001"
}
os.decide_recommendation
Decide one pending recommendation: decline, actioned, or implement.
What the model reads:
Decide one pending recommendation. decision: decline (reason required), actioned (issueUrl of the issue or pull request that takes the work, and lane: os, repo-commands or local-stack), or implement (the task-record lane: issueUrl of the issue that tracks it; starts the implementer). Cite an open issue or a merged pull request in the repository the work belongs to: the OS checks only that issueUrl is an issue or pull request URL. Pass id, decision, reason, issueUrl, lane.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
decision |
string, one of decline, actioned, implement |
yes | |
reason |
string | yes | |
issueUrl |
string | no | An issue or pull request URL, e.g. https://<host>/<owner>/<repo>/issues/<n> |
lane |
string, one of os, repo-commands, local-stack, task-record |
no |
No other fields are accepted.
- Effect: write.
- Side effects:
implementstarts the implementing task. - Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the tool call: the same call sent twice decides once and returns the first answer. A different call on a decided recommendation is refused.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.decide_recommendation(run:self)
| Error | When | What happens |
|---|---|---|
id_required |
id is missing. |
Tool error |
recommendation_not_pending:<status> |
Someone else already decided it. Only a pending recommendation can be decided. |
Tool error |
decision_invalid |
decision is not one of the three. |
Tool error |
lane_invalid |
actioned without a valid lane. |
Tool error |
task_record_uses_implement |
actioned with lane task-record: decide implement instead. |
Tool error |
issue_url_invalid |
actioned or implement without an issue or pull request URL. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000001",
"decision": "decline",
"reason": "Not reproduced on the source run"
}
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000002",
"decision": "actioned",
"reason": "Covered by the retry change",
"issueUrl": "https://git.example.com/acme/app/issues/12",
"lane": "os"
}
os.mail_list
List the assigned member's inbox, newest first: metadata and a snippet, no bodies.
What the model reads:
List mail in the inbox of the member doing this run, newest first. Metadata and a snippet only, no bodies: read one with os.mail_read. Optional unreadOnly (only messages not yet opened), label (only mail carrying that label), handledState (only mail in that state), threadId (every mail in one conversation), search (only mail whose sender address or name, subject or text contains the words, any case), order (desc, the default, or asc), page and limit (default 25, max 200). Filters combine: label VIP with handledState unhandled lists only unhandled VIP mail. A full row is large: about 30 fit in one result. To work through a long backlog pass compact true, which returns only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag, so about 100 rows fit.
| Field | Type | Required | Description |
|---|---|---|---|
unreadOnly |
boolean | no | Only messages nobody has opened yet |
label |
string | no | Only mail carrying this label, e.g. VIP |
handledState |
string, one of unhandled, replied, skipped, snoozed, escalated |
no | Only mail in this handled state |
threadId |
string | no | Only mail in this conversation, from a row’s threadId |
search |
string | no | Only mail whose sender address or name, subject or text contains this, any case |
order |
string, one of desc, asc |
no | By receivedAt. Default desc |
page |
integer, at least 1 | no | |
limit |
integer, 1 to 200 | no | |
compact |
boolean | no | Only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag on each row |
No other fields are accepted.
What chat reads, through os.use_tool:
List mail in the inbox of one of the enterprise’s members, newest first. Pass id, the member’s id (os.directory lists them). Reading a member’s mailbox needs the person’s members:read; their own mailbox is os.my_mail_list. Metadata and a snippet only, no bodies: read one with os.mail_read, passing the same id and the mail’s id as emailId. Optional unreadOnly (only messages not yet opened), label (only mail carrying that label), handledState (only mail in that state), threadId (every mail in one conversation), search (only mail whose sender address or name, subject or text contains the words, any case), order (desc, the default, or asc), page and limit (default 25, max 200). Filters combine: label VIP with handledState unhandled lists only unhandled VIP mail. Pass compact true to get only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag on each row, so many more rows fit.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The member whose mailbox, by id, as os.directory lists them |
unreadOnly |
boolean | no | Only messages nobody has opened yet |
label |
string | no | Only mail carrying this label, e.g. VIP |
handledState |
string, one of unhandled, replied, skipped, snoozed, escalated |
no | Only mail in this handled state |
threadId |
string | no | Only mail in this conversation, from a row’s threadId |
search |
string | no | Only mail whose sender address or name, subject or text contains this, any case |
order |
string, one of desc, asc |
no | By receivedAt. Default desc |
page |
integer, at least 1 | no | |
limit |
integer, 1 to 200 | no | |
compact |
boolean | no | Only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag on each row |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API, the CEO chat.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ data, total, page, limit, pages }. Each row hasid,fromAddress,fromName,subject,snippet,receivedAt,readAt,hasAttachments,threadKey(the same on every message in one conversation),direction(inboundwhen it arrived,outboundwhen the member sent it),to,cc,bcc(who a mail the mailbox sent went to unseen,[]on everything else),threadId,labels(free text,[]when none),handledState(unhandled,replied,skipped,snoozedorescalated) andsnoozedUntil(only whensnoozed),spamScoreandspamFlag(null if the receiving edge has not scored the message). Withcompact, each row has onlyid,fromAddress,subject,receivedAt,labels,handledState,spamScoreandspamFlag. - API:
GET /v1/members/:id/emails(members:read)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
handled_state_invalid |
handledState is not one of the handled states. | Tool error |
Example:
{
"unreadOnly": true,
"limit": 10
}
Example:
{
"handledState": "unhandled",
"order": "asc",
"compact": true,
"limit": 100
}
os.mail_read
Read one message from the assigned member's inbox.
What the model reads:
Read one message from the assigned member’s inbox: sender, subject, text and sanitised HTML bodies, and attachment names (not their contents). Reading marks it read for the member too. Pass id from os.mail_list.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.mail_list |
No other fields are accepted.
What chat reads, through os.use_tool:
Read one message from the inbox of one of the enterprise’s members: sender, subject, text and sanitised HTML bodies, and attachment names (not their contents). Pass id, the member’s id, and emailId, the message’s id from os.mail_list. Reading a member’s mailbox needs the person’s members:read; their own mailbox is os.my_mail_read. Reading marks it read for the member, the same as opening it in the portal.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The member whose mailbox, by id, as os.directory lists them |
emailId |
string | yes | A message id from os.mail_list |
No other fields are accepted.
- Effect: read.
- Side effects: Marks the message read for the member, the same as opening it in the portal.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API, the CEO chat.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns: The message: sender, subject,
textBody, sanitisedhtmlBody,receivedAt,readAt,attachments(names and sizes, not contents),to,cc,bcc(who a mail the mailbox sent went to unseen,[]on everything else),threadId,labels(free text,[]when none),handledState(unhandled,replied,skipped,snoozedorescalated) andsnoozedUntil(only whensnoozed),spamScoreandspamFlag(null if the receiving edge has not scored the message). - API:
GET /v1/members/:id/emails/:emailId(members:read)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
email_not_found |
The id is not in this member's mailbox, including another member's message. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003"
}
os.mail_reply
Reply to a stored mail using its mailbox reply identity, once the CEO approves.
What the model reads:
Reply to one message in the assigned member’s inbox. Pass id from os.mail_list and the reply. Write the body as `markdown`; the OS sends it formatted with a plain-text copy, and raw HTML in it is not passed through. Or pass text, with optional html for a body you formatted yourself, as before; give markdown or text, not both, and never markdown with html. The subject is taken from the message being answered. It goes to the sender of the message being answered. Pass replyAll true to answer everyone on the original too: everyone else on its To and Cc is copied in, but for this mailbox’s own addresses. Optional cc and bcc, each one address or a list, copy in more people, seen or unseen; 50 addresses at most in all. Replies use the arrival address unless its alias is configured to reply from the member’s primary address. Both addresses must still belong to this mailbox. The reply threads under the original in the recipient’s mail client. When the mailbox has a signature, the OS adds it after the body, in text and html, before the approval card opens; pass signature false to send without it. The OS then quotes the message being answered below the signature, under an `On <date>, <name> wrote:` line, as `>` lines in text and a blockquote in html, also before the approval card opens; pass quote false to send without it. Every send waits for the CEO to approve this exact payload, signature, quote and every recipient included (a reply-all names everyone it copies in, in cc, before the approval card opens), and approval sends that and nothing else. The sent reply is filed in the member’s mailbox in the original’s thread, and the original is marked read and moves to handled state replied.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.mail_list: the mail this answers |
markdown |
string | no | The body in Markdown: headings, emphasis, lists, links, quotes, code and tables. The OS sends it formatted, with a plain-text copy. Give this or text, not both |
text |
string | no | The reply, as plain text, when not given as markdown |
html |
string | no | Optional HTML body beside text. Plain text is sent either way |
replyAll |
boolean | no | true answers everyone on the original: its sender, and everyone else on its To and Cc but this mailbox |
cc |
string or array of string | no | More people to copy in, seen by every recipient: one address or a list |
bcc |
string or array of string | no | People sent the reply that no other recipient sees: one address or a list |
signature |
boolean | no | false sends without the mailbox’s signature. Left out, the OS adds it after the body |
quote |
boolean | no | false sends without the original quoted below. Left out, the OS quotes the message being answered after the body and signature |
No other fields are accepted.
- Effect: write.
- Side effects: Files the sent reply in the member’s mailbox, in the original’s thread, marks the original read and, once sent, moves it to handled state
replied(clearing any snooze) and saves every recipient to the member’s contacts. - Retry: Not retry-safe: a repeat acts again. A repeat sends a second reply. Call it again only if the first reported a refusal.
- Called by: a run, the API.
- Needs:
- A gate: the CEO decides every call, whatever the task declares.
- The gate offers Approve and Reject, and beside them these choices. Stop Chasing (
stop_chasing): Send nothing and mark this thread complete. Future chase passes skip it. - The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- Returns:
{ status, id }:sent, orsend_failedwith the provider’serrorwhen it did not go out.idis the copy filed in the mailbox either way. - API:
POST /v1/runs/self/tools/os.mail_reply(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
email_not_found |
The id is not in this member's mailbox, including another member's message. | Tool error |
mail_field_required |
Neither markdown nor text says anything. | Handed back |
mail_body_conflict |
markdown was given with text or with html. | Handed back |
recipient_invalid |
The stored message names no address that can be replied to, or an address in cc or bcc is not an email address. The error names the address. | Tool error |
too_many_recipients |
The reply would go to more than 50 addresses in all, everyone a reply-all copies in counted. | Tool error |
sender_not_own_mailbox |
The address the original arrived at does not deliver to this member's mailbox. | Tool error |
gate_summary_required |
The run has not written the recipient and gist the CEO should read on the approval card. | Handed back |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"markdown": "Thursday at **10:00** works."
}
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"replyAll": true,
"markdown": "Thursday at **10:00** works for all of us."
}
os.mail_send
Send a new mail from the assigned member’s mailbox, once the CEO approves.
What the model reads:
Send a new message from the assigned member’s mailbox: to, subject and the body. to, cc and bcc each take one address or a list of them. Everyone in to and cc sees who else the mail went to; nobody sees bcc. An address named twice gets one copy, and a mail goes to at most 50 addresses in all. Write the body as `markdown`; the OS sends it formatted with a plain-text copy, and raw HTML in it is not passed through. Or pass text, with optional html for a body you formatted yourself, as before; give markdown or text, not both, and never markdown with html. It goes out from the member’s own address unless from names another address that delivers to the same mailbox — any other sender is refused, whatever the payload says. When the mailbox has a signature, the OS adds it after the body, in text and html, before the approval card opens; pass signature false to send without it. Every send waits for the CEO to approve this exact payload, signature and every recipient included, and approval sends that and nothing else. The sent message is filed in the member’s mailbox. To answer a message already in the inbox, use os.mail_reply instead, so it threads.
| Field | Type | Required | Description |
|---|---|---|---|
to |
string or array of string | yes | Who the mail is to: one email address, or a list |
cc |
string or array of string | no | Who is copied in, seen by every recipient: one address or a list |
bcc |
string or array of string | no | Who is sent the mail unseen by any other recipient: one address or a list |
subject |
string | yes | |
markdown |
string | no | The body in Markdown: headings, emphasis, lists, links, quotes, code and tables. The OS sends it formatted, with a plain-text copy. Give this or text, not both |
text |
string | no | The message, as plain text, when not given as markdown |
html |
string | no | Optional HTML body beside text. Plain text is sent either way |
from |
string | no | Another address that delivers to this member’s mailbox. Defaults to their own |
signature |
boolean | no | false sends without the mailbox’s signature. Left out, the OS adds it after the body |
No other fields are accepted.
- Effect: write.
- Side effects: Files the sent message in the member’s mailbox, every recipient on it, and, once sent, saves every recipient to its contacts.
- Retry: Not retry-safe: a repeat acts again. A repeat sends a second message. Call it again only if the first reported a refusal.
- Called by: a run, the API.
- Needs:
- A gate: the CEO decides every call, whatever the task declares.
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- Returns:
{ status, id }:sent, orsend_failedwith the provider’serrorwhen it did not go out.idis the copy filed in the mailbox either way. - API:
POST /v1/runs/self/tools/os.mail_send(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
mail_field_required |
Neither markdown nor text says anything. | Handed back |
mail_body_conflict |
markdown was given with text or with html. | Handed back |
recipient_invalid |
An address in to, cc or bcc is not an email address, or to names nobody. The error names the address. | Handed back |
too_many_recipients |
to, cc and bcc name more than 50 addresses in all. | Handed back |
sender_not_own_mailbox |
from names an address that does not deliver to this member's mailbox. Leave from out to send from the member's own address. |
Tool error |
Example:
{
"to": "[email protected]",
"subject": "Thursday",
"markdown": "Thursday at **10:00** works for the CEO."
}
Example:
{
"to": [
"[email protected]",
"[email protected]"
],
"cc": "[email protected]",
"subject": "Thursday",
"markdown": "Thursday at **10:00** works for the CEO."
}
os.mail_contacts
List or search the assigned member's contacts: the people its mailbox has written to, and those added.
What the model reads:
List the contacts of the assigned member’s mailbox: everyone a send or reply from it went to, saved once it left, and everyone added by hand. Most recently written to first, then by name. Pass search to keep only contacts whose name or address contains it, any case: to mail Sarah from Acme, search Sarah or acme and use the address it returns in os.mail_send. Pass directory true to add the enterprise’s own people and members who have an address, after the contacts and each only once. limit is how many rows (default 50, max 200). Mail that arrived never makes a contact.
| Field | Type | Required | Description |
|---|---|---|---|
search |
string | no | Only contacts whose name or address contains this, any case |
directory |
boolean | no | Also offer the enterprise’s own people and members who have an address |
limit |
integer, 1 to 200 | no | Rows to return. Default 50 |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ data }: each contact withid(null on a directory row),address,name(empty when none is known),source(autowhen a send saved it,manualwhen it was added by hand,directoryfor one of the enterprise’s own people or members offered beside the contacts),nameByHand(a name set by hand, which no later send replaces),mailCountandlastMailedAt(null until the mailbox first writes to it). - API:
POST /v1/runs/self/tools/os.mail_contacts(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
contact_search_invalid |
search is not text, or is longer than 200 characters. | Tool error |
contact_limit_invalid |
limit is not a whole number from 1 to 200. | Tool error |
Example:
{
"search": "sarah"
}
Example:
{
"search": "acme",
"directory": true,
"limit": 10
}
os.mail_contact_save
Add a contact to the assigned member's mailbox, or name one already there.
What the model reads:
Save an address to the contacts of the assigned member’s mailbox. Pass address and, optionally, name. A new address is added as one saved by hand; an address already among the contacts keeps its history and takes the name when one is given. A name set here is kept: a later send never replaces it. Leave name out to keep the name a contact already has. It only records the contact, and sends nothing.
| Field | Type | Required | Description |
|---|---|---|---|
address |
string | yes | The contact’s email address |
name |
string | no | The name the contact goes by. Kept over any a later send carries |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns: The contact saved, with
id(null on a directory row),address,name(empty when none is known),source(autowhen a send saved it,manualwhen it was added by hand,directoryfor one of the enterprise’s own people or members offered beside the contacts),nameByHand(a name set by hand, which no later send replaces),mailCountandlastMailedAt(null until the mailbox first writes to it). - API:
POST /v1/runs/self/tools/os.mail_contact_save(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
contact_address_invalid |
address is not one email address. | Tool error |
contact_name_invalid |
name is not text, or is longer than 200 characters. | Tool error |
Example:
{
"address": "[email protected]",
"name": "Sarah Jones"
}
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.
What the model reads:
List the one-click buttons a member’s mailbox offers, as the member’s page shows them: each an active task of the enterprise whose current version declares a mailbox action (mailboxAction) and that runs as a role this member holds, since those are the runs that read the member’s mailbox. on says where the button sits: mailbox, over the whole mailbox, or mail, on one message. Start one with os.start_task by its taskId; for a button on one message pass the message’s id as the emailId input. The run reads the member’s mailbox as its tasks always have. Pass id, the member’s id. A member in another enterprise, or one holding no such role, offers nothing.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The member’s id |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ actions }: each{ taskId, catalogTaskId, slug, name, label, on },taskIdalways set here, by label. - API:
GET /v1/members/:id/mailbox-actions(members:read)
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031"
}
os.mail_set_label
Set the labels on a mail in the assigned member’s inbox.
What the model reads:
Set the labels triage gives one message in the assigned member’s inbox. Pass id from os.mail_list and labels, the whole set the mail should carry: it replaces whatever labels it had, and an empty list clears them. Labels are free text (e.g. VIP, Needs reply); there is no fixed list to choose from. List mail by label with os.mail_list.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.mail_list |
labels |
array of string | yes | Every label the mail should carry. Replaces the current set |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ id, labels }: the mail and the labels it now carries. - API:
POST /v1/runs/self/tools/os.mail_set_label(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
email_not_found |
The id is not in this member's mailbox, including another member's message. | Tool error |
labels_invalid |
labels is not a list of non-empty strings of at most 64 characters. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"labels": [
"VIP"
]
}
os.mail_set_handled
Record whether a mail in the assigned member’s inbox has been handled.
What the model reads:
Record where one message in the assigned member’s inbox stands. Pass id from os.mail_list and handledState: unhandled, replied, skipped, snoozed or escalated. A mail is in one state at a time. snoozed needs snoozedUntil, the date and time it comes back (ISO 8601); every other state takes no date and clears any snooze. os.mail_reply moves the mail it answers to replied on its own.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.mail_list |
handledState |
string, one of unhandled, replied, skipped, snoozed, escalated |
yes | |
snoozedUntil |
string | no | ISO 8601 date and time the mail comes back. Only with handledState snoozed |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ id, handledState, snoozedUntil }: the state the mail is now in. - API:
POST /v1/runs/self/tools/os.mail_set_handled(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
email_not_found |
The id is not in this member's mailbox, including another member's message. | Tool error |
handled_state_invalid |
handledState is not one of the handled states. | Tool error |
snoozed_until_required |
handledState is snoozed and snoozedUntil is missing or not a date. | Tool error |
snoozed_until_not_allowed |
snoozedUntil was given with a handledState other than snoozed. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"handledState": "snoozed",
"snoozedUntil": "2026-10-01T09:00:00Z"
}
os.mail_set_many
Set the labels, the handled state, or both on many mails in the assigned member’s inbox at once.
What the model reads:
Record the same triage decision on many messages in the assigned member’s inbox in one call. Name the mail one way: ids (up to 200 message ids from os.mail_list), or fromAddress (every unhandled mail that arrived from that exact sender address; mail already handled and mail the member sent are never touched). Then pass labels (the whole set each mail should carry, replacing what it had), handledState (unhandled, replied, skipped, snoozed or escalated; snoozed needs snoozedUntil), or both. Use it to close a run of look-alike mail without reading each one. An id that is not in this mailbox changes nothing and comes back in notFound.
| Field | Type | Required | Description |
|---|---|---|---|
ids |
array of string, at least 1 | no | Up to 200 message ids from os.mail_list. Not together with fromAddress |
fromAddress |
string | no | A sender address, matched exactly: every unhandled mail that arrived from it. Not together with ids |
labels |
array of string | no | Every label each mail should carry. Replaces the current set |
handledState |
string, one of unhandled, replied, skipped, snoozed, escalated |
no | |
snoozedUntil |
string | no | ISO 8601 date and time the mail comes back. Only with handledState snoozed |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ updated, notFound }: how many mails were changed, and the ids given that are not in this mailbox (always[]when selecting byfromAddress). - API:
POST /v1/runs/self/tools/os.mail_set_many(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
member_not_found |
The run's member no longer exists. | Tool error |
mail_selector_invalid |
Neither ids nor fromAddress was given, or both were. | Tool error |
mail_ids_invalid |
ids is not a list of 1 to 200 non-empty message ids. | Tool error |
mail_change_required |
Neither labels nor handledState was given, so there is nothing to record. | Tool error |
labels_invalid |
labels is not a list of non-empty strings of at most 64 characters. | Tool error |
handled_state_invalid |
handledState is not one of the handled states. | Tool error |
snoozed_until_required |
handledState is snoozed and snoozedUntil is missing or not a date. | Tool error |
snoozed_until_not_allowed |
snoozedUntil was given with a handledState other than snoozed. | Tool error |
Example:
{
"fromAddress": "[email protected]",
"labels": [
"Newsletter"
],
"handledState": "skipped"
}
Example:
{
"ids": [
"5f0c1d2e-0000-4000-8000-000000000003",
"5f0c1d2e-0000-4000-8000-000000000004"
],
"handledState": "skipped"
}
os.mail_quiet_threads
The threads the assigned member replied to that have gone quiet, oldest first, at most ten.
What the model reads:
List the conversations in the assigned member’s mailbox where the member had the last word and the correspondent has not answered for three clear weekdays, counted in the enterprise’s timezone. A thread already chased or snoozed today, one snoozed until a later date, and one whose original names no address a reply could go to are left out, so every row is one to act on today. At most the ten oldest.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ data }: each row hasthreadKey,replyToEmailId(the newest inbound message: pass it to os.mail_reply asid),correspondent,subjectandlastOutboundAt. An empty list when nothing is quiet or the member has no mailbox. - API:
POST /v1/runs/self/tools/os.mail_quiet_threads(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
Example:
{}
os.mail_mark_chased
Record that a quiet thread was answered today, so no second run today raises it again.
What the model reads:
Record that one thread from os.mail_quiet_threads has been dealt with today. Call it before os.mail_reply on that thread: the reply waits for the CEO, and a second run the same day must not propose a second follow-up while the first is still waiting. The thread is offered again on a later weekday if it is still quiet.
| Field | Type | Required | Description |
|---|---|---|---|
threadKey |
string | yes | A threadKey from os.mail_quiet_threads |
No other fields are accepted.
- Effect: write.
- Side effects: Stores when the thread was last chased on the member's chase record for it. Nothing is sent.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ threadKey, chasedAt }. - API:
POST /v1/runs/self/tools/os.mail_mark_chased(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
thread_not_found |
The threadKey names no conversation in this member's mailbox, including another member's. | Tool error |
Example:
{
"threadKey": "<[email protected]>"
}
os.mail_snooze
Leave a quiet thread alone until a date, instead of drafting a follow-up.
What the model reads:
Snooze one thread from os.mail_quiet_threads until a later date (YYYY-MM-DD or an ISO timestamp): it is not offered again until that date has passed or the member writes in the thread again, and it counts as dealt with today. Use it instead of a follow-up when chasing now would be premature. Nothing is sent.
| Field | Type | Required | Description |
|---|---|---|---|
threadKey |
string | yes | A threadKey from os.mail_quiet_threads |
until |
string | yes | When to raise it again: a date or timestamp after now |
No other fields are accepted.
- Effect: write.
- Side effects: Stores the snooze on the member's chase record for the thread. Nothing is sent.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Needs:
- The run's assigned member. The mailbox is always theirs: a
memberIdin the payload is ignored, and an OS-owned task has no mailbox.
- The run's assigned member. The mailbox is always theirs: a
- Returns:
{ threadKey, snoozedUntil }. - API:
POST /v1/runs/self/tools/os.mail_snooze(run:self)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
The run has no assigned member, so no mailbox. | Tool error |
thread_not_found |
The threadKey names no conversation in this member's mailbox, including another member's. | Tool error |
snooze_until_invalid |
until is not a date, or is not after now. |
Tool error |
Example:
{
"threadKey": "<[email protected]>",
"until": "2026-10-12"
}
os.my_mail_list
List the mail in your own mailbox, newest first: metadata and a snippet, no bodies.
What the model reads:
List the mail in your own mailbox, newest first: the mailbox of the person who signed in or connected this app, in the enterprise this call is in, and never a member’s or anyone else’s. Metadata and a snippet only, no bodies: read one with os.my_mail_read. Optional unreadOnly (only messages not yet opened), label (only mail carrying that label), handledState (only mail in that state), threadId (every mail in one conversation), search (only mail whose sender address or name, subject or text contains the words, any case), order (desc, the default, or asc), page and limit (default 25, max 200). Filters combine: label VIP with handledState unhandled lists only unhandled VIP mail; search invoice with label Acme finds the Acme mail about an invoice. A full row is large: about 30 fit in one result. To work through a long backlog pass compact true, which returns only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag, so about 100 rows fit.
| Field | Type | Required | Description |
|---|---|---|---|
unreadOnly |
boolean | no | Only messages nobody has opened yet |
label |
string | no | Only mail carrying this label, e.g. VIP |
handledState |
string, one of unhandled, replied, skipped, snoozed, escalated |
no | Only mail in this handled state |
threadId |
string | no | Only mail in this conversation, from a row’s threadId |
search |
string | no | Only mail whose sender address or name, subject or text contains this, any case |
order |
string, one of desc, asc |
no | By receivedAt. Default desc |
page |
integer, at least 1 | no | The page of results, from 1 |
limit |
integer, 1 to 200 | no | Rows per page. Default 25 |
compact |
boolean | no | Only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag on each row |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ data, total, page, limit, pages }. Each row hasid,fromAddress,fromName,subject,snippet,receivedAt,readAt,hasAttachments,threadKey(the same on every message in one conversation),direction(inboundwhen it arrived,outboundwhen you sent it),to,cc,bcc(who a mail the mailbox sent went to unseen,[]on everything else),threadId,labels(free text,[]when none),handledState(unhandled,replied,skipped,snoozedorescalated) andsnoozedUntil(only whensnoozed),spamScoreandspamFlag(null if the receiving edge has not scored the message). Withcompact, each row has onlyid,fromAddress,subject,receivedAt,labels,handledState,spamScoreandspamFlag. - API:
GET /v1/mail(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
handled_state_invalid |
handledState is not one of the handled states. | Tool error |
Example:
{
"unreadOnly": true,
"limit": 10
}
Example:
{
"handledState": "unhandled",
"order": "asc",
"compact": true,
"limit": 100
}
os.my_mail_read
Read one message from your own mailbox.
What the model reads:
Read one message from your own mailbox: sender, subject, text and sanitised HTML bodies, and attachment names and sizes (fetch one with os.my_mail_attachment). Reading marks it read for you too. Pass id from os.my_mail_list; an id from anyone else’s mailbox is not found.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list |
No other fields are accepted.
- Effect: read.
- Side effects: Marks the message read for you, the same as opening it.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The message: sender, subject,
textBody, sanitisedhtmlBody,receivedAt,readAt,attachments(each withid,filename,contentTypeandsizeBytes, not contents),to,cc,bcc(who a mail the mailbox sent went to unseen,[]on everything else),threadId,labels(free text,[]when none),handledState(unhandled,replied,skipped,snoozedorescalated) andsnoozedUntil(only whensnoozed),spamScoreandspamFlag(null if the receiving edge has not scored the message). - API:
GET /v1/mail/:id(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003"
}
os.my_mail_attachment
Fetch one attachment of a message in your own mailbox, base64-encoded.
What the model reads:
Fetch one attachment of a message in your own mailbox, as its file name, content type, size and base64-encoded bytes. Pass id, a message id from os.my_mail_list, and attachmentId from that message’s attachments in os.my_mail_read. A file over 4 MB is refused here: download it from the API instead (GET /v1/mail/{id}/attachments/{attachmentId} without format=json streams the bytes).
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list |
attachmentId |
string | yes | An attachment id from os.my_mail_read |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ filename, contentType, sizeBytes, base64 }: the file, encoded. - API:
GET /v1/mail/:id/attachments/:attachmentId?format=json(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
attachment_not_found |
The message has no attachment with that id. | Tool error |
attachment_too_large |
The file is over 4 MB, more than a tool result carries. Download it from the API instead. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"attachmentId": "5f0c1d2e-0000-4000-8000-000000000009"
}
os.my_mail_set_label
Set the labels on a message in your own mailbox.
What the model reads:
Set the labels on one message in your own mailbox. Pass id from os.my_mail_list and labels, the whole set the mail should carry: it replaces whatever labels it had, and an empty list clears them. Labels are free text (e.g. VIP, Needs reply); there is no fixed list to choose from. List mail by label with os.my_mail_list.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list |
labels |
array of string | yes | Every label the mail should carry. Replaces the current set |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ id, labels }: the mail and the labels it now carries. - API:
PATCH /v1/mail/:id/labels(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
labels_invalid |
labels is not a list of non-empty strings of at most 64 characters. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"labels": [
"VIP"
]
}
os.my_mail_set_handled
Record where a message in your own mailbox stands: unhandled, replied, skipped, or snoozed until a date.
What the model reads:
Record where one message in your own mailbox stands. Pass id from os.my_mail_list and handledState: unhandled, replied, skipped or snoozed. A mail is in one state at a time. snoozed needs snoozedUntil, the date and time it comes back (ISO 8601); every other state takes no date and clears any snooze. escalated is a member’s state, raised to the enterprise owner: your mail has nobody to raise to, so it is refused. os.my_mail_reply moves the mail it answers to replied on its own.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list |
handledState |
string, one of unhandled, replied, skipped, snoozed |
yes | Where the mail stands now |
snoozedUntil |
string | no | ISO 8601 date and time the mail comes back. Only with handledState snoozed |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ id, handledState, snoozedUntil }: the state the mail is now in. - API:
PATCH /v1/mail/:id/handled(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
handled_state_invalid |
handledState is not unhandled, replied, skipped or snoozed (escalated is a member’s state). | Tool error |
snoozed_until_required |
handledState is snoozed and snoozedUntil is missing or not a date. | Tool error |
snoozed_until_not_allowed |
snoozedUntil was given with a handledState other than snoozed. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"handledState": "snoozed",
"snoozedUntil": "2026-11-03T09:00:00Z"
}
os.my_mail_set_many
Set the labels, the handled state, or both on many messages in your own mailbox at once.
What the model reads:
Record the same decision on many messages in your own mailbox in one call. Name the mail one way: ids (up to 200 message ids from os.my_mail_list), or fromAddress (every unhandled mail that arrived from that exact sender address; mail already handled and mail you sent are never touched). Then pass labels (the whole set each mail should carry, replacing what it had), handledState (unhandled, replied, skipped or snoozed; snoozed needs snoozedUntil), or both. Use it to close a run of look-alike mail without reading each one. An id that is not in your mailbox changes nothing and comes back in notFound.
| Field | Type | Required | Description |
|---|---|---|---|
ids |
array of string | no | Up to 200 message ids from os.my_mail_list. Not together with fromAddress |
fromAddress |
string | no | A sender address, matched exactly: every unhandled mail that arrived from it. Not together with ids |
labels |
array of string | no | Every label each mail should carry. Replaces the current set |
handledState |
string, one of unhandled, replied, skipped, snoozed |
no | Where each mail stands now |
snoozedUntil |
string | no | ISO 8601 date and time the mail comes back. Only with handledState snoozed |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ updated, notFound }: how many mails were changed, and the ids given that are not in your mailbox (always[]when selecting byfromAddress). - API:
POST /v1/mail/triage(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
mail_selector_invalid |
Neither ids nor fromAddress was given, or both were. | Tool error |
mail_ids_invalid |
ids is not a list of 1 to 200 non-empty message ids. | Tool error |
mail_change_required |
Neither labels nor handledState was given, so there is nothing to record. | Tool error |
labels_invalid |
labels is not a list of non-empty strings of at most 64 characters. | Tool error |
handled_state_invalid |
handledState is not unhandled, replied, skipped or snoozed (escalated is a member’s state). | Tool error |
snoozed_until_required |
handledState is snoozed and snoozedUntil is missing or not a date. | Tool error |
snoozed_until_not_allowed |
snoozedUntil was given with a handledState other than snoozed. | Tool error |
Example:
{
"fromAddress": "[email protected]",
"labels": [
"Newsletter"
],
"handledState": "skipped"
}
Example:
{
"ids": [
"5f0c1d2e-0000-4000-8000-000000000003",
"5f0c1d2e-0000-4000-8000-000000000004"
],
"handledState": "skipped"
}
os.my_mail_reply
Reply to a message in your own mailbox, from your own address, with no approval step.
What the model reads:
Reply to one message in your own mailbox. Pass id from os.my_mail_list and the reply. Write the body as `markdown`; the OS sends it formatted with a plain-text copy, and raw HTML in it is not passed through. Or pass text, with optional html for a body you formatted yourself, as before; give markdown or text, not both, and never markdown with html. The subject comes from the message being answered, and the reply goes out from the address it arrived at, which has to be yours. It goes to the sender of the message being answered. Pass replyAll true to answer everyone on the original too: everyone else on its To and Cc is copied in, but for this mailbox’s own addresses. Optional cc and bcc, each one address or a list, copy in more people, seen or unseen; 50 addresses at most in all. Pass to, one address or a list, to send it to them in place of that sender; the subject, the address it leaves from and the threading still come from the original. With replyAll, anyone already in to is not copied in again. It threads under the original in the recipient’s mail client. Pass attachments to attach files: each by a public https link (url), by a file already on a mail in your mailbox (emailId and attachmentId), or inline as base64 for a small file. A mail carries up to 10 files, 7 MB together: a file past that, one that cannot be read or fetched, or an item that is not one is refused by name before anything leaves, and nothing is sent. Your signature, when you have set one, is added after the body; pass signature false to leave it off. The message you are answering is quoted below your reply and signature, under an `On <date>, <name> wrote:` line, as `>` lines in text and a blockquote in html; pass quote false to leave it off. Your own mail is yours: nothing waits for anyone’s approval, and the message leaves in this call. The sent copy is filed in your mailbox in the original’s thread, listing the files it carried, and the original is marked read and moves to handled state replied.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list: the mail this answers |
markdown |
string | no | The body in Markdown: headings, emphasis, lists, links, quotes, code and tables. The OS sends it formatted, with a plain-text copy. Give this or text, not both |
text |
string | no | The reply, as plain text, when not given as markdown |
html |
string | no | Optional HTML body beside text. Plain text is sent either way |
to |
string or array of string | no | Who the reply goes to, in place of the sender of the message being answered: one address or a list. Left out, it goes to that sender |
replyAll |
boolean | no | true answers everyone on the original: its sender, and everyone else on its To and Cc but this mailbox |
cc |
string or array of string | no | More people to copy in, seen by every recipient: one address or a list |
bcc |
string or array of string | no | People sent the reply that no other recipient sees: one address or a list |
attachments |
array of object | no | Optional files the reply carries: up to 10, 7 MB together. The message being answered’s own files are not attached unless you name them. Each item names one file in one of three ways: { url, filename?, contentType? }, a public https link the OS fetches, so a screenshot or any other hosted file is attached without writing out its bytes; { emailId, attachmentId, filename?, contentType? }, a file already on a mail in your mailbox, the ids as os.my_mail_read lists them; or { filename, contentType, base64 }, the bytes inline, for a small file. A link’s or a stored file’s filename and contentType are used unless you give your own; contentType is type/subtype, such as image/png. Refused whole, naming the file, before anything leaves: attachments_over_limit past the limits, attachment_unreadable for a stored file that is not in your mailbox or cannot be read, attachment_invalid for an item that is not one, attachment_link_refused for a link that is not a public https one or does not answer with the file |
signature |
boolean | no | false sends without your signature. Left out, the OS adds it when you have one |
quote |
boolean | no | false sends without the original quoted below. Left out, the OS quotes the message you are answering after the body and your signature |
No other fields are accepted.
- Effect: write.
- Side effects: Files the sent reply in your mailbox, in the original’s thread, marks the original read and, once sent, moves it to handled state
replied(clearing any snooze) and saves every recipient to your contacts. - Retry: Not retry-safe: a repeat acts again. A repeat sends a second reply. Call it again only if the first reported a refusal.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ status, id }:sent, orsend_failedwith the provider’serrorwhen it did not go out.idis the copy filed in your mailbox either way. - API:
POST /v1/mail/:id/reply(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
mail_field_required |
Neither markdown nor text says anything. | Tool error |
mail_body_conflict |
markdown was given with text or with html. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
no_mail_address |
You have no address in this enterprise yet, so nothing can leave as you. An owner gives one on People. | Tool error |
recipient_invalid |
The stored message names no address that can be replied to, or an address in to, cc or bcc is not an email address. The error names the address. | Tool error |
too_many_recipients |
The reply would go to more than 50 addresses in all, everyone a reply-all copies in counted. | Tool error |
sender_not_own_mailbox |
The address the original arrived at is not yours, or its domain is not active for sending. | Tool error |
sending_unavailable |
Sending from the enterprise’s own domain is not configured on this deployment. | Tool error |
attachments_over_limit |
attachments name more than 10 files, or more than 7 MB together; the refusal names the files that do not fit, and nothing was sent. | Tool error |
attachment_unreadable |
A file named by emailId and attachmentId is not on a mail in your mailbox, or could not be read; the refusal names it, and nothing was sent. | Tool error |
attachment_invalid |
An item of attachments names no file or more than one, gives base64 without a filename or bytes that are not base64, or a contentType that is not type/subtype; the refusal names it, and nothing was sent. | Tool error |
attachment_link_refused |
A url is not https, points at an internal address (itself or through a redirect), does not answer in time, or answers with an error; the refusal names the link, and nothing was sent. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"markdown": "Thursday at **10:00** works."
}
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"replyAll": true,
"markdown": "Thursday at **10:00** works for all of us."
}
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"markdown": "Fixed: the screenshot shows the new page, and the terms are attached again.",
"attachments": [
{
"url": "https://files.example.com/screenshots/fixed.png"
},
{
"emailId": "5f0c1d2e-0000-4000-8000-000000000003",
"attachmentId": "5f0c1d2e-0000-4000-8000-000000000009"
}
]
}
os.my_mail_send
Send a new mail from your own address, with no approval step.
What the model reads:
Send a new message from your own mailbox: to, subject and the body. to, cc and bcc each take one address or a list of them. Everyone in to and cc sees who else the mail went to; nobody sees bcc. An address named twice gets one copy, and a mail goes to at most 50 addresses in all. Write the body as `markdown`; the OS sends it formatted with a plain-text copy, and raw HTML in it is not passed through. Or pass text, with optional html for a body you formatted yourself, as before; give markdown or text, not both, and never markdown with html. It goes out from your own address in this enterprise, the one an owner gave you, or from one of your extra addresses when you name it as `from`. Pass attachments to attach files: each by a public https link (url), by a file already on a mail in your mailbox (emailId and attachmentId), or inline as base64 for a small file. A mail carries up to 10 files, 7 MB together: a file past that, one that cannot be read or fetched, or an item that is not one is refused by name before anything leaves, and nothing is sent. Your signature, when you have set one, is added after the body; pass signature false to leave it off. Your own mail is yours: nothing waits for anyone’s approval, and the message leaves in this call. The sent copy is filed in your mailbox, listing the files it carried. To answer a message already in your mailbox, use os.my_mail_reply instead, so it threads.
| Field | Type | Required | Description |
|---|---|---|---|
to |
string or array of string | yes | Who the mail is to: one email address, or a list |
cc |
string or array of string | no | Who is copied in, seen by every recipient: one address or a list |
bcc |
string or array of string | no | Who is sent the mail unseen by any other recipient: one address or a list |
subject |
string | yes | The subject line |
markdown |
string | no | The body in Markdown: headings, emphasis, lists, links, quotes, code and tables. The OS sends it formatted, with a plain-text copy. Give this or text, not both |
text |
string | no | The message, as plain text, when not given as markdown |
html |
string | no | Optional HTML body beside text. Plain text is sent either way |
from |
string | no | Optional sender: one of your extra addresses in this enterprise. Left out, your own address is used |
attachments |
array of object | no | Optional files the mail carries: up to 10, 7 MB together. Each item names one file in one of three ways: { url, filename?, contentType? }, a public https link the OS fetches, so a screenshot or any other hosted file is attached without writing out its bytes; { emailId, attachmentId, filename?, contentType? }, a file already on a mail in your mailbox, the ids as os.my_mail_read lists them; or { filename, contentType, base64 }, the bytes inline, for a small file. A link’s or a stored file’s filename and contentType are used unless you give your own; contentType is type/subtype, such as image/png. Refused whole, naming the file, before anything leaves: attachments_over_limit past the limits, attachment_unreadable for a stored file that is not in your mailbox or cannot be read, attachment_invalid for an item that is not one, attachment_link_refused for a link that is not a public https one or does not answer with the file |
signature |
boolean | no | false sends without your signature. Left out, the OS adds it when you have one |
No other fields are accepted.
- Effect: write.
- Side effects: Files the sent message in your mailbox, every recipient on it, and, once sent, saves every recipient to your contacts.
- Retry: Not retry-safe: a repeat acts again. A repeat sends a second message. Call it again only if the first reported a refusal.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ status, id }:sent, orsend_failedwith the provider’serrorwhen it did not go out.idis the copy filed in your mailbox either way. - API:
POST /v1/mail(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
mail_field_required |
Neither markdown nor text says anything. | Tool error |
mail_body_conflict |
markdown was given with text or with html. | Tool error |
no_mail_address |
You have no address in this enterprise yet, so nothing can leave as you. An owner gives one on People. | Tool error |
recipient_invalid |
An address in to, cc or bcc is not an email address, or to names nobody. The error names the address. | Tool error |
too_many_recipients |
to, cc and bcc name more than 50 addresses in all. | Tool error |
sender_not_own_mailbox |
Your address’s domain is not active for sending, or from is not an address you hold. |
Tool error |
sending_unavailable |
Sending from the enterprise’s own domain is not configured on this deployment. | Tool error |
attachments_over_limit |
attachments name more than 10 files, or more than 7 MB together; the refusal names the files that do not fit, and nothing was sent. | Tool error |
attachment_unreadable |
A file named by emailId and attachmentId is not on a mail in your mailbox, or could not be read; the refusal names it, and nothing was sent. | Tool error |
attachment_invalid |
An item of attachments names no file or more than one, gives base64 without a filename or bytes that are not base64, or a contentType that is not type/subtype; the refusal names it, and nothing was sent. | Tool error |
attachment_link_refused |
A url is not https, points at an internal address (itself or through a redirect), does not answer in time, or answers with an error; the refusal names the link, and nothing was sent. | Tool error |
Example:
{
"to": "[email protected]",
"subject": "Thursday",
"markdown": "Thursday at **10:00** works for me."
}
Example:
{
"to": [
"[email protected]",
"[email protected]"
],
"cc": "[email protected]",
"subject": "Thursday",
"markdown": "Thursday at **10:00** works for me."
}
Example:
{
"to": "[email protected]",
"subject": "The error on checkout",
"markdown": "The screenshot shows the error.",
"attachments": [
{
"url": "https://files.example.com/screenshots/checkout-error.png"
}
]
}
os.my_mail_forward
Forward a message from your own mailbox to somebody else, from your own address, with no approval step.
What the model reads:
Forward one message from your own mailbox to somebody else. Pass id from os.my_mail_list and to, who it goes to. to, cc and bcc each take one address or a list of them. Everyone in to and cc sees who else the mail went to; nobody sees bcc. An address named twice gets one copy, and a mail goes to at most 50 addresses in all. Optional markdown or text (not both) is a note placed above the forwarded message, sent formatted with a plain-text copy when written as markdown, and optional from is one of your extra addresses to send from. The new message carries the original under a forwarded-message line that says who wrote it and when: its text and, when it has HTML, its formatting, sanitised, with its pictures where they were; and the original’s files, its pictures among them, go with it. Pass attachments to add more files: each by a public https link (url), by a file already on a mail in your mailbox (emailId and attachmentId), or inline as base64 for a small file. The original’s files and yours count towards the 10 files, 7 MB a mail carries: past that, or when one of them cannot be read or fetched, or an item is not one, the forward is refused naming the files, and nothing is sent. Your signature, when you have set one, is added after your note and above the forwarded message; pass signature false to leave it off. Your own mail is yours: nothing waits for anyone’s approval, and the message leaves in this call. The sent copy is filed in your mailbox in the original’s thread, and the original is marked read; its handled state does not change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list: the mail to pass on |
to |
string or array of string | yes | Who the forward is to: one email address, or a list |
cc |
string or array of string | no | Who is copied in, seen by every recipient: one address or a list |
bcc |
string or array of string | no | Who is sent the forward unseen by any other recipient: one address or a list |
markdown |
string | no | Optional note above the forwarded message, in Markdown. The OS sends it formatted, with a plain-text copy. Give this or text, not both |
text |
string | no | Optional note above the forwarded message, as plain text |
from |
string | no | Optional sender: one of your extra addresses in this enterprise. Left out, your own address is used |
attachments |
array of object | no | Optional files added to the original’s, which go with the forward anyway: the original’s and these together up to 10 files, 7 MB. Each item names one file in one of three ways: { url, filename?, contentType? }, a public https link the OS fetches, so a screenshot or any other hosted file is attached without writing out its bytes; { emailId, attachmentId, filename?, contentType? }, a file already on a mail in your mailbox, the ids as os.my_mail_read lists them; or { filename, contentType, base64 }, the bytes inline, for a small file. A link’s or a stored file’s filename and contentType are used unless you give your own; contentType is type/subtype, such as image/png. Refused whole, naming the file, before anything leaves: attachments_over_limit past the limits, attachment_unreadable for a stored file that is not in your mailbox or cannot be read, attachment_invalid for an item that is not one, attachment_link_refused for a link that is not a public https one or does not answer with the file |
signature |
boolean | no | false sends without your signature. Left out, the OS adds it when you have one |
No other fields are accepted.
- Effect: write.
- Side effects: Files the forwarded message in your mailbox, in the original’s thread, marks the original read and, once sent, saves every recipient to your contacts.
- Retry: Not retry-safe: a repeat acts again. A repeat forwards the message a second time. Call it again only if the first reported a refusal.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ status, id }:sent, orsend_failedwith the provider’serrorwhen it did not go out.idis the copy filed in your mailbox either way. - API:
POST /v1/mail/:id/forward(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
mail_body_conflict |
markdown was given with text or with html. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
no_mail_address |
You have no address in this enterprise yet, so nothing can leave as you. An owner gives one on People. | Tool error |
recipient_invalid |
An address in to, cc or bcc is not an email address, or to names nobody. The error names the address. | Tool error |
too_many_recipients |
to, cc and bcc name more than 50 addresses in all. | Tool error |
sender_not_own_mailbox |
Your address’s domain is not active for sending, or from is not an address you hold. |
Tool error |
sending_unavailable |
Sending from the enterprise’s own domain is not configured on this deployment. | Tool error |
attachments_over_limit |
The original’s files and the attachments you add are past 10 files or 7 MB together; the refusal names the files that do not fit, and nothing was sent. | Tool error |
attachment_unreadable |
One of the original’s files could not be read, or a file named by emailId and attachmentId is not on a mail in your mailbox or could not be read; the refusal names it, and nothing was sent. | Tool error |
attachment_invalid |
An item of attachments names no file or more than one, gives base64 without a filename or bytes that are not base64, or a contentType that is not type/subtype; the refusal names it, and nothing was sent. | Tool error |
attachment_link_refused |
A url is not https, points at an internal address (itself or through a redirect), does not answer in time, or answers with an error; the refusal names the link, and nothing was sent. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"to": "[email protected]",
"text": "Can you take this one?"
}
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"to": "[email protected]",
"text": "Can you take this one? The screenshot shows where it fails.",
"attachments": [
{
"url": "https://files.example.com/screenshots/failure.png"
}
]
}
os.my_mail_delete
Delete a message from your own mailbox for good.
What the model reads:
Delete one message from your own mailbox for good: the message, its attachments and their stored files are removed, and nothing brings them back. Pass id from os.my_mail_list. This is not the archive: to keep a mail out of the way, record it as skipped with os.my_mail_set_handled instead. An id from anyone else’s mailbox is not found.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A message id from os.my_mail_list |
No other fields are accepted.
- Effect: write.
- Side effects: Removes the message, its attachment records and their stored files; their storage is no longer counted.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds no such message and reports email_not_found: the message is gone either way.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ id }: the message that is gone. - API:
DELETE /v1/mail/:id(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
email_not_found |
The id is not in the caller's own mailbox, including a member's mail and another person's. | Tool error |
mail_delete_failed |
The message’s stored files could not be removed, so the message was kept whole. Try again. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003"
}
os.my_mail_actions
List the one-click buttons your inbox offers: the tasks that declare a mailbox action.
What the model reads:
List the one-click buttons your inbox offers. Each is a task whose current version declares a mailbox action: a task of the enterprise, which os.my_mail_start_action starts over your own mailbox (taskId set), or a public Catalog template that declares one and the enterprise holds no clone of, which has to be cloned first (catalogTaskId set). on says where the button sits: mailbox, over the whole mailbox, or mail, on one message, which starts the run with that message’s id. label is the button’s words, as the task declares them. schedule is your own cadence for a button, set with os.my_mail_schedule_action, or null.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns:
{ actions }: each{ taskId, catalogTaskId, slug, name, label, on, schedule }, exactly one oftaskIdandcatalogTaskIdset, by label.scheduleis your own cadence for that button ({ cron, timezone, enabled, nextRunAt, lastFiredAt, lastRunId, refusalReason }), or null when you press it only by hand. - API:
GET /v1/mail/actions(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
Example:
{}
os.my_mail_start_action
Press one of your inbox’s buttons: start that task over your own mailbox.
What the model reads:
Press one of the buttons os.my_mail_actions lists: start the task by its taskId, over your own mailbox. The run reads and files your mail rather than its member’s, and the runs it chains do too. For a button on one message (on mail), pass emailId, the message it is pressed on, which the run receives as its emailId input. A busy task or member makes the run wait its turn as pending rather than refusing. A template (catalogTaskId set) cannot be started until it is cloned.
| Field | Type | Required | Description |
|---|---|---|---|
taskId |
string | yes | The task to start: a taskId from os.my_mail_actions |
emailId |
string | no | For a button on one message: that message’s id from os.my_mail_list |
No other fields are accepted.
- Effect: write.
- Side effects: Starts a run of the task, recorded as acting on your mailbox.
- Retry: Not retry-safe: a repeat acts again. A repeat starts a second run. Read the first run before calling again.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The run started: its
id,status(queued, orpendingwhile it waits its turn) andtaskId. - API:
POST /v1/mail/actions/:taskId/runs(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
task_not_found |
taskId is not a task of this enterprise. | Tool error |
task_not_runnable |
The task is deprecated, has no version yet, or nobody holds its role. | Tool error |
task_disabled |
The task’s runs are switched off. | Tool error |
input_required |
The task requires an input the button does not pass; the error names the field. | Tool error |
Example:
{
"taskId": "0a7d2c9e-0000-4000-8000-000000000011"
}
Example:
{
"taskId": "0a7d2c9e-0000-4000-8000-000000000012",
"emailId": "5f0c1d2e-0000-4000-8000-000000000003"
}
os.my_mail_schedule_action
Press one of your inbox’s buttons on a cadence: each firing runs it over your own mailbox.
What the model reads:
Put one of the buttons os.my_mail_actions lists on a cadence of your own: each firing presses it for you, over your own mailbox, as os.my_mail_start_action does, and the run is recorded as asked for by you. Only a button over the whole mailbox (on mailbox) can be scheduled; one on a single message needs a message. cron is five fields (*/15 * * * * is every 15 minutes, */15 8-21 * * 1-5 the same on weekdays from 08:00 to 21:45); timezone is an IANA zone, or enterprise (the default) to follow the enterprise’s. enabled false keeps the cadence without firing it. Saving again changes it. A firing starts nothing while the button’s last run over your mailbox is still going, or failed and nobody cleared it, and says so in the schedule’s refusalReason.
| Field | Type | Required | Description |
|---|---|---|---|
taskId |
string | yes | The button to schedule: a taskId from os.my_mail_actions, on mailbox |
cron |
string | yes | Five-field cron, read in timezone, such as */15 * * * * |
timezone |
string | no | An IANA zone such as Europe/Madrid, or enterprise (the default) |
enabled |
boolean | no | false keeps the cadence without firing it (default true) |
No other fields are accepted.
- Effect: write.
- Side effects: Saves your cadence for the button; each firing starts a run of the task over your mailbox.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat saves the same cadence again.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The cadence as saved:
{ cron, timezone, enabled, nextRunAt, lastFiredAt, lastRunId, refusalReason }. - API:
PUT /v1/mail/actions/:taskId/schedule(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
task_not_found |
taskId is not a task of this enterprise. | Tool error |
not_a_mailbox_action |
The task is not active or declares no button over the whole mailbox. | Tool error |
no_mail_address |
You have no mailbox in this enterprise yet. | Tool error |
invalid_schedule |
cron or timezone cannot be read, or the cadence never comes round. | Tool error |
Example:
{
"taskId": "0a7d2c9e-0000-4000-8000-000000000011",
"cron": "*/15 * * * *"
}
Example:
{
"taskId": "0a7d2c9e-0000-4000-8000-000000000011",
"cron": "*/15 8-21 * * 1-5",
"timezone": "Europe/Madrid"
}
os.my_mail_unschedule_action
Stop pressing one of your inbox’s buttons on a cadence.
What the model reads:
Stop the cadence os.my_mail_schedule_action set for one of your inbox’s buttons. The button stays, and a run already started finishes. cleared says whether there was a cadence to stop.
| Field | Type | Required | Description |
|---|---|---|---|
taskId |
string | yes | The button whose cadence to stop: a taskId from os.my_mail_actions |
No other fields are accepted.
- Effect: write.
- Side effects: Deletes your cadence for the button.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds no cadence and reports cleared false.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns:
{ cleared }: true when a cadence was stopped, false when there was none. - API:
DELETE /v1/mail/actions/:taskId/schedule(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
Example:
{
"taskId": "0a7d2c9e-0000-4000-8000-000000000011"
}
os.my_mail_contacts
List or search your own contacts: the people you have written to, and those you added.
What the model reads:
List the contacts of your own mailbox: everyone a send, reply or forward from it went to, saved as it left, and everyone you added by hand. Most recently written to first, then by name. Pass search to keep only contacts whose name or address contains it, any case: search Sarah, or acme.com, finds the address to write to. Pass directory true to add the enterprise’s own people and members who have an address, after your contacts and each only once. limit is how many rows (default 50, max 200). Mail that arrived never makes a contact, so nobody who only wrote to you is here until you write back.
| Field | Type | Required | Description |
|---|---|---|---|
search |
string | no | Only contacts whose name or address contains this, any case |
directory |
boolean | no | Also offer the enterprise’s own people and members who have an address |
limit |
integer, 1 to 200 | no | Rows to return. Default 50 |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ data }: each contact withid(null on a directory row),address,name(empty when none is known),source(autowhen a send saved it,manualwhen it was added by hand,directoryfor one of the enterprise’s own people or members offered beside the contacts),nameByHand(a name set by hand, which no later send replaces),mailCountandlastMailedAt(null until the mailbox first writes to it). - API:
GET /v1/mail/contacts(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
contact_search_invalid |
search is not text, or is longer than 200 characters. | Tool error |
contact_limit_invalid |
limit is not a whole number from 1 to 200. | Tool error |
Example:
{
"search": "sarah"
}
Example:
{
"search": "acme",
"directory": true,
"limit": 10
}
os.my_mail_contact_save
Add a contact to your own mailbox, or name one already there.
What the model reads:
Save an address to the contacts of your own mailbox. Pass address and, optionally, name. A new address is added as one you saved by hand; an address already in your contacts keeps its place and history, and takes the name when you give one. A name you set here is yours: a later send never replaces it. Leave name out to keep the name a contact already has. An empty name clears it.
| Field | Type | Required | Description |
|---|---|---|---|
address |
string | yes | The contact’s email address |
name |
string | no | The name the contact goes by. Kept over any a later send carries |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The contact saved, with
id(null on a directory row),address,name(empty when none is known),source(autowhen a send saved it,manualwhen it was added by hand,directoryfor one of the enterprise’s own people or members offered beside the contacts),nameByHand(a name set by hand, which no later send replaces),mailCountandlastMailedAt(null until the mailbox first writes to it). - API:
POST /v1/mail/contacts(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
contact_address_invalid |
address is not one email address. | Tool error |
contact_name_invalid |
name is not text, or is longer than 200 characters. | Tool error |
Example:
{
"address": "[email protected]",
"name": "Sarah Jones"
}
os.my_mail_contact_delete
Remove a contact from your own mailbox.
What the model reads:
Remove one contact from your own mailbox. Pass id from os.my_mail_contacts; a directory row has none, since it is not one of your contacts. Only the contact goes: mail to and from the address stays. A later send to the address saves it again.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A contact id from os.my_mail_contacts |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds no such contact and reports contact_not_found: it is gone either way.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ id }: the contact that is gone. - API:
DELETE /v1/mail/contacts/:id(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
contact_not_found |
The id is not one of your contacts, including another mailbox’s. | Tool error |
Example:
{
"id": "7c1e2f3a-0000-4000-8000-000000000021"
}
os.my_mail_signature
Read the signature the OS adds to every mail you send, reply and forward.
What the model reads:
Read your own mailbox’s signature: what the OS adds after the body of every mail you send, reply or forward, from the portal, the API or MCP, unless that send says signature false. Its html is the signature as you formatted it, sanitised; its text is the plain-text form, which a mail’s text part carries under a `-- ` line. Both are empty when you have no signature. With none of your own, your mail is signed with the enterprise’s signature template, filled in with your name, title and address, unless useTemplate is false. Mail from one of your extra addresses carries that address’s own signature instead, when it has one: see os.my_mail_addresses.
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: Your signature:
html(sanitised, empty for a signature written as text),text(its plain-text form),updatedAt(null when you have none),useTemplate(whether the enterprise’s signature template signs your mail while you have no signature of your own) andtemplate(that template filled in for you,{ html, text }, or null when the enterprise has none). - API:
GET /v1/mail/signature(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
Example:
{}
os.my_mail_signature_set
Set or clear the signature the OS adds to every mail you send.
What the model reads:
Set your own mailbox’s signature, which the OS adds after the body of every mail you send, reply or forward. Pass html for a formatted signature (bold, links, a few lines): it is sanitised to what mail may carry, and its plain-text form is derived from it, with each link written after its words. Or pass text alone for a plain signature. With html given, text is ignored. Each is at most 20 KB. Pass both empty to clear the signature: your mail then leaves with the enterprise’s signature template, filled in for you, or with none when there is no template or useTemplate is false. Pass useTemplate false to send with no signature at all while you have none of your own, true to use the template again; left out, it stays as it was. Given without html or text, your signature stays as it is. To sign mail from one of your extra addresses differently, use os.my_mail_address_signature_set.
| Field | Type | Required | Description |
|---|---|---|---|
html |
string | no | The signature as HTML. Sanitised; its text form is derived |
text |
string | no | The signature as plain text, used when no html is given |
useTemplate |
boolean | no | Whether the enterprise’s signature template signs your mail while you have no signature of your own |
No other fields are accepted.
- Effect: write.
- Side effects: Every mail you send, reply or forward from now on carries it, unless that send says signature false.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: Your signature as saved:
html(sanitised, empty for a signature written as text),text(its plain-text form),updatedAt(null when you have none),useTemplate(whether the enterprise’s signature template signs your mail while you have no signature of your own) andtemplate(that template filled in for you,{ html, text }, or null when the enterprise has none). - API:
PUT /v1/mail/signature(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
signature_invalid |
html or text is not text, or useTemplate is not true or false. | Tool error |
signature_too_large |
html or text is larger than 20 KB. | Tool error |
Example:
{
"html": "<p><strong>Sarah Jones</strong><br>Head of Sales · <a href=\"https://acme.com\">acme.com</a></p>"
}
Example:
{
"text": "Sarah Jones\nHead of Sales"
}
Example:
{
"html": "",
"text": ""
}
Example:
{
"html": "",
"text": "",
"useTemplate": false
}
os.my_mail_addresses
List your own extra addresses, each with the signature mail from it carries.
What the model reads:
List the extra addresses of your own mailbox: the further addresses at the enterprise’s domains an owner gave you, which deliver to your mailbox and which you can send from by naming one as `from` on os.my_mail_send or os.my_mail_forward. Your own address is not listed. Each comes with replyFromAlias and its own signature, which a mail leaving from that address carries in place of your mailbox’s; null means it signs as your mailbox does (os.my_mail_signature). Set or clear one with os.my_mail_address_signature_set. Adding and removing an address is an owner’s, on People.
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:
{ aliases }: each of your extra addresses, by address, withid,address,replyFromAlias(whether a reply to mail that arrived at it leaves from it, rather than from your own address) andsignature(its own,{ html, text }withhtmlsanitised and empty for one written as text, or null while it signs as your mailbox does).[]when you have none. - API:
GET /v1/mail/aliases(mail:read)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
Example:
{}
os.my_mail_address_signature_set
Set or clear the signature mail from one of your extra addresses carries.
What the model reads:
Set the signature of one of your own extra addresses: what the OS adds after the body of a mail you send or forward from that address, and of a reply that leaves from it, in place of your mailbox’s signature, unless that send says signature false. Pass id from os.my_mail_addresses, and html for a formatted signature: it is sanitised to what mail may carry, and its plain-text form is derived from it, with each link written after its words. Or pass text alone for a plain signature. With html given, text is ignored. Each is at most 20 KB. Pass both empty, or leave both out, to clear it: mail leaving from that address then carries your mailbox’s signature (os.my_mail_signature), or with none of your own, the enterprise’s signature template unless you switched it off, or nothing.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | An address id from os.my_mail_addresses |
html |
string | no | The signature as HTML. Sanitised; its text form is derived |
text |
string | no | The signature as plain text, used when no html is given |
No other fields are accepted.
- Effect: write.
- Side effects: Every mail that leaves from the address from now on carries it, unless that send says signature false.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ aliases }: every one of your extra addresses after the change, as os.my_mail_addresses lists them, withid,address,replyFromAlias(whether a reply to mail that arrived at it leaves from it, rather than from your own address) andsignature(its own,{ html, text }withhtmlsanitised and empty for one written as text, or null while it signs as your mailbox does). - API:
PUT /v1/mail/aliases/:id/signature(mail:write)
| Error | When | What happens |
|---|---|---|
api_token_cannot_reach_mail |
An API token called it. A token belongs to the enterprise and to nobody, so it has no mailbox. | Tool error |
user_not_found |
The caller is no longer a member of the enterprise the call is in. | Tool error |
alias_not_found |
The id is not one of your extra addresses, including another mailbox’s. | Tool error |
use_mailbox_owner_handoff |
The address has since become a member’s own address, so it is no longer one of yours to sign. | Tool error |
alias_address_taken |
The address has since become a person’s own address, so it is no longer one of yours to sign. | Tool error |
signature_invalid |
html or text is not text. | Tool error |
signature_too_large |
html or text is larger than 20 KB. | Tool error |
Example:
{
"id": "3b8e4d5f-0000-4000-8000-000000000031",
"html": "<p><strong>Acme Sales</strong><br><a href=\"https://acme.com\">acme.com</a></p>"
}
Example:
{
"id": "3b8e4d5f-0000-4000-8000-000000000031",
"text": "Acme Support\nWe answer within a day"
}
Example:
{
"id": "3b8e4d5f-0000-4000-8000-000000000031",
"html": "",
"text": ""
}
os.escalate_mail
The gate a mail that needs the CEO opens: the mail, why it matters, and what is suggested.
What the model reads:
Escalate a mail the CEO has to see (a VIP, something sensitive, or a question only they can answer), then stop. The gate carries the mail, why it matters and which of its three choices you suggest. It appears on the gates page and in the assigned member’s chat thread, where the CEO chooses Reply, Snooze or Leave it. Reply and Snooze end this run with outcome ceo_approved, the choice as ceoChoice (reply or snooze), this mail as mailId, and ceoNote: what the reply should say, or the ISO 8601 time the snooze ends. Leave it cancels this run and archives the mail. Call it last.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The mail the escalation is about |
mailId |
string | no | The same id, under the key both mail gates use |
subject |
string | yes | |
fromAddress |
string | yes | |
summary |
string | yes | Why this mail needs the CEO |
suggestion |
string | yes | Which choice you suggest (Reply, Snooze or Leave it) and why, in one or two sentences |
No other fields are accepted.
- Effect: write.
- Side effects: Opens one CEO gate for this run and parks the run until it is decided.
- Retry: Not retry-safe: a repeat acts again. Escalating the same mail again opens a second gate carrying its own summary, so the CEO is asked twice. Whether a mail has already been escalated is triage’s to track, not this gate’s.
- Called by: a run, the OS itself, on nobody’s call.
- Needs:
- A gate: the CEO decides every call, whatever the task declares.
- The gate offers these choices in place of Approve and Reject. Reply (
reply): A reply is drafted and comes back to you to approve before anything is sent. Snooze (snooze): Nothing is sent. The mail is set aside until the time you pick. Leave it (leave): No reply is sent and the mail is archived.
- Returns: The CEO’s choice, to the task that runs next:
ceoChoice(replyorsnooze),ceoNoteandmailId. Leave it hands nothing on: the run is cancelled and the mail archived.
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000003",
"subject": "Renewal before Friday",
"fromAddress": "[email protected]",
"summary": "A VIP contact wants to renew before Friday and has asked for a call.",
"suggestion": "Reply: confirm the renewal terms and offer Thursday for the call."
}
os.mail_reply_draft
The gate a drafted reply opens, so no reply leaves without a decision on it.
What the model reads:
Nobody calls this: the OS opens this gate itself when the CEO’s instruction on an escalated mail is to reply. It carries the mail the reply answers and the drafted body, and waits for a decision before anything is sent.
| Field | Type | Required | Description |
|---|---|---|---|
mailId |
string | yes | The mail this reply answers |
body |
string | yes | The drafted reply, as it would be sent |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A second draft for the same mail opens a second gate, decided on its own: nothing folds it into the first.
- Called by: the OS itself, on nobody’s call.
- Returns: The decision on the draft: approved and it may be sent, or not, with the decider's note.
Example:
{
"mailId": "5f0c1d2e-0000-4000-8000-000000000003",
"body": "Thursday works — I will send an invitation shortly."
}
os.list_kpis
List the signed-off KPIs the run's teams own and those its task is the source of, with their lights.
What the model reads:
List the KPIs this run may read: the KPIs of every team its member sits on or leads, and any KPI whose source is this run's task, whichever layer owns it. Only KPIs a person has signed off are listed. Each row carries its target (value, direction, AMBER band, on-target-worsening rule), cadence, owner (layer and id), source (kind and ref), latest reading, current light and whether it is overdue. The light is null when the KPI has no target or no reading yet. No arguments. Never a KPI of a team the member is not on unless its source is this run's task, and never another enterprise's.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Returns:
{ data }: one row per KPI, each withid,name,ownerLayer(company,team,role,task, or null for a company KPI set before layers),ownerId,sourceKind(taskorperson),sourceRef(the task or person id),target,cadenceMinutes,light,overdueandlastReading(id,value,takenAt,recordedBy,runId), or null before the first reading. - API:
POST /v1/runs/self/tools/os.list_kpis(run:self)
Example:
{}
os.record_kpi_reading
Record a reading for a KPI whose source is this run's task.
What the model reads:
Record one reading for the KPI named by kpiId (from os.list_kpis). Only a run of the task that KPI names as its source (sourceKind task, sourceRef this run's task) may record one, and only once a person has signed the KPI off. Pass value and, optionally, takenAt (ISO 8601; defaults to now). No other field is accepted: no os.* tool lets a run change a target, band, cadence or source. The reading is recorded as taken by this run (`recordedBy: run:<runId>`); a run cannot record on another run's behalf. It lands in the same history HQ's board and the KPI readings API read, so the light they show moves with it.
| Field | Type | Required | Description |
|---|---|---|---|
kpiId |
string | yes | A KPI id from os.list_kpis |
value |
number | yes | |
takenAt |
string | no | ISO 8601. Defaults to now. |
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 tool call, like every other os.* write tool: a repeat of the same call records once and returns the same reading.
- Called by: a run, the API.
- Returns: The recorded reading and the KPI it landed on:
kpiId,name,readingId,value,takenAt,recordedByandrunId(this run),target, and the KPI’slightas it now stands. - API:
POST /v1/runs/self/tools/os.record_kpi_reading(run:self)
| Error | When | What happens |
|---|---|---|
kpi_id_required |
kpiId is missing. |
Tool error |
value_required |
value is missing or not a number. |
Tool error |
taken_at_invalid |
takenAt is not a timestamp anything can read. |
Tool error |
kpi_not_found |
kpiId does not name a KPI this run may record: another enterprise's, one whose source is not this run's task, or one nobody has signed off yet. |
Tool error |
Example:
{
"kpiId": "5f0c1d2e-0000-4000-8000-000000000009",
"value": 42
}
os.get_enterprise_kpis
The company's KPI targets, bands, cadence and source.
What the model reads:
The company's KPI targets as set: unit, target and direction, AMBER band, cadence and source. A KPI waiting for a target has targetValue null. Each KPI carries signedOffAt: null while it waits for a person to sign it off, and until then no run sees it or records a reading for it.
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.
- API:
GET /v1/enterprise/kpi-targets(enterprise:read)
os.set_enterprise_kpis
Replace the company's KPI target list.
What the model reads:
Replace the company's complete KPI target list. A target needs its unit, direction, cadence and source; a no-target KPI is accepted. Uses the same validation as the portal. The answer's awaitingSignOff names every KPI still waiting for sign-off, or is null: an API token never signs a KPI off, so a KPI it adds or changes waits for a person.
| Field | Type | Required | Description |
|---|---|---|---|
kpis |
array of object | yes | The complete KPI target list. Every item is validated by the API. |
kpis[].id |
string | no | |
kpis[].name |
string | yes | |
kpis[].unit |
string | no | |
kpis[].targetValue |
number | no | |
kpis[].targetDirection |
string, one of at_least, at_most |
no | |
kpis[].amberBand |
number, at least 0 | no | |
kpis[].amberBandType |
string, one of absolute, percentage |
no | |
kpis[].onTargetWorseningRule |
boolean | no | |
kpis[].cadenceMinutes |
integer, at least 1 | no | |
kpis[].sourceKind |
string, one of task, person |
no | |
kpis[].sourceRef |
string | no | |
kpis[].isKey |
boolean | no |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PATCH /v1/enterprise/kpi-targets(enterprise:write)
| Error | When | What happens |
|---|---|---|
invalid_kpis |
A KPI is incomplete or malformed. | Tool error |
os.get_team_kpis
A team's KPI targets, including its key KPI.
What the model reads:
A team's own KPI targets as set, including which one is its key KPI. This is the target list, not the role and task KPI tree. Each KPI carries signedOffAt: null while it waits for a person to sign it off, and until then no run sees it or records a reading for it.
| Field | Type | Required | Description |
|---|---|---|---|
teamId |
string | yes | The team whose KPI targets are read. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
GET /v1/teams/:teamId/kpi-targets(teams:read)
| Error | When | What happens |
|---|---|---|
team_not_found |
The team is not in this enterprise. | Tool error |
os.set_team_kpis
Replace a team's KPI target list and key KPI.
What the model reads:
Replace a team's complete KPI target list. Two key KPIs are refused; a list with none marked is stored with no key KPI. Uses the same validation as the portal. The answer's awaitingSignOff names every KPI still waiting for sign-off, or is null: an API token never signs a KPI off, so a KPI it adds or changes waits for a person.
| Field | Type | Required | Description |
|---|---|---|---|
teamId |
string | yes | The team whose KPI targets are replaced. |
kpis |
array of object | yes | The complete KPI target list. Every item is validated by the API. |
kpis[].id |
string | no | |
kpis[].name |
string | yes | |
kpis[].unit |
string | no | |
kpis[].targetValue |
number | no | |
kpis[].targetDirection |
string, one of at_least, at_most |
no | |
kpis[].amberBand |
number, at least 0 | no | |
kpis[].amberBandType |
string, one of absolute, percentage |
no | |
kpis[].onTargetWorseningRule |
boolean | no | |
kpis[].cadenceMinutes |
integer, at least 1 | no | |
kpis[].sourceKind |
string, one of task, person |
no | |
kpis[].sourceRef |
string | no | |
kpis[].isKey |
boolean | no |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PATCH /v1/teams/:teamId/kpi-targets(teams:write)
| Error | When | What happens |
|---|---|---|
team_not_found |
The team is not in this enterprise. | Tool error |
invalid_kpis |
A KPI is incomplete or two KPIs are marked key. | Tool error |
os.set_context
Store a JSON value for the enterprise under a key, so a later run can read it.
What the model reads:
Store value at key for this enterprise. A later call with the same key replaces the value. Any later run of any task in the enterprise can read it, and a task version that declares a prefix of the key receives it in input.context when a run starts. value is JSON and at most 16KB. This is bookkeeping between runs, not memory, and not a place for a secret. A repeat of the same tool call returns the value that call stored and does not write again.
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | A short key, such as sitemap:https://example.com/pricing. No spaces. Not a secret. |
value |
any | yes | Any JSON value, at most 16KB. Not a secret. |
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 tool call, like every other os.* write tool: a repeat of the same call stores once and returns the value that call stored.
- Called by: a run, the API.
- Returns:
{ key, value }: the key and the JSON value now stored for it. - API:
POST /v1/runs/self/tools/os.set_context(run:self)
| Error | When | What happens |
|---|---|---|
key_required |
key is missing. |
Tool error |
key_invalid |
key is empty, longer than 512 characters, or contains whitespace or a control character. |
Tool error |
value_required |
value is missing. |
Tool error |
value_not_json |
value is not JSON. |
Tool error |
value_too_large |
value is over 16KB. |
Tool error |
Example:
{
"key": "sitemap:https://example.com/pricing",
"value": {
"status": "absorbed"
}
}
os.get_context
Read one enterprise context value, or null when the key has never been set.
What the model reads:
Read the JSON value stored at key for this enterprise. Returns value null when the key has never been set. A run whose task declares a prefix of the key already has it in input.context; this reads one key that was not loaded, or a key another run has changed since this run started.
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | A short key, such as sitemap:https://example.com/pricing. No spaces. Not a secret. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Returns:
{ key, value }.valueis null when the key has never been set. - API:
POST /v1/runs/self/tools/os.get_context(run:self)
| Error | When | What happens |
|---|---|---|
key_required |
key is missing. |
Tool error |
key_invalid |
key is empty, longer than 512 characters, or contains whitespace or a control character. |
Tool error |
Example:
{
"key": "sitemap:https://example.com/pricing"
}
os.delete_context
Remove one enterprise context key. A missing key is a success.
What the model reads:
Remove key from this enterprise. A key that is not there is a success. Used when the thing the key tracked has gone, such as a URL that left the sitemap. A repeat of the same tool call returns the result that call stored and does not delete a key a later call has set.
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | A short key, such as sitemap:https://example.com/pricing. No spaces. Not a secret. |
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 tool call, like every other os.* write tool: a repeat of the same call removes the key once and returns that call’s result.
- Called by: a run, the API.
- Returns:
{ key, deleted }.deletedis false when the key was not there. - API:
POST /v1/runs/self/tools/os.delete_context(run:self)
| Error | When | What happens |
|---|---|---|
key_required |
key is missing. |
Tool error |
key_invalid |
key is empty, longer than 512 characters, or contains whitespace or a control character. |
Tool error |
Example:
{
"key": "sitemap:https://example.com/pricing"
}
kpi.record_reading
Record one reading of a KPI by hand: the value, when it was taken, and who or what took it.
What the model reads:
Record one reading of a KPI by hand: the value, when it was taken, and who or what took it. Every reading is kept — correcting a wrong one means recording a new reading, never editing or deleting the old one — so a KPI history shows how it got to where it is. The light and the trend are read off the readings, so recording one is what moves them. A KPI nobody has signed off takes no reading: it is refused with 409 kpi_not_signed_off.
| Field | Type | Required | Description |
|---|---|---|---|
kpiId |
string | yes | The KPI the reading belongs to. |
value |
number | yes | The number read, in the KPI's own unit. |
takenAt |
string | yes | When the reading was taken, as an ISO 8601 timestamp, e.g. 2026-01-08T00:00:00Z. |
recordedBy |
string | yes | Who or what took the reading: a member id, or the agent or tool that read it. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. Every call appends a reading, so a repeat records a second one.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The reading as recorded:
id,kpiId,value,takenAt(ISO 8601) andrecordedBy. - API:
POST /v1/kpis/:kpiId/readings(kpis:write)
| Error | When | What happens |
|---|---|---|
kpi_not_found |
kpiId names no KPI in this enterprise, another enterprise's included. |
Tool error |
kpi_not_signed_off |
Nobody has signed the KPI off yet, so it takes no reading. | Tool error |
Example:
{
"kpiId": "5f0c1d2e-0000-4000-8000-000000000009",
"value": 3.5,
"takenAt": "2026-01-08T00:00:00Z",
"recordedBy": "weekly-metrics-export"
}
kpi.list_readings
One KPI's readings, newest first, corrected ones included.
What the model reads:
One KPI's readings, newest first: the value, when it was taken and who or what took it. This is the whole history behind the KPI's light and its trend, including any reading a later one corrected.
| Field | Type | Required | Description |
|---|---|---|---|
kpiId |
string | yes | The KPI whose readings to list. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: Every reading of the KPI, newest by
takenAtfirst, each withid,kpiId,value,takenAtandrecordedBy. - API:
GET /v1/kpis/:kpiId/readings(kpis:read)
| Error | When | What happens |
|---|---|---|
kpi_not_found |
kpiId names no KPI in this enterprise, another enterprise's included. |
Tool error |
Example:
{
"kpiId": "5f0c1d2e-0000-4000-8000-000000000009"
}
role.list_kpis
A role's KPIs, oldest first, with the team KPI each serves, its sign-off, light, trend and readings.
What the model reads:
A role's KPIs, oldest first: each one's target, direction, AMBER band, cadence, source, the team KPI it serves (servesName names it; served is false for one that serves none), whether a person has signed it off, its light and trend (null until it is signed off) and its readings. Not found for a role in another enterprise.
| Field | Type | Required | Description |
|---|---|---|---|
roleId |
string | yes | The role whose KPIs to list. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
GET /v1/roles/:roleId/kpis(roles:read)
| Error | When | What happens |
|---|---|---|
role_not_found |
roleId names no role in this enterprise, another enterprise's included. |
Tool error |
role.define_kpi
Propose a KPI on a role, waiting for a person to sign it off.
What the model reads:
Propose a KPI on a role, with the same fields as a KPI on any other layer. It waits for a person to sign it off, and until then draws no light and takes no reading. A KPI may serve only a team’s KPI, any team’s, since a role is held across teams (400 role_kpi_serves_non_team otherwise); leave servesKpiId out for one that serves none. The response is the role's KPIs after the change.
| Field | Type | Required | Description |
|---|---|---|---|
roleId |
string | yes | The role the KPI belongs to. |
name |
string | yes | What is measured, up to 200 characters. |
targetValue |
number | no | The target, in the KPI’s own unit. Set it with targetDirection, or leave both out for no target. |
targetDirection |
string, one of at_least, at_most |
no | at_least when higher is better, at_most when lower is better. |
amberBand |
number, at least 0 | no | How far past the target still reads AMBER rather than RED. |
onTargetWorseningRule |
boolean | no | true to read AMBER when on target but worse than the reading before. |
cadenceMinutes |
integer, at least 1 | no | How often it is read, in minutes; a reading older than this is overdue. |
servesKpiId |
string | no | The KPI of the role’s own team this one serves. |
sourceKind |
string, one of task, person |
no | Where readings come from: task (a task records them) or person (entered by hand). |
sourceRef |
string | no | The task id, or the person’s human-user id, sourceKind names. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. Every call adds a KPI to the role, so a repeat proposes a second one.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
POST /v1/roles/:roleId/kpis(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
roleId names no role in this enterprise, another enterprise's included. |
Tool error |
role_kpi_serves_non_team |
servesKpiId names a KPI that is not a team’s: the company’s, a role’s or a task’s. |
Tool error |
role.edit_kpi
Change a role KPI's fields; a signed-off one only a person changes.
What the model reads:
Change a role KPI's fields; the ones left out keep their value. A KPI a person has signed off is changed only by a person, so this is refused with 403 kpi_signed_off_person_only for it. The response is the role's KPIs after the change.
| Field | Type | Required | Description |
|---|---|---|---|
roleId |
string | yes | The role the KPI belongs to. |
name |
string | no | What is measured, up to 200 characters. |
targetValue |
number | no | The target, in the KPI’s own unit. Set it with targetDirection, or leave both out for no target. |
targetDirection |
string, one of at_least, at_most |
no | at_least when higher is better, at_most when lower is better. |
amberBand |
number, at least 0 | no | How far past the target still reads AMBER rather than RED. |
onTargetWorseningRule |
boolean | no | true to read AMBER when on target but worse than the reading before. |
cadenceMinutes |
integer, at least 1 | no | How often it is read, in minutes; a reading older than this is overdue. |
servesKpiId |
string | no | The KPI of the role’s own team this one serves. |
sourceKind |
string, one of task, person |
no | Where readings come from: task (a task records them) or person (entered by hand). |
sourceRef |
string | no | The task id, or the person’s human-user id, sourceKind names. |
kpiId |
string | yes | The KPI to change. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same fields set twice leave the KPI as the first call did.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PATCH /v1/roles/:roleId/kpis/:kpiId(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
roleId names no role in this enterprise, another enterprise's included. |
Tool error |
role_kpi_not_found |
kpiId names no KPI still on this role. |
Tool error |
role_kpi_serves_non_team |
servesKpiId names a KPI that is not a team’s: the company’s, a role’s or a task’s. |
Tool error |
kpi_signed_off_person_only |
A person has signed the KPI off, so only a person may change it. | Tool error |
os.inspect_enterprise
A snapshot of the company: teams, members, roles, and the tasks of the roles each member holds.
What the model reads:
Read the company as it is now: every team (id, name, slug) and every member (id, name, email, persona, roles), with each member’s tasks: every task of a role they hold, whatever team they sit on (not OS tasks). The same snapshot as os.directory. Use this to name who owns what before you assign, route or escalate work. Read-only; pass no arguments.
No declared fields: the schema accepts any object.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Returns:
{ teams, members }: each team's id, name and slug, and each member's id, name, email, persona, roles, and every task of a role they hold, whatever team they sit on (not OS tasks). - API:
POST /v1/runs/self/tools/os.inspect_enterprise(run:self)
os.directory
Teams, members, roles, and the tasks of the roles each member holds: who to offload work to.
What the model reads:
List teams, members, roles, and each member’s tasks: every task of a role they hold, whatever team they sit on (not OS tasks). Use this to find someone to offload work to.
No declared fields: the schema accepts any object.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the CEO chat, the API.
- Returns:
{ teams, members }: each team's id, name and slug, and each member's id, name, email, persona, roles, and every task of a role they hold, whatever team they sit on (not OS tasks). The same snapshot asos.inspect_enterprise. - API:
POST /v1/runs/self/tools/os.directory(run:self)
os.list_blockers
What has stopped: failed, stalled, blocked and spend-paused runs, and stopped pipelines, with who owns each.
What the model reads:
What is stopping work right now, as the Blockers page shows it: failed runs not yet cleared (one page, with failedTotal counting them all), stalled, blocked and spend-paused runs, stopped pipelines, missing model tiers, exhausted LLM capacity, task definition problems, and teams with no lead, no metric or an overdue retro. Read-only: nothing is retried or cleared. Waiting gates are not here; use os.list_open_gates.
| Field | Type | Required | Description |
|---|---|---|---|
failedPage |
integer, at least 1 | no | The page of failed runs to read, from 1. Defaults to 1. A page past the last reads the last. |
pageSize |
integer, 1 to 100 | no | Failed runs per page, up to 100. Defaults to 100 in a run, and to 20 over the API. |
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: What the portal shows as blockers. To a run:
runs, each stopped run once, oldest first, withrunId, thesectionsit is listed in (failed, stopped, blocked, stalled, paused),status,reason,blockClass, itstask,team, teamleadandassignee, therepo,issueandprfrom its input,since,taskRetries(how many times tasks have retried its chain) andescalation(to whom,toYou, the note, when) once someone escalated it; thenfailedTotal(every uncleared failed run), thefailedPageread and itspageSize, the team-health rows (missingLead,overdueRetro, andkpiHealth: a KPI that needs attention, with itscondition(no_key_kpi,no_target,overdueorlight),team,kpi,layer,light,trendandowner),spendEnabledanddraining. Over the API: the portal rows as they are. Waiting gates are not here: read them withos.list_open_gates. - API:
GET /v1/blockers(blockers:read)
os.list_open_gates
Every gate waiting on a decision, oldest first: the CEO inbox's own rows.
What the model reads:
Every gate waiting on a decision, oldest first: the run and task it belongs to, the tool call it holds (toolName, payload), its summary when the run wrote one, who owns the decision, when it times out, and whether the run can be sent back with changes requested. Read-only: deciding a gate is not a tool here.
Takes no arguments: no 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: Each waiting gate:
runId,taskSlug,toolName,owner,payload,summary(when the run wrote one),createdAtand its age. - API:
GET /v1/gates?status=waiting(gates:read)
os.list_waiting
Open work nothing is working on: no live or queued run, no waiting decision, not on Blockers, not finished.
What the model reads:
Every piece of open work nothing is working on, as the Waiting list shows it: one row per issue, pull request or work item whose last run has ended, with no live or queued run, no decision waiting and nothing on Blockers, that is not finished: its last run did not end on an outcome its task declares as finishing the work, nobody has marked it finished, and no person cancelled its last run. Work stays listed however old it is. Read-only: nothing is restarted or finished. Pass no arguments.
Takes no arguments: no 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:
{ rows, total }, longest waiting first. Each row:pipeline(owner/name#<number>for an issue or pull request,work:<id>for a work item),repoandnumber(null for a work item),workItemandworkItemTitle(the item and its title; null for an issue or pull request), the newestrunIdand itstaskId,endedAs(how that run ended:succeeded,failed,cancelled, ordecision_rejected), thereasonit gave and what the workwaitsOn(each null when it named none),since(when it ended) andwaitedMs.totalis the number of rows. - API:
GET /v1/waiting(runs:read)
os.retry_run
Start a stopped run again, with the same input, so its work moves.
What the model reads:
Retry one stopped run: start a fresh run of the same task with the same input. Only a run on Blockers: failed, blocked, or finished on an outcome nothing follows, and not already cleared or retried. Pass runId and note (one line on why another run should get through, recorded on the run). Tasks may retry one chain 3 times; past that, escalate it.
| Field | Type | Required | Description |
|---|---|---|---|
runId |
string | yes | The run id, as os.list_blockers names it |
note |
string | yes | Why another run should get through, in one line |
No other fields are accepted.
- Effect: write.
- Side effects: Starts a paid run of the stopped run's task. A blocked run is cancelled as it is retried, and the issue it works is marked in flight again.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the tool call: the same call sent twice starts one run. A retried run is refused afterwards, so a later call starts nothing either.
- Called by: a run, the API.
- Returns:
{ runId, retryRunId, status, taskRetries }: the new run,queued, orpendingwhile its task or member is busy, and how many times tasks have now retried the chain. - API:
POST /v1/runs/self/tools/os.retry_run(run:self)
| Error | When | What happens |
|---|---|---|
run_id_required |
runId is missing. |
Tool error |
note_required |
note is missing or empty. |
Tool error |
run_not_found |
No run with that id in this enterprise. | Tool error |
own_run |
The run named is the one calling. | Tool error |
not_stopped:<status> |
The run is not on Blockers: it was cancelled, it finished on an outcome its task follows, or (to retry or clear) it is still active. A stalled or spend-paused run can only be escalated. | Tool error |
already_retried |
A later run already retried or routed it. Act on that run instead. | Tool error |
already_cleared |
Someone already cleared it. | Tool error |
retry_limit_reached |
Tasks have already retried this chain 3 times. | Tool error |
task_not_runnable |
The run's task is deprecated, has no current version, or has nobody to run it. Escalate it instead. | Tool error |
Example:
{
"runId": "5f0c1d2e-0000-4000-8000-000000000001",
"note": "Ran out of steps after pushing most of the change; the next run continues from the branch"
}
os.route_run
Send a stopped run's work to another task of its pipeline, instead of running the same task again.
What the model reads:
Route one stopped run: start a run of another task of its pipeline with the same input, in the same execution, when running the same task again would stop the same way. The task is one that already ran on the run's issue or pull request (send it back to an earlier stage), or one the stopped run's task names as a successor (move it on past this stage). Only a run on Blockers, as for os.retry_run. Pass runId, task (the slug to run next) and note (what that task should do, and why; the new run reads it as routedFrom in its input). Routes and retries share one limit: tasks may retry or route one chain 3 times; past that, escalate it.
| Field | Type | Required | Description |
|---|---|---|---|
runId |
string | yes | The run id, as os.list_blockers names it |
task |
string | yes | The slug of the task to run next |
note |
string | yes | What that task should do with it, and why, in a line or two |
No other fields are accepted.
- Effect: write.
- Side effects: Starts a paid run of the task named. A blocked run is cancelled as it is routed, and the issue it works is marked in flight again.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the tool call: the same call sent twice starts one run. A routed run is refused afterwards, so a later call starts nothing either.
- Called by: a run, the API.
- Returns:
{ runId, routedRunId, task, status, taskRetries }: the new run,queued, orpendingwhile its task or member is busy, and how many times tasks have now retried or routed the chain. - API:
POST /v1/runs/self/tools/os.route_run(run:self)
| Error | When | What happens |
|---|---|---|
run_id_required |
runId is missing. |
Tool error |
note_required |
note is missing or empty. |
Tool error |
run_not_found |
No run with that id in this enterprise. | Tool error |
own_run |
The run named is the one calling. | Tool error |
not_stopped:<status> |
The run is not on Blockers: it was cancelled, it finished on an outcome its task follows, or (to retry or clear) it is still active. A stalled or spend-paused run can only be escalated. | Tool error |
already_retried |
A later run already retried or routed it. Act on that run instead. | Tool error |
already_cleared |
Someone already cleared it. | Tool error |
task_required |
task is missing. |
Tool error |
same_task |
task is the stopped run's own task. |
Tool error |
task_not_in_pipeline |
No run of that task is on the run's issue or pull request, and its task names no such successor. | Tool error |
retry_limit_reached |
Tasks have already retried or routed this chain 3 times. | Tool error |
task_not_runnable |
The task named is deprecated, has no current version, or has nobody to run it. Escalate it instead. | Tool error |
Example:
{
"runId": "5f0c1d2e-0000-4000-8000-000000000004",
"task": "write-red-suite",
"note": "The locked tests never cover the last acceptance criterion; add them, then implement runs on"
}
os.clear_run
Take a stopped run off Blockers without running it again.
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 or merged, or it is a leftover of a wait someone already ended. A failed run, or one that finished on an outcome nothing follows, is cleared; a blocked run is cancelled. Pass runId and note (why nothing more is needed, recorded on the run). To clear a stale repair escalation after a route, pass replacement with sourceRunId and acceptedRunId: the API verifies the tenant-scoped route audit, original lineage and priorRunId before clearing. A preview alone is refused. 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 |
replacement |
object | no | Accepted replacement evidence when clearing a stale repair escalation after routing. |
replacement.sourceRunId |
string | yes | The original source run that was routed. |
replacement.acceptedRunId |
string | yes | The accepted routed run, never a preview. |
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. The same call sent twice clears once. A cleared run is refused afterwards.
- Called by: a run, the API.
- Returns:
{ runId, status, cleared }: the run as it now stands. - API:
POST /v1/runs/self/tools/os.clear_run(run:self)
| Error | When | What happens |
|---|---|---|
run_id_required |
runId is missing. |
Tool error |
note_required |
note is missing or empty. |
Tool error |
run_not_found |
No run with that id in this enterprise. | Tool error |
own_run |
The run named is the one calling. | Tool error |
not_stopped:<status> |
The run is not on Blockers: it was cancelled, it finished on an outcome its task follows, or (to retry or clear) it is still active. A stalled or spend-paused run can only be escalated. | Tool error |
already_retried |
A later run already retried or routed it. Act on that run instead. | Tool error |
already_cleared |
Someone already cleared it. | Tool error |
replacement_not_accepted |
The named replacement has no verified route acceptance with the source lineage and priorRunId. | Tool error |
invalid_work_item_state |
workItemState is not held, ready, done or dropped. | Tool error |
Example:
{
"runId": "5f0c1d2e-0000-4000-8000-000000000002",
"note": "The pull request merged by hand on 28 Sep",
"workItemState": "done"
}
os.escalate_run
Hand a stopped run to its team lead, or to the CEO, and record that you did.
What the model reads:
Hand one stopped run to someone who can decide it, and record it on the run so nobody hands it on twice. to: lead (the lead of the first of the running member's teams led by someone else, or the COO where there is none; they own the decision from then on) or ceo (record it before you put the question to the CEO with os.ask_ceo). Pass runId, to and note (what is stuck, what was tried, and the move you recommend). os.list_blockers shows the escalation on the row from then on.
| Field | Type | Required | Description |
|---|---|---|---|
runId |
string | yes | The run id, as os.list_blockers names it |
to |
string, one of lead, ceo |
yes | |
note |
string | yes | What is stuck, what was tried, and the move you recommend |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Escalating a run again to the same person records nothing new.
- Called by: a run, the API.
- Returns:
{ runId, to, memberId, memberName, alreadyEscalated }: who now owns the decision.alreadyEscalatedis true when the run was already escalated to them, and nothing new is recorded. - API:
POST /v1/runs/self/tools/os.escalate_run(run:self)
| Error | When | What happens |
|---|---|---|
run_id_required |
runId is missing. |
Tool error |
note_required |
note is missing or empty. |
Tool error |
run_not_found |
No run with that id in this enterprise. | Tool error |
own_run |
The run named is the one calling. | Tool error |
not_stopped:<status> |
The run is not on Blockers: it was cancelled, it finished on an outcome its task follows, or (to retry or clear) it is still active. A stalled or spend-paused run can only be escalated. | Tool error |
already_retried |
A later run already retried or routed it. Act on that run instead. | Tool error |
already_cleared |
Someone already cleared it. | Tool error |
to_invalid |
to is not lead or ceo. |
Tool error |
no_lead |
None of the running member's teams has a lead other than that member (or they sit on no team), and nobody holds the COO role to act as lead. | Tool error |
Example:
{
"runId": "5f0c1d2e-0000-4000-8000-000000000003",
"to": "lead",
"note": "Loop cap on recover-red-suite (2/2): each lap found the same failing test outside the issue. Recommend closing the loop and filing the test separately."
}
os.read_enterprise
The whole enterprise: teams, charters, roles, members and every task in full.
What the model reads:
Read the whole enterprise a plan is proposed against: every team with its charter, roles and members (persona and roles), the members on no team, and every task, OS-owned ones included, in full: goal, metric, guardrails, tools, gates, spend, successors, finishesOn (the outcomes a run ends on that finish its work), its assigneeRole and the members holding it (roleHolderIds; assigneeMemberId when exactly one does), teamIds (the teams that inherit it: each team where a member holds its role, seated or as lead), and lastRunStatus. A task is assigned to a role, never pinned to a member and never placed on a team: a team runs the tasks of the roles its members hold. With no arguments it returns everything. When that is too big to hand back (tool_result_truncated), read it in slices, each with its tasks in full: noTeam: true for the members on no team and the tasks whose role no team holds (OS-owned tasks among them), then team (a team id or slug) for each team, with its roles, members and the tasks of the roles its members hold. A task whose role is held on several teams is in each of their slices. When one team is too big, read it role by role: team with role (a role id or slug from allRoles in that team slice) for its tasks that run as that role, and team with noRole: true for its tasks that run as no role. Every slice lists allTeams, the id and slug of every team; every team slice also lists allRoles, every role its tasks can run as. Together the slices cover every member and task. OS-owned tasks only.
| Field | Type | Required | Description |
|---|---|---|---|
team |
string | no | A team id or slug: that team, its roles, members and the tasks of the roles its members hold. |
noTeam |
boolean | no | true: the members on no team and the tasks whose role no team holds. |
role |
string | no | With team only. A role id or slug from allRoles: that team's tasks that run as it. |
noRole |
boolean | no | With team only. true: that team's tasks that run as no role. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.read_enterprise(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
team_not_found:<team> |
No team in this enterprise has that id or slug. Read allTeams with noTeam: true. | Tool error |
team_selector_conflict |
Both team and noTeam are set. |
Tool error |
role_requires_team |
role or noRole is set without team: they narrow one team. |
Tool error |
role_not_found:<role> |
No task on that team can run as a role with that id or slug. The message lists the team's allRoles. | Tool error |
role_selector_conflict |
Both role and noRole are set. |
Tool error |
Example:
{}
Example:
{
"noTeam": true
}
Example:
{
"team": "engineering"
}
Example:
{
"team": "engineering",
"role": "cto"
}
Example:
{
"team": "engineering",
"noRole": true
}
os.search_catalog
Published catalog tasks that match a plain-English intent, best first.
What the model reads:
Find published catalog tasks that match a plain-English intent, best match first (at most 10), so a plan proposes something proven instead of inventing it. Scored on the words of the intent found in a task slug or name; an intent of only filler words matches nothing. Pass intent.
| Field | Type | Required | Description |
|---|---|---|---|
intent |
string | yes |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.search_catalog(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
Example:
{
"intent": "Triage a new GitHub issue"
}
os.list_tool_bindings
The tool types this enterprise has bound, at which layer, and the tools each exposes.
What the model reads:
List the tool types this enterprise has bound, the layer each is bound at, and the individual tools each one exposes, asked of its MCP server. A proposal may only name tools of a bound type. A server that will not answer lists no tools, and its binding is still reported.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Needs:
- Each binding's own credential, to ask its server which tools it exposes.
- API:
POST /v1/runs/self/tools/os.list_tool_bindings(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
Example:
{}
os.list_built_in_tools
Every built-in tool a run can call, with its summary and whether it reads or writes.
What the model reads:
List every built-in tool a run can call: its name, a one-line summary, and its effect (read or write). A task may declare a built-in tool (os.*, workspace.*, memory.*, web.*) only from this list: saving a task that names any other is refused, as a tool that does not exist (tool_unknown) or one only the CEO chat offers (tool_not_run_callable). A row with gate is a tool a task may hold only if it also declares a CEO gate on the tool gate names: saving it without that gate is refused (gate_required_for_tool). Vendor tools are not here: os.list_tool_bindings lists what the enterprise has bound. Takes no arguments.
Takes no arguments: no 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:
[{ name, summary, effect, gate? }]: one row per built-in tool a run can call, in reference order.gateis only on a tool a task may hold only with a CEO gate, and names the tool that gate is declared on. - API:
GET /v1/tools/built-in?callable=run(tools:read)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
Example:
{}
os.read_task
One task in full, its pending recommendations, and the tasks that start it.
What the model reads:
One task in full (as os.read_enterprise reads a task), the improvement recommendations still pending against it, and incomingSuccessors: the tasks whose successors start it. Its own successors are what it starts. The task also carries currentVersionId, the version this read is of: an update_task item you write from it names that as its baseVersionId. Pass taskId.
| Field | Type | Required | Description |
|---|---|---|---|
taskId |
string | yes |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.read_task(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
task_id_required |
taskId is missing. |
Tool error |
task_not_found |
No task in this enterprise has that id. | Tool error |
Example:
{
"taskId": "5f0c1d2e-0000-4000-8000-000000000001"
}
os.assess_impact
What points at a role, team, task or member a plan would delete.
What the model reads:
What points at a role, team, task or member a plan would delete. role: the members holding it and the tasks assigned to it. team: the roles held on it and the members on it; the tasks it runs belong to those roles and stay with their holders, so only its roster stands in the way of deleting it. task: the tasks whose successors name it and its runs in flight. member: the roles they hold, the teams they sit on and the tasks their roles run. Reported, never refused: the plan says what the deletion breaks. Pass kind and id.
| Field | Type | Required | Description |
|---|---|---|---|
kind |
string, one of role, team, task, member |
yes | |
id |
string | yes |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.assess_impact(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
id_required |
id is missing. |
Tool error |
kind_invalid |
kind is not role, team, task or member. |
Tool error |
Example:
{
"kind": "role",
"id": "5f0c1d2e-0000-4000-8000-000000000002"
}
os.write_plan
Write or replace this conversation's plan, checked before the CEO sees it.
What the model reads:
Write this conversation's plan for the CEO, or replace it: one plan per conversation, and a replace carries the version os.read_plan returned. The conversation is the chatSessionId you pass when you have one, else the planKey in your run's input, which the OS fills with the first proposing run's id and every later round carries, so you never pass planKey yourself. Every item is checked first, and the first problem comes back as the reason: a tool whose type this enterprise has not bound, a slug it already has, a task pinned to a member (set assigneeRole), a task placed on a team (a task belongs to a role: drop teamId and teamHandle and seat a holder of its role on the team instead), a task whose role nobody holds and no item in the plan gives to anyone, a task definition a saved task would fail, or an update_task item whose task has moved on from the version it names. An update_task item names the version it was written from as baseVersionId: the currentVersionId os.read_task returned. One that names none is given the version current as the plan is written. Fix it and write again. Pass summary, ceoIntent, kind (default os_change), items, the chatSessionId from your input when you have one and, to replace, version.
| Field | Type | Required | Description |
|---|---|---|---|
chatSessionId |
string | no | |
summary |
string | yes | |
ceoIntent |
string | no | |
kind |
string | no | |
items |
array of object | yes | |
version |
integer, at least 1 | no |
No other fields are accepted.
- Effect: write.
- Side effects: Moves the plan to
awaiting_ceo. - Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat replaces the same plan with the same content rather than adding a second. A repeat carrying a version the plan has moved past is refused as
plan_version_conflict. - Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.write_plan(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
plan_key_required |
No chatSessionId was passed and the run carries no planKey in its input, so the plan has no conversation to belong to. |
Tool error |
summary_required |
summary is missing. |
Tool error |
plan_payload_invalid |
An item is not one the plan can apply (a missing handle, an unknown type). | Tool error |
tool_type_not_bound:<type> |
An item names a tool whose type this enterprise has not bound. | Tool error |
slug_collision:<slug> |
An item creates a task, role or team with a slug the enterprise already has. | Tool error |
assignee_member_removed |
A create_task item names assigneeMemberId. A task is assigned to a role: set assigneeRole. |
Tool error |
task_team_removed:<slug> |
A create_task or update_task item names teamId or teamHandle. A task belongs to a role, not a team: a team runs the tasks of the roles its members hold. Seat a holder of the task’s role on the team instead. |
Tool error |
role_unplaced:<role> |
A task runs as a role nobody holds, and no item in the plan creates a member who holds it, so it would never start. | Tool error |
definition_issue:<code> |
A proposed task fails the check a saved task must pass (an unknown successor, a deterministic task with tools). | Tool error |
plan_version_conflict |
version is not the version the plan is at now. Read it back with os.read_plan and write again. |
Tool error |
task_version_conflict |
An update_task item's baseVersionId is not its task's current version: someone published since you read it. The reason names the current version. Read the task again with os.read_task and write the change against that. |
Tool error |
Example:
{
"chatSessionId": "chat-42",
"ceoIntent": "Hire a support lead",
"summary": "Creates a Support Lead role",
"kind": "os_change",
"items": [
{
"type": "create_role",
"handle": "r1",
"slug": "support-lead",
"name": "Support Lead"
}
]
}
os.read_plan
This conversation's plan as it stands, with its version.
What the model reads:
Read this conversation's plan as it stands, with the version a replacing os.write_plan must carry, so a feedback round continues it rather than starting again. The conversation is the chatSessionId you pass when you have one, else the planKey in your run's input, which every round of the conversation carries. Null when the conversation has no plan. With neither, the plan this run wrote.
| Field | Type | Required | Description |
|---|---|---|---|
chatSessionId |
string | no |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- API:
POST /v1/runs/self/tools/os.read_plan(run:self)
| Error | When | What happens |
|---|---|---|
os_owned_only |
The run's task is not OS-owned. These tools read every team's work, so only an OS task may call them. | Tool error |
Example:
{
"chatSessionId": "chat-42"
}
os.chat_list
List chat threads, most recently active first: who each is with, its state and its last message.
What the model reads:
List chat threads, most recently active first: each thread’s id, its state (idle, replying or closed), and its last message. In a run these are the enterprise owner’s threads with the member doing the run, the ones the OS files into: never another person’s private chats, and memberId is ignored. Over the API they are the threads you own, or only one member’s when you pass memberId. No message bodies beyond the last: read a thread with os.chat_read. A conversation opened for one job, such as designing a task, is never listed.
| Field | Type | Required | Description |
|---|---|---|---|
memberId |
string | no | Over the API: only threads with this member. A run always lists its own member’s. |
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.
- Needs:
- In a run, the run's assigned member: the threads are always theirs, and an OS-owned task has none. Over the API and the MCP server, any thread of the enterprise the token can reach.
- Returns: To a run:
{ threads }, each withid,status(idle,replyingorclosed),lastMessage(role,content,createdAt, or null in an empty thread),lastReadAt(when a person last opened it, or null),createdAtandupdatedAt. Over the API: the Chat page’s rows as they are, which add thememberand theunreadandunreadCountof the person’s side. - API:
GET /v1/chats(chats:read)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
A run with no assigned member called it, so there is no thread. | Tool error |
Example:
{}
os.chat_read
Read one chat thread: its messages, oldest first.
What the model reads:
Read one chat thread: its messages, oldest first, each with who wrote it. Pass id from os.chat_list, and optionally limit to read only the newest messages (up to 200). In a run you get what was said (people’s messages and the member’s), the newest 50 unless you pass limit, in one of the threads os.chat_list shows you, and reading does not mark the thread read. Over the API you get every row, tool calls included, in a thread you own or reach by its link, and reading marks it read for its owner, as opening it in the portal does.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | A thread id from os.chat_list |
limit |
integer, 1 to 200 | no | Only the newest messages, up to 200. In a run it defaults to 50; over the API, to all of them. |
No other fields are accepted.
- Effect: read.
- Side effects: Over the API and the MCP server, marks the thread read, the same as opening it in the portal. In a run, nothing.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API, the CEO chat, the OS MCP server.
- Needs:
- In a run, the run's assigned member: the threads are always theirs, and an OS-owned task has none. Over the API and the MCP server, any thread of the enterprise the token can reach.
- Returns: To a run:
{ id, status, total, messages }, wheretotalcounts every message said in the thread and each message hasid,role(userfor a person or an API token,assistantfor the member),content,sender(the name of whoever wrote ausermessage, else null) andcreatedAt. Over the API: the thread as the portal reads it, with itsmemberand every row, each with itssender. - API:
GET /v1/chats/:id(chats:read)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
A run with no assigned member called it, so there is no thread. | Tool error |
chat_not_found |
No thread has that id: in a run, including another member's thread, another person's, and a conversation opened for one job. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021",
"limit": 20
}
os.chat_write
Write one message in a chat thread, as yourself.
What the model reads:
Write one message in a chat thread, as yourself. Pass content: Markdown. In a run you write as the member doing the run, for the enterprise’s people to read, and it is drawn as the member’s formatted text: paragraphs with their line breaks kept, bulleted and numbered lists, bold, and links, written [text](https://…) or as a bare web address. It shows as unread until someone opens the thread, nobody replies to the run, and the run carries on. Leave id out to write in the enterprise owner’s open thread with the member (one the owner owns is opened if there is none), or pass id from os.chat_list. At most 4000 characters in a run. For a question you need answered, use os.ask_ceo. Over the API, id is required, you write as the person or token calling, shown as you typed it with web addresses linked, and the member replies: the response is the thread with that reply in it. Sends no mail and opens no gate. A repeat writes the message again.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | no | The thread, from os.chat_list. A run may leave it out to write in the enterprise owner’s open thread with its member. Required over the API. |
content |
string | yes | The message, as Markdown |
No other fields are accepted.
- Effect: write.
- Side effects: In a run, one message from the member in the thread. Over the API, one message from the caller and a reply turn by the member, which spends on the enterprise’s model keys.
- Retry: Not retry-safe: a repeat acts again. A repeat writes the message again: call it once for each thing you have to say.
- Called by: a run, the API, the CEO chat, the OS MCP server.
- Needs:
- In a run, the run's assigned member: the threads are always theirs, and an OS-owned task has none. Over the API and the MCP server, any thread of the enterprise the token can reach.
- Returns: To a run:
{ written: true, id, messageId }, the thread it went in and the message. Over the API: the thread as os.chat_read returns it, with the member’s reply. - API:
POST /v1/chats/:id/messages(chats:write)
| Error | When | What happens |
|---|---|---|
no_assigned_member |
A run with no assigned member called it, so there is no thread. | Tool error |
chat_not_found |
No thread has that id: in a run, including another member's thread, another person's, and a conversation opened for one job. | Tool error |
empty_message |
content is missing, not text, or blank. |
Tool error |
message_too_long |
In a run, content is longer than 4000 characters. |
Tool error |
chat_closed |
The thread is closed. | Tool error |
chat_replying |
Over the API, the member is still replying to an earlier message in the thread. | Tool error |
Example:
{
"content": "New enquiry\nFrom: [email protected]\nAsking about: the Team plan"
}
Example, Over the API: a person’s message to the member, answered in the response.:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021",
"content": "Where did last week’s report go?"
}
os.chat_open
Open a new chat thread with a member.
What the model reads:
Open a new, empty chat thread with a member, and get its id to write in with os.chat_write. Pass memberId. Nothing is said and nothing is spent until a message is written. A run cannot call it: a run’s os.chat_write opens its member’s thread when there is none.
| Field | Type | Required | Description |
|---|---|---|---|
memberId |
string | yes | The member to talk to |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat opens another thread with the same member.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The new thread: its
id,memberId,status(idle) and times. - API:
POST /v1/chats(chats:write)
| Error | When | What happens |
|---|---|---|
memberId_required |
memberId is missing. |
Tool error |
member_not_found |
No member of this enterprise has that id. | Tool error |
Example:
{
"memberId": "5f0c1d2e-0000-4000-8000-000000000007"
}
os.list_roles
The enterprise's roles, by slug.
What the model reads:
List the enterprise's roles, ordered by slug: each one's id, name and slug. A role is a job across the enterprise, held by members on any team; it belongs to no team. No arguments. Never another enterprise's roles.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: One row per role, each with
id,nameandslug. - API:
GET /v1/roles(roles:read)
Example:
{}
os.read_role
One role, with the members who hold it and the tasks that run as it.
What the model reads:
Read one role: its name and slug, the members who hold it (members), the teams those members sit on (teams, each with its holders), and the tasks that run as it (tasks). Not found for a role in another enterprise.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role:
id,name,slug,members(who holds it),teams(where it is held, each with its holders) andtasks(what runs as it). - API:
GET /v1/roles/:id(roles:read)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011"
}
os.create_role
Create a role.
What the model reads:
Create a role with a name and, optionally, a slug. A slug left out is made from the name. A slug, or a name with no slug, another role already has is refused with role_slug_taken. A role belongs to no team: it is held by members, every holder runs the role’s tasks on whatever team they sit, and a team runs the tasks of the roles its members hold. The response is the role as created.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The role’s name, up to 200 characters. |
slug |
string | no | The role’s slug, unique in the enterprise. Made from the name when left out. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. Every call creates a role. A repeat with the same slug is refused (role_slug_taken) rather than creating a second.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role as created:
id,name,slug,members,teamsandtasks. - API:
POST /v1/roles(roles:write)
| Error | When | What happens |
|---|---|---|
role_slug_taken |
Another role in this enterprise already has that slug. A role given no slug takes one made from its name, so a name already taken is refused this way too. | Tool error |
Example:
{
"name": "Support lead"
}
os.update_role
Change a role's name or slug.
What the model reads:
Change a role's name or slug; a field left out keeps its value. A slug another role already has is refused with role_slug_taken. The response is the role after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
name |
string | no | The role’s new name, up to 200 characters. |
slug |
string | no | The role’s new slug, unique in the enterprise. A task names its role by this slug. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same fields set twice leave the role as the first call did.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role after the change:
id,name,slug,members,teamsandtasks. - API:
PATCH /v1/roles/:id(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
role_slug_taken |
Another role in this enterprise already has that slug. A role given no slug takes one made from its name, so a name already taken is refused this way too. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011",
"name": "Support head"
}
os.delete_role
Remove a role nobody holds and no task runs as.
What the model reads:
Remove a role. A role a member still holds, or a task still runs as, is refused with role_has_dependents, naming each: take them off it first. The call is the confirmation, so the tool takes no confirm argument.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds the role already gone and is refused with role_not_found, removing nothing else.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: Nothing: the role is gone.
- API:
DELETE /v1/roles/:id?confirm=true(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
role_has_dependents |
A member still holds the role or a task still runs as it. The refusal names each. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011"
}
os.add_role_task
Give a role a task: the task runs as that role.
What the model reads:
Give a role a task: the task runs as this role from now on, in place of any role it ran as before. The response is the role after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
taskId |
string | yes | The task that runs as the role. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A task already on the role stays on it once.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role after the change, with the task among its
tasks. - API:
POST /v1/roles/:id/tasks(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
task_not_found |
taskId names no task in this enterprise. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011",
"taskId": "5f0c1d2e-0000-4000-8000-000000000013"
}
os.remove_role_task
Take a task away from a role.
What the model reads:
Take a task away from a role: the task runs as no role until it is given one. A task that does not run as this role is refused with task_not_on_role. The response is the role after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
taskId |
string | yes | The task to take off the role. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds the task already off the role and is refused with task_not_on_role, changing nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role after the change, without the task among its
tasks. - API:
DELETE /v1/roles/:id/tasks/:taskId(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
task_not_found |
taskId names no task in this enterprise. |
Tool error |
task_not_on_role |
The task does not run as this role. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011",
"taskId": "5f0c1d2e-0000-4000-8000-000000000013"
}
os.add_role_member
Give a role a member: the member holds it.
What the model reads:
Give a role a member: the member holds the role from now on. The response is the role after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
memberId |
string | yes | The member who holds the role. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A member who already holds the role holds it once.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role after the change, with the member among its
members. - API:
POST /v1/roles/:id/members(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
member_not_found |
memberId names no member in this enterprise. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011",
"memberId": "5f0c1d2e-0000-4000-8000-000000000014"
}
os.remove_role_member
Take a member away from a role.
What the model reads:
Take a member away from a role: the member no longer holds it. The response is the role after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The role, by its id from os.list_roles. |
memberId |
string | yes | The member to take off the role. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A member who no longer holds the role stays off it.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The role after the change, without the member among its
members. - API:
DELETE /v1/roles/:id/members/:memberId(roles:write)
| Error | When | What happens |
|---|---|---|
role_not_found |
id names no role in this enterprise, another enterprise's included. |
Tool error |
member_not_found |
memberId names no member in this enterprise. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000011",
"memberId": "5f0c1d2e-0000-4000-8000-000000000014"
}
os.list_task_definitions
The enterprise's tasks, built-in ones included, a page at a time, each marked builtIn.
What the model reads:
List the enterprise's tasks, a page at a time: the ones it wrote or copied, and the OS's built-in tasks every enterprise runs. Each row carries its id, slug, name, kind, status, origin, builtIn (true for a shared built-in definition, false for one of the enterprise’s own), its role and the teams that inherit it (teams: the teams where a member holds that role), currentVersionId and currentVersion (its version number and declared fields). Narrow it with search (slug, name or role), kind, status, origin, teamId, assigneeRole, memberId, name or slug, and sort it by slug, name, kind, status, createdAt or updatedAt. Read one task in full, its skill text included, with os.read_task_definition. The response is { data, total, page, limit, pages }. Never another enterprise's tasks.
| Field | Type | Required | Description |
|---|---|---|---|
search |
string | no | Only tasks whose slug, name or role contains this text. |
kind |
string, one of llm, deterministic |
no | Only tasks of this kind. |
status |
string, one of active, deprecated |
no | Only tasks in this status. |
origin |
string, one of tenant, os |
no | tenant for the enterprise’s own tasks, os for the built-in ones. |
teamId |
string | no | Only the tasks of the roles held on this team, by a seated member or its lead. |
assigneeRole |
string | no | Only the tasks that run as this role, by its slug. |
memberId |
string | no | Only the tasks of the roles this member holds in the enterprise. |
name |
string | no | Only tasks whose name contains this text. |
slug |
string | no | Only tasks whose slug contains this text. |
sort |
string, one of slug, name, kind, status, createdAt, updatedAt |
no | The field to sort by. Defaults to slug. |
order |
string, one of asc, desc |
no | The sort direction. Defaults to desc. |
page |
integer, at least 1 | no | The page to read, from 1. Defaults to 1. |
limit |
integer, 1 to 200 | no | Tasks per page, up to 200. Defaults to 25. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns:
{ data, total, page, limit, pages }, each task withid,slug,name,kind,status,origin,builtIn,currentVersionIdandcurrentVersion. - API:
GET /v1/tasks(tasks:read)
Example:
{
"search": "triage",
"origin": "tenant",
"limit": 10
}
os.read_task_definition
One task in full: its skill text, declared fields, version number and current version id.
What the model reads:
Read one of the enterprise's tasks in full, as it is live now: its skill text (skillMd), its current version (currentVersion, with its version number and its declared fields, inputs) and currentVersionId, the identity of that version, which a later change to the task names as the version it builds on, and this enterprise's own values for those inputs (inputValues). It also says whether the task is a shared built-in definition (builtIn), and carries its role, the teams that inherit it (teams: the teams where a member holds that role), its predecessors and successors. Pass id, from os.list_task_definitions. Not found for a task in another enterprise.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task, by its id from os.list_task_definitions. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The task with
builtIn,skillMd,currentVersionIdandcurrentVersion(itsversionnumber and declaredinputs), and what the portal’s task page shows beside them. - API:
GET /v1/tasks/:id(tasks:read)
| Error | When | What happens |
|---|---|---|
task_not_found |
id names no task in this enterprise, another enterprise's included. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000013"
}
os.create_task
Create one of the enterprise’s own tasks.
What the model reads:
Create one of the enterprise’s own tasks. Pass name, goal, metric ({ text }) and skillMd. A slug left out is made from the name. kind defaults to llm, and status and runStatus default to active. Leave gates out and the task is given the default CEO gates; send gates as [] to declare none. A task that declares this tool is refused when it is saved. A task reaches it only through a bound connection to the OS’s own MCP server, with a gate naming the tool, as with every write that server serves. The OS’s built-in tasks are created with a release, never through this tool, and a slug one of them holds is reserved. Give the task to a role with assigneeRole: a task belongs to a role, not a team, and a team runs it by seating a holder of that role. Over this tool the create is refused with definition_issues, and nothing is saved, while the definition carries a routing issue: outcome_not_routed, named with the word (the skill tells a run to end on an outcome that no successor, finishesOn entry or plain success handles), self_loop_unconditional (a successor back to its own slug with no delayMinutes, other than ceo_approved or ceo_changes_requested), or asks_ceo_without_resume (it asks the CEO, does more work after the answer, and has no ceo_approved successor back to its own slug). Fix each and create it again. The response is the task as created, including id and currentVersionId.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The task’s name, trimmed, at most 200 characters. |
slug |
string | no | A slug of letters, digits and hyphens, at most 80 characters. |
kind |
string, one of llm, deterministic |
no | llm or deterministic. A deterministic task has no tools. |
status |
string, one of active, deprecated |
no | active or deprecated. |
assigneeRole |
string | no | The role whose holders run the task, by the role’s slug. A task is given to a role, never a team: every holder of the role runs it, on whatever team they sit, and a team runs the tasks of the roles its members hold. assigneeMemberId is refused. |
goal |
string | yes | What the task is for, in one or two sentences. |
metric |
object | yes | How the task is judged, as { text }. |
guardrails |
array of string | no | Sentences the task must hold to. Each item is plain text. |
tools |
array of string | no | The tools the task may call. Each item is a tool name, as a string, such as "acme.merge_pull_request". An entry that is an object, including one carrying its own gates or marked optional, cannot be sent through this tool: sending tools replaces them all, so leave tools out to keep the current ones. |
inputs |
array of object | no | The inputs, as { key, label, type, required?, configuration?, requiredGroup?, entries? }. type is string, number, boolean, link or file. configuration marks persistent enterprise setup. requiredGroup requires at least one input in the group; every member must agree on configuration. A string map may declare entries: { keyInput, separator }: comma-separated key/value entries must cover the resolved keyInput at each start. Missing required configuration prevents a run from starting. |
gates |
array of object | no | Gates on tools that reach outside. Each object is { tool, owner, approval }. On create, leave it out and the task is given the default CEO gates; on publish, leave it out and the current gates stay. Send [] to declare none, which is refused when a tool still requires a gate. |
spend |
object | no | Spend limits, as { moneyUsdPerRun, maxModelTier, model, maxSteps }. Leave model out, or send "auto", and a model is chosen for each run by what the work needs, no higher than maxModelTier (economical, mid or frontier) when that is set. Send an exact model id as model to use that model for every run. maxSteps is how many steps a run gets, a whole number from 1 to 400; leave it out for the default for the tool shape (24, or 120 with workspace or Computer-Use tools). The run input maxSteps and the operator setting LLM_MAX_STEPS still win over it. |
workspace |
object | no | The clone the task may change, as { branch, onDefaultBranch, writeAllow, rewriteAllow, writeDeny, appendOnly, pushAllow, requireFiles, credentials }. Each list is strings but credentials, which is [{ tool, as, prop? }]: a bound tool's secret (or its custom prop) as the environment variable as of the run's repository commands; onDefaultBranch: true keeps the run on the default branch's tip, with no branch of its own and nothing to push; pushAllow lists the full ref globs (refs/heads/main, refs/tags/v*) a run may push with workspace.git_push's ref besides its own branch, and needs writeAllow. |
successors |
array of object | no | What runs after this task. Each object is { slug, on, when, delayMinutes, maxRunsPerIssue, escalate, verificationAnyOf }. on is succeeded, failed or terminal. |
finishesOn |
array of string | no | Outcome names that finish the work. Each item is plain text, at most 16. |
maxRunsPerExecution |
integer, at least 1 | no | The most countable runs this task may have in one execution before its next start is logged or stopped, a whole number of at least 1. Counted per task across the execution, whichever handoff started each run. Never applied below the highest maxRunsPerIssue on a successor into the task. Left out on create, or never set, EXECUTION_MAX_TASK_RUNS applies; left out on publish, the current value stays. |
toolSlots |
array of object | no | Tool slots the task’s tools may be named by in place of one vendor’s tool type, at most 16. Each object is { key, label, description?, actions? }: key reads like a tool type (codehost), label is what a person choosing a binding reads. A tool named "codehost" or "codehost.<tool>" is then filled per enterprise by the binding that lists codehost among the slots it fills, and runs as that binding’s tool type. actions is a list of { name, description? }, at most 32, the actions the task names under the key ("codehost.pr.merge"); the filling binding maps each to one of its own tools, so the task names no vendor’s tool. |
callLimits |
array of object | no | How often one run may make a call, at most 16. Each object is { tool, match?, perRun }: tool is one tool the task’s tools reach, by its exact name ("acme.issue_write"); match names payload fields the call must carry to count, as a gate’s match does ({ "method": "create" }); perRun is a whole number of at least 1. A call past the limit is not sent, and the run reads call_limit_reached instead. |
mailboxAction |
object | no | Where a mailbox offers this task as a one-click button, as { on, label }. on is mailbox (a button above the mailbox’s list; the run starts with no input of the OS’s) or mail (a button on one open message; the run starts with that message’s id as its emailId input, so the task has to declare an input with that key). label is the button’s words, at most 40 characters. A public template that declares one is offered to clone on inboxes that have no such task yet. Leave it out to offer none. |
skillMd |
string | yes | The skill text, markdown, telling the model how to do the job. |
contextPrefixes |
array of string | no | Key prefixes loaded into input.context when a run starts. Each item is plain text. |
trainGrants |
array of object | no | Team or enterprise notes a run of this task may write. Each object is { layer, eventIdPrefix }, layer team or enterprise. A team note goes to each team the running member sits on or leads. |
overlapPolicy |
string, one of skip, os |
no | skip waits behind the member’s other work. os runs beside it. |
serializeOn |
array of string | no | Input keys that partition this task’s work into lanes, up to 8. Each item is plain text. |
runStatus |
string, one of active, disabled |
no | active, the default, or disabled. disabled keeps runs from starting. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. Every call creates a task. A repeat with the same slug is refused (task_slug_taken) rather than returning the first.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The task as created:
id,slug,currentVersionId,currentVersion,skillMd. - API:
POST /v1/tasks(tasks:write)
| Error | When | What happens |
|---|---|---|
invalid_name |
name is empty, or longer than 200 characters. |
Tool error |
invalid_slug |
The slug is empty once cleaned, or longer than 80 characters. | Tool error |
task_slug_taken |
This enterprise already has a task with that slug. | Tool error |
task_team_removed |
The call names a team for the task. A task belongs to a role, not a team: a team runs the tasks of the roles its members hold. Seat a holder of the task’s role on the team instead. | Tool error |
invalid_task_definition |
The definition fails a check: a deterministic task with tools, a merge or mail or plan gate that is missing, a successor the rules refuse, a call limit on a tool the task does not declare (call_limit_tool_not_declared). | Tool error |
definition_issues |
A create over the OS’s own MCP server whose definition would stop or loop its own pipeline: it carries outcome_not_routed (named with the word), self_loop_unconditional or asks_ceo_without_resume. Nothing is saved, and issues lists each one. | Tool error |
call_limits_invalid |
callLimits is not a list of up to 16 objects. The refusal names the fault instead when one limit is wrong: call_limit_tool_invalid (not one tool by its exact name), call_limit_match_invalid:<tool> (not a gate-shaped match) or call_limit_per_run_invalid:<tool> (not a whole number of at least 1). |
Tool error |
serialize_on_invalid |
serializeOn is not a list of up to 8 input keys. |
Tool error |
tool_entry_unreadable |
A tools entry names no tool. |
Tool error |
llm_model_not_in_catalogue |
spend.model is not a model a connected provider offers. |
Tool error |
os_task_immutable |
The task is one of the OS's own: the same in every enterprise, changed only with a release. | Tool error |
Example:
{
"name": "Triage new issues",
"goal": "Label a new issue and hand it to the right pipeline.",
"metric": {
"text": "Each new issue is labelled or handed on within a day."
},
"skillMd": "# Triage new issues\n\nRead the issue and label it.\n",
"assigneeRole": "engineer"
}
os.publish_task_version
Publish a new version of one of the enterprise’s tasks, naming the version it was read from.
What the model reads:
Publish a new version of one of the enterprise’s tasks. Pass id and baseVersionId, the currentVersionId from os.read_task_definition. Send only the fields that change: a field left out keeps its current value. Sending null does not clear a field through this tool, because a null argument is dropped. Clear inputs, workspace, successors, finishesOn, toolSlots, callLimits, mailboxAction or maxRunsPerExecution over HTTP by sending null. name, slug, assigneeRole, serializeOn, status and kind change the task at once and are not part of the version. A save that changes nothing returns the current version with unchanged true. visibility public publishes the version to the catalog, listed on the task’s role when the enterprise has published that role, and private withdraws it and records the task as left out; either also needs catalog:write. Once the task is in the catalog, every version published after goes there too without visibility; a version the catalog refuses is still saved, and catalogPublication says why the catalog kept its version. A task that declares this tool is refused when it is saved. A task reaches it only through a bound connection to the OS’s own MCP server, with a gate naming the tool, as with every write that server serves, and a run cannot publish the task it is running (self_publish_refused). The OS’s built-in tasks are not edited this way. Give the task to a role with assigneeRole; a task has no team. A version that carries a routing issue is still saved, and definitionIssues lists each as a warning: outcome_not_routed, named with the word (the skill ends on a word no successor or finishesOn entry handles), self_loop_unconditional (a successor back to its own slug with no delayMinutes) or asks_ceo_without_resume (it asks the CEO and works on after the answer with no ceo_approved successor back to itself). The response is the version, and its id is the next baseVersionId.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task, by its id from os.list_task_definitions. |
baseVersionId |
string | yes | The currentVersionId this change was read from. |
name |
string | no | The task’s name, trimmed, at most 200 characters. |
slug |
string | no | A slug of letters, digits and hyphens, at most 80 characters. |
kind |
string, one of llm, deterministic |
no | llm or deterministic. A deterministic task has no tools. |
status |
string, one of active, deprecated |
no | active or deprecated. |
assigneeRole |
string | no | The role whose holders run the task, by the role’s slug. A task is given to a role, never a team: every holder of the role runs it, on whatever team they sit, and a team runs the tasks of the roles its members hold. assigneeMemberId is refused. |
goal |
string | no | What the task is for, in one or two sentences. |
metric |
object | no | How the task is judged, as { text }. |
guardrails |
array of string | no | Sentences the task must hold to. Each item is plain text. |
tools |
array of string | no | The tools the task may call. Each item is a tool name, as a string, such as "acme.merge_pull_request". An entry that is an object, including one carrying its own gates or marked optional, cannot be sent through this tool: sending tools replaces them all, so leave tools out to keep the current ones. |
inputs |
array of object | no | The inputs, as { key, label, type, required?, configuration?, requiredGroup?, entries? }. type is string, number, boolean, link or file. configuration marks persistent enterprise setup. requiredGroup requires at least one input in the group; every member must agree on configuration. A string map may declare entries: { keyInput, separator }: comma-separated key/value entries must cover the resolved keyInput at each start. Missing required configuration prevents a run from starting. |
gates |
array of object | no | Gates on tools that reach outside. Each object is { tool, owner, approval }. On create, leave it out and the task is given the default CEO gates; on publish, leave it out and the current gates stay. Send [] to declare none, which is refused when a tool still requires a gate. |
spend |
object | no | Spend limits, as { moneyUsdPerRun, maxModelTier, model, maxSteps }. Leave model out, or send "auto", and a model is chosen for each run by what the work needs, no higher than maxModelTier (economical, mid or frontier) when that is set. Send an exact model id as model to use that model for every run. maxSteps is how many steps a run gets, a whole number from 1 to 400; leave it out for the default for the tool shape (24, or 120 with workspace or Computer-Use tools). The run input maxSteps and the operator setting LLM_MAX_STEPS still win over it. |
workspace |
object | no | The clone the task may change, as { branch, onDefaultBranch, writeAllow, rewriteAllow, writeDeny, appendOnly, pushAllow, requireFiles, credentials }. Each list is strings but credentials, which is [{ tool, as, prop? }]: a bound tool's secret (or its custom prop) as the environment variable as of the run's repository commands; onDefaultBranch: true keeps the run on the default branch's tip, with no branch of its own and nothing to push; pushAllow lists the full ref globs (refs/heads/main, refs/tags/v*) a run may push with workspace.git_push's ref besides its own branch, and needs writeAllow. |
successors |
array of object | no | What runs after this task. Each object is { slug, on, when, delayMinutes, maxRunsPerIssue, escalate, verificationAnyOf }. on is succeeded, failed or terminal. |
finishesOn |
array of string | no | Outcome names that finish the work. Each item is plain text, at most 16. |
maxRunsPerExecution |
integer, at least 1 | no | The most countable runs this task may have in one execution before its next start is logged or stopped, a whole number of at least 1. Counted per task across the execution, whichever handoff started each run. Never applied below the highest maxRunsPerIssue on a successor into the task. Left out on create, or never set, EXECUTION_MAX_TASK_RUNS applies; left out on publish, the current value stays. |
toolSlots |
array of object | no | Tool slots the task’s tools may be named by in place of one vendor’s tool type, at most 16. Each object is { key, label, description?, actions? }: key reads like a tool type (codehost), label is what a person choosing a binding reads. A tool named "codehost" or "codehost.<tool>" is then filled per enterprise by the binding that lists codehost among the slots it fills, and runs as that binding’s tool type. actions is a list of { name, description? }, at most 32, the actions the task names under the key ("codehost.pr.merge"); the filling binding maps each to one of its own tools, so the task names no vendor’s tool. |
callLimits |
array of object | no | How often one run may make a call, at most 16. Each object is { tool, match?, perRun }: tool is one tool the task’s tools reach, by its exact name ("acme.issue_write"); match names payload fields the call must carry to count, as a gate’s match does ({ "method": "create" }); perRun is a whole number of at least 1. A call past the limit is not sent, and the run reads call_limit_reached instead. |
mailboxAction |
object | no | Where a mailbox offers this task as a one-click button, as { on, label }. on is mailbox (a button above the mailbox’s list; the run starts with no input of the OS’s) or mail (a button on one open message; the run starts with that message’s id as its emailId input, so the task has to declare an input with that key). label is the button’s words, at most 40 characters. A public template that declares one is offered to clone on inboxes that have no such task yet. Leave it out to offer none. |
skillMd |
string | no | The skill text, markdown, telling the model how to do the job. |
contextPrefixes |
array of string | no | Key prefixes loaded into input.context when a run starts. Each item is plain text. |
trainGrants |
array of object | no | Team or enterprise notes a run of this task may write. Each object is { layer, eventIdPrefix }, layer team or enterprise. A team note goes to each team the running member sits on or leads. |
overlapPolicy |
string, one of skip, os |
no | skip waits behind the member’s other work. os runs beside it. |
serializeOn |
array of string | no | Input keys that partition this task’s work into lanes, up to 8. Each item is plain text. |
allowSelfReaction |
boolean | no | Kept for versions written before it was retired: the OS no longer reads it, and a reaction is a call like any other. Leave it out. |
visibility |
string, one of public, private |
no | public publishes this version to the catalog, private withdraws it. Either also needs catalog:write. Left out, a task already in the catalog sends this version there too, and any other task changes only itself. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat after a successful publish is refused (task_version_conflict): baseVersionId is then stale. Read the task again and send the new currentVersionId. A save that changes nothing returns the current version with unchanged true.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The version:
id,version, the definition, andunchanged(truewhen the save decided nothing). For a task in the catalog, or a save withvisibility: public,catalogPublication: the entry’sid,versionandsourceVersion(the task version it holds),updated(whether this save reached the catalog) andrefusal(errorandmessagesaying why the catalog kept its version, or null). - API:
POST /v1/tasks/:id/versions(tasks:write)
| Error | When | What happens |
|---|---|---|
base_version_required |
baseVersionId is missing or blank. Read the task and send its currentVersionId. |
Tool error |
task_version_conflict |
Someone published a newer version than baseVersionId. The body names currentVersionId and currentVersion. |
Tool error |
task_not_found |
id names no task in this enterprise, another enterprise's included. |
Tool error |
task_definition_read_only |
The task is a clone: its definition belongs to the original's owner. | Tool error |
os_task_immutable |
The task is one of the OS's own: the same in every enterprise, changed only with a release. | Tool error |
skillMd_required |
The skill would be empty. | Tool error |
invalid_name |
name is empty, or longer than 200 characters. |
Tool error |
invalid_slug |
The slug is empty once cleaned, or longer than 80 characters. | Tool error |
task_slug_taken |
This enterprise already has a task with that slug. | Tool error |
task_team_removed |
The call names a team for the task. A task belongs to a role, not a team: a team runs the tasks of the roles its members hold. Seat a holder of the task’s role on the team instead. | Tool error |
invalid_task_definition |
The definition fails a check: a deterministic task with tools, a merge or mail or plan gate that is missing, a successor the rules refuse, a call limit on a tool the task does not declare (call_limit_tool_not_declared). | Tool error |
call_limits_invalid |
callLimits is not a list of up to 16 objects. The refusal names the fault instead when one limit is wrong: call_limit_tool_invalid (not one tool by its exact name), call_limit_match_invalid:<tool> (not a gate-shaped match) or call_limit_per_run_invalid:<tool> (not a whole number of at least 1). |
Tool error |
serialize_on_invalid |
serializeOn is not a list of up to 8 input keys. |
Tool error |
tool_entry_unreadable |
A tools entry names no tool. |
Tool error |
llm_model_not_in_catalogue |
spend.model is not a model a connected provider offers. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000013",
"baseVersionId": "6a1d2e3f-0000-4000-8000-000000000014",
"guardrails": [
"Never close an issue."
]
}
os.set_task_run_status
Enable or disable a task.
What the model reads:
Set runStatus to active or disabled. Enabling permits future starts; it does not start a run. Disabling prevents future starts without cancelling work already running. Built-in task controls remain protected by the API.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task id from os.list_task_definitions. |
runStatus |
string, one of active, disabled |
yes | Whether the task may start. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PATCH /v1/tasks/:id/run-status(tasks:write)
os.set_task_schedule
Set a task schedule.
What the model reads:
Replace a task schedule. Pass cron, optionally an IANA timezone (otherwise the enterprise timezone), enabled (defaults to true), and input matching the task fields. The API validates the schedule and refuses built-in tasks. A disabled task still cannot run. Read the schedule back with os.read_task_definition.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task id from os.list_task_definitions. |
cron |
string | yes | A five-field cron expression. |
timezone |
string | no | An IANA timezone, or enterprise to follow the enterprise timezone. |
enabled |
boolean | no | Whether the schedule should fire. Defaults to true. |
input |
object | no | Inputs supplied on each scheduled run. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PUT /v1/tasks/:id/schedule(tasks:write)
os.remove_task_schedule
Remove a task schedule.
What the model reads:
Remove a task schedule so it no longer starts work on a cadence. Does not cancel existing runs. Built-in tasks are refused by the API.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task id from os.list_task_definitions. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
DELETE /v1/tasks/:id/schedule(tasks:write)
os.set_task_input_values
Set this enterprise's own values for a task's inputs.
What the model reads:
Replace this enterprise's own values for the inputs a task declares, keyed by input key; pass {} to clear them. Every run of the task takes them, however it starts: a value the start gives wins, then these, then the task version's defaults. Works on any task the enterprise runs, including a linked clone whose definition another enterprise owns; it changes no version. Each key must be an input the current version declares and each value of its declared type; a file input takes none. Built-in tasks are refused. Read them back with os.read_task_definition (inputValues, and ignoredInputValues for saved values the current version no longer takes).
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The task id from os.list_task_definitions. |
values |
object | yes | Input key to value: text, a number or true/false, as the input declares. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PUT /v1/tasks/:id/input-values(tasks:write)
os.read_context
Read enterprise workflow context outside a run.
What the model reads:
Read one enterprise context key. Returns key, value (null when absent), and updatedAt. This is workflow bookkeeping, separate from knowledge in memory.
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | One enterprise context key, at most 512 characters, without whitespace. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
GET /v1/enterprise/context/:key(enterprise:read)
os.write_context
Set enterprise workflow context outside a run.
What the model reads:
Store a JSON object under one enterprise context key, at most 16 KB encoded. Last write wins. Replaces the entire value, so read it before changing selected fields. Records the authenticated caller as the writer. Does not change task permissions, versions or schedules.
| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | One enterprise context key, at most 512 characters, without whitespace. |
value |
object | yes | The complete JSON object to store, at most 16 KB. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state.
- Called by: the API, the CEO chat, the OS MCP server.
- API:
PUT /v1/enterprise/context/:key(enterprise:write)
os.list_teams
The enterprise's teams, by name.
What the model reads:
List the enterprise's teams, ordered by name: each one's id, name, slug, status, lead (leadMemberId and leadName, null for none), charter and concurrentRunLimit (null when it uses the enterprise's). No arguments. Never another enterprise's teams.
Takes no arguments: no fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: One row per team, each with
id,name,slug,status,leadMemberId,leadNameandconcurrentRunLimit. - API:
GET /v1/teams(teams:read)
Example:
{}
os.read_team
One team, with its members and the tasks its members’ roles run.
What the model reads:
Read one team: its name, slug, status, lead, charter and concurrentRunLimit, the members on it (members) and the tasks it runs (tasks): the tasks of the roles its members hold, seated or as lead. A task belongs to a role, not a team, so the list changes as members join and leave. Not found for a team in another enterprise.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The team, by its id from os.list_teams. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The team:
id,name,slug,concurrentRunLimitand the rest,members(who is on it) andtasks(the tasks of the roles its members hold). - API:
GET /v1/teams/:id(teams:read)
| Error | When | What happens |
|---|---|---|
team_not_found |
id names no team in this enterprise, another enterprise's included. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021"
}
os.create_team
Create a team, optionally with its own concurrent run limit.
What the model reads:
Create a team with a name and, optionally, its own concurrent run limit (concurrentRunLimit); left out, the team uses the enterprise's. Its slug is made from the name, so a name whose slug another team already has is refused with team_slug_taken. The response is the team as created.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The team’s name, up to 200 characters. Its slug is made from it. |
concurrentRunLimit |
integer, at least 1 | no | How many of the team’s runs may run at once, at least 1. Left out, the team uses the enterprise’s limit. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. Every call creates a team. A repeat with the same name is refused (team_slug_taken) rather than creating a second.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The team as created:
id,name,slug,concurrentRunLimitand the rest,membersandtasks. - API:
POST /v1/teams(teams:write)
| Error | When | What happens |
|---|---|---|
team_slug_taken |
Another team in this enterprise already has the slug made from that name, so a repeat of a create is refused too. | Tool error |
concurrent_run_limit_invalid |
concurrentRunLimit is not a whole number of at least 1. |
Tool error |
concurrent_run_limit_over_enterprise |
Every team's limit together would exceed the enterprise's own concurrent run limit. The refusal says by how much. | Tool error |
Example:
{
"name": "Support",
"concurrentRunLimit": 2
}
os.update_team
Change a team's name or concurrent run limit.
What the model reads:
Change a team's name or its concurrent run limit (concurrentRunLimit); a field left out keeps its value. A limit that would take every team's together past the enterprise's is refused with concurrent_run_limit_over_enterprise. The response is the team after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The team, by its id from os.list_teams. |
name |
string | no | The team’s new name, up to 200 characters. Its slug stays as it is. |
concurrentRunLimit |
integer, at least 1 | no | How many of the team’s runs may run at once, at least 1. Every team’s limit together stays within the enterprise’s. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same fields set twice leave the team as the first call did.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The team after the change:
id,name,slug,concurrentRunLimitand the rest,membersandtasks. - API:
PATCH /v1/teams/:id(teams:write)
| Error | When | What happens |
|---|---|---|
team_not_found |
id names no team in this enterprise, another enterprise's included. |
Tool error |
concurrent_run_limit_invalid |
concurrentRunLimit is not a whole number of at least 1. |
Tool error |
concurrent_run_limit_over_enterprise |
Every team's limit together would exceed the enterprise's own concurrent run limit. The refusal says by how much. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021",
"name": "Customer support"
}
os.delete_team
Remove a team.
What the model reads:
Remove a team. Its members come off it and keep their roles, and with them the tasks those roles run. The enterprise’s last team is refused with last_team: an enterprise keeps at least one. Any other refusal comes back with the API’s reason. The call is the confirmation, so the tool takes no confirm argument.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The team, by its id from os.list_teams. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat finds the team already gone and is refused with team_not_found, removing nothing else.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: Nothing: the team is gone.
- API:
DELETE /v1/teams/:id(teams:write)
| Error | When | What happens |
|---|---|---|
team_not_found |
id names no team in this enterprise, another enterprise's included. |
Tool error |
last_team |
The team is the last one the enterprise has. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021"
}
os.add_team_member
Put a member on a team, optionally in a role.
What the model reads:
Put a member on a team, and, when roleId names one, give them that role too. The role is a convenience: a team can hold a member before it has a role to give them. The response is the team after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The team, by its id from os.list_teams. |
memberId |
string | yes | The member to put on the team. |
roleId |
string | no | A role the member holds from now on as well. Left out, their roles are unchanged. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A member already on the team stays on it once, and holds a role it names once.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The team after the change, with the member among its
members. - API:
POST /v1/teams/:id/members(teams:write)
| Error | When | What happens |
|---|---|---|
team_not_found |
id names no team in this enterprise, another enterprise's included. |
Tool error |
member_not_found |
memberId names no member in this enterprise. |
Tool error |
role_not_found |
roleId names no role in this enterprise. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021",
"memberId": "5f0c1d2e-0000-4000-8000-000000000014"
}
os.remove_team_member
Take a member off a team.
What the model reads:
Take a member off a team. They keep their roles; a lead taken off no longer leads it. The response is the team after the change.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The team, by its id from os.list_teams. |
memberId |
string | yes | The member to take off the team. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A member already off the team stays off it.
- Called by: the CEO chat, the API, the OS MCP server.
- Returns: The team after the change, without the member among its
members. - API:
DELETE /v1/teams/:id/members/:memberId(teams:write)
| Error | When | What happens |
|---|---|---|
team_not_found |
id names no team in this enterprise, another enterprise's included. |
Tool error |
member_not_found |
memberId names no member in this enterprise. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000021",
"memberId": "5f0c1d2e-0000-4000-8000-000000000014"
}
os.add_work_item
Add an item to a team's work list.
What the model reads:
Add an item to a team's work list: a title, a kind (one word you choose), and optionally a state, a priority, a short body (up to 16 KB), up to 20 links, a parent item on the same team (one level only) and a not-before date until which no run claims it. It starts proposed unless you give an open state, and goes to the end of its level. Who added it is recorded from the caller. A run adds to the first team its member sits on or leads, or, with forFunction, to the list of the team in its enterprise that holds that business function: as proposed, for that team's lead or a person to approve. An issue or pull request has one open item across the enterprise: a link to one another open item holds, on any team’s list, is refused with work_item_exists, and the issue is taken.
| Field | Type | Required | Description |
|---|---|---|---|
teamId |
string | no | The team whose list it is. A run leaves it out: the first team its member sits on or leads is used, and any other is ignored. |
title |
string | yes | What the work is, up to 200 characters. |
kind |
string | yes | A word the task chooses for the kind of work (content, outreach, bug): one word, no spaces, up to 40 characters. |
state |
string, one of proposed, ready, held, in_progress |
no | Where it starts: proposed (waiting for a person) unless given. held is parked until a person releases it. Closed states are set by os.close_work_item. |
priority |
string, one of urgent, high, medium, low |
no | Its level, urgent first. Left out, it has none and lists after every level. |
body |
string | no | A short body: plain text, up to 16 KB. Link a larger document instead. |
links |
array of string | no | Up to 20 http(s) URLs the work refers to. |
parentId |
string | no | The item this one sits under, such as a campaign or an epic, by its id: an item on the same team that has no parent itself. Left out, it stands alone. |
notBefore |
string | no | The moment before which no run claims it, such as a check due 28 days after go-live: a date-time with an offset or Z (2026-12-03T09:00:00Z), or a date (2026-12-03) meaning the start of that day in the enterprise's timezone. It still lists in its usual place. Left out, it can be claimed as soon as it is ready. |
forFunction |
string, one of support, marketing, sales, operations, engineering |
no | A run only: put the item on another team's list, the team of your enterprise that holds this business function. It is added as proposed whatever state you give, for a person or that team's lead to approve: you can never approve it, and unless you sit on that team you cannot read or change it afterwards. With no such team, or more than one, nothing is added: the finding goes to a person on Blockers and the answer says raised. Naming your first team's function adds the item to your first team's list as proposed. Ignored outside a run, where teamId names the team. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same tool call sent again adds the item once and answers with the item it added.
- Called by: a run, the CEO chat, the API, the OS MCP server.
- Returns: The item:
id,teamId,title,kind,state,priority,position,body,links,addedBy,createdAt,updatedAt,closedAt,closeReason,claimedByRunIdandclaimedAt(the run working it and since when, or null),parentId(the item it sits under, or null),notBefore(the UTC instant before which no run claims it, or null), andrequestedBy(the person the work is for,{ id, name }, or null for nobody: set by the OS only when the item is added, from the person adding it or the person who asked for the run adding it, never from an argument). With forFunction, the answer is the item placed on the receiving team, withorigin(the team and run that sent it), or, when no single team holds the function,{ raised: true, reason, forFunction, candidates }: nothing was added, a person was told on Blockers, and the run carries on. - API:
POST /v1/teams/:teamId/work-items(teams:write)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
team_not_found |
teamId names no team in this enterprise, another enterprise's included. |
Tool error |
invalid_work_item |
A title, kind, state, priority, position, link, reason or forFunction is missing or not one the list accepts; or a parent is the item itself, has a parent of its own, is given to an item that has children, or is not an item on the same team; or notBefore is not a date (YYYY-MM-DD), a date-time with an offset or Z, or none. | Tool error |
body_too_large |
The body is over 16 KB. Keep a larger document elsewhere and put its address in links. |
Tool error |
work_item_exists |
A link names an issue or pull request that another open item in the enterprise already holds, on any team’s list. The issue is taken: leave it and pick another. Closing that item frees it. | Tool error |
Example:
{
"title": "Draft the launch note",
"kind": "content",
"priority": "high",
"links": [
"https://example.com/brief"
]
}
os.list_work_items
A team's work list, open items by default.
What the model reads:
List a team's work items: the open ones (proposed, ready, held, in_progress) unless you ask for a state, optionally of one kind. Ordered by priority (urgent first, none last), then position, then age, in pages of 25 (up to 200). A run lists the first team its member sits on or leads. Each item carries its parentId and a rollup of its children, `children: { total, byState }`, closed children counted.
| Field | Type | Required | Description |
|---|---|---|---|
teamId |
string | no | The team whose list it is. A run leaves it out: the first team its member sits on or leads is used, and any other is ignored. |
state |
string, one of open, proposed, ready, held, in_progress, done, dropped |
no | Only items in this state, or open for every open state. Left out, every open state. |
kind |
string | no | Only items of this kind. |
page |
integer, at least 1 | no | Which page, from 1. |
limit |
integer, 1 to 200 | no | Items per page: 25 unless given. |
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:
{ data, total, page, limit, pages }:datais one page of items, each as os.read_work_item gives it,claimedByRunStatus,childrenandrequestedByincluded. - API:
GET /v1/teams/:teamId/work-items(teams:read)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
team_not_found |
teamId names no team in this enterprise, another enterprise's included. |
Tool error |
invalid_work_item |
A title, kind, state, priority, position, link, reason or forFunction is missing or not one the list accepts; or a parent is the item itself, has a parent of its own, is given to an item that has children, or is not an item on the same team; or notBefore is not a date (YYYY-MM-DD), a date-time with an offset or Z, or none. | Tool error |
Example:
{
"state": "ready",
"kind": "content"
}
os.read_work_item
One work item, with every field.
What the model reads:
Read one work item with every field, open or closed, and claimedByRunStatus: the status now of the run holding it (live, waiting at a gate, ended, or null for none), which tells work being done from work waiting, finished without closing the item, or stopped. Not found for an item in another enterprise, or, for a run, on the list of a team its member is not on, unless it is the open item the run holds.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The item, by its id from os.list_work_items or os.add_work_item. |
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: The item:
id,teamId,title,kind,state,priority,position,body,links,addedBy,createdAt,updatedAt,closedAt,closeReason,claimedByRunIdandclaimedAt(the run working it and since when, or null),parentId(the item it sits under, or null),notBefore(the UTC instant before which no run claims it, or null), andrequestedBy(the person the work is for,{ id, name }, or null for nobody: set by the OS only when the item is added, from the person adding it or the person who asked for the run adding it, never from an argument). AlsoclaimedByRunStatus: the status of the run holding it now, or null; andchildren:{ total, byState }, how many items sit under it and how many in each state, closed ones included. - API:
GET /v1/work-items/:id(teams:read)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031"
}
os.update_work_item
Change an open work item's fields.
What the model reads:
Change an open item's title, kind, state (among the open ones), priority, position, body, links, parent or not-before date. A field left out keeps its value. Each change is kept in the item’s history with who made it, and a call that changes nothing records nothing. A closed item cannot be changed (work_item_closed). Only a person approves a proposed item or releases a held one: a run that tries is refused (approval_requires_person).
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The item, by its id from os.list_work_items or os.add_work_item. |
title |
string | no | The new title, up to 200 characters. |
kind |
string | no | A word the task chooses for the kind of work (content, outreach, bug): one word, no spaces, up to 40 characters. |
state |
string, one of proposed, ready, held, in_progress |
no | Move it between the open states: proposed waits for a person, ready can be claimed, held is parked until a person releases it. A run cannot move a proposed or held item out of that state. Use os.close_work_item to finish or drop it. |
priority |
string, one of urgent, high, medium, low, none |
no | Its level, urgent first. none clears it, so it lists after every level. |
position |
integer | no | Its place among items of the same level: lower lists first. A new item goes to the end. |
body |
string | no | The new body: plain text, up to 16 KB. |
links |
array of string | no | The whole new list of links: up to 20 http(s) URLs. |
parentId |
string | no | The item this one sits under, by its id: an item on the same team that has no parent itself. none clears it. An item that has children takes no parent. |
notBefore |
string | no | Set or move the moment before which no run claims it: a date-time with an offset or Z (2026-12-03T09:00:00Z), or a date (2026-12-03) meaning the start of that day in the enterprise's timezone. none clears it. It keeps its state and place in the list; a run already holding it keeps it. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same tool call sent again changes the item once and answers with the first answer.
- Called by: a run, the CEO chat, the API, the OS MCP server.
- Returns: The item after the change. The item:
id,teamId,title,kind,state,priority,position,body,links,addedBy,createdAt,updatedAt,closedAt,closeReason,claimedByRunIdandclaimedAt(the run working it and since when, or null),parentId(the item it sits under, or null),notBefore(the UTC instant before which no run claims it, or null), andrequestedBy(the person the work is for,{ id, name }, or null for nobody: set by the OS only when the item is added, from the person adding it or the person who asked for the run adding it, never from an argument). - API:
PATCH /v1/work-items/:id(teams:write)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
work_item_closed |
The item is closed (done or dropped), so it can no longer be changed or closed the other way. |
Tool error |
invalid_work_item |
A title, kind, state, priority, position, link, reason or forFunction is missing or not one the list accepts; or a parent is the item itself, has a parent of its own, is given to an item that has children, or is not an item on the same team; or notBefore is not a date (YYYY-MM-DD), a date-time with an offset or Z, or none. | Tool error |
body_too_large |
The body is over 16 KB. Keep a larger document elsewhere and put its address in links. |
Tool error |
approval_requires_person |
A run tries to move a proposed or held item to another state: only a person approves or releases one. | Tool error |
work_item_exists |
A link names an issue or pull request that another open item in the enterprise already holds, on any team’s list. The issue is taken: leave it and pick another. Closing that item frees it. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031",
"state": "in_progress"
}
os.close_work_item
Close a work item as done or dropped.
What the model reads:
Close an item as done or dropped, with an optional reason. It stays readable with its whole history, and can no longer be changed. Closing it again the same way changes nothing; the other way is work_item_closed.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The item, by its id from os.list_work_items or os.add_work_item. |
state |
string, one of done, dropped |
yes | done when the work is finished, dropped when it is not. |
reason |
string | no | Why, in a sentence, up to 2000 characters. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Closing an item again in the same state changes nothing and answers with the item as closed.
- Called by: a run, the CEO chat, the API, the OS MCP server.
- Returns: The item as closed, with
closedAtset. The item:id,teamId,title,kind,state,priority,position,body,links,addedBy,createdAt,updatedAt,closedAt,closeReason,claimedByRunIdandclaimedAt(the run working it and since when, or null),parentId(the item it sits under, or null),notBefore(the UTC instant before which no run claims it, or null), andrequestedBy(the person the work is for,{ id, name }, or null for nobody: set by the OS only when the item is added, from the person adding it or the person who asked for the run adding it, never from an argument). - API:
POST /v1/work-items/:id/close(teams:write)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
work_item_closed |
The item is closed (done or dropped), so it can no longer be changed or closed the other way. |
Tool error |
invalid_work_item |
A title, kind, state, priority, position, link, reason or forFunction is missing or not one the list accepts; or a parent is the item itself, has a parent of its own, is given to an item that has children, or is not an item on the same team; or notBefore is not a date (YYYY-MM-DD), a date-time with an offset or Z, or none. | Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031",
"state": "done",
"reason": "Published on Friday"
}
os.claim_work_item
Take the next ready item of this run's team lists, so no other run can take it.
What the model reads:
Claim the highest-priority ready item on the lists of the teams you sit on or lead, your first team’s list first and the next team’s only when it has none, each in the order os.list_work_items gives (priority, then position, then age), optionally only of the kinds you give. A claim skips an item until its not-before date (notBefore), and takes the next one instead; from that moment it is claimed as before. Or give id to claim that one item, such as one you just added for the work you are handing on: it is taken if it is ready, or still in progress for a run that has ended; a held, proposed or closed item, one whose not-before date has not come, or one a live run holds, answers { item: null }. In the same step it moves to in_progress and is marked as worked by this run, so no other run can take it. A run holds one item: calling again answers with the item it already holds. When no item fits, the answer is { item: null }, not an error. The claim lasts while the run is live, gate waits included; if the run is cancelled without closing the item, it goes back to ready for the next run. If the run fails or is blocked, or its pipeline stops short, the item is held for a person, still naming the run: a retry takes it over, and clearing the run on Blockers or releasing the item puts it back to ready. When the run ends and hands off, every successor it starts receives the item as its workItem input and holds it in turn, so the runs on one item are one execution, its loop caps count laps on the item, and a task that declares its finish closes the item as done.
| Field | Type | Required | Description |
|---|---|---|---|
kinds |
array of string, at least 1 | no | Only items of these kinds: 1 to 20, each one word with no spaces, up to 40 characters. Left out, any kind. |
id |
string | no | Claim this one item of your teams’ lists instead of the next ready one. Not with kinds. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same tool call sent again answers with the first answer, and a run that already holds an item gets that item back: it never takes a second.
- Called by: a run, the API.
- Returns:
{ item }: the item this run now holds, withclaimedByRunIdandclaimedAtset, or null when no ready item fits. The item:id,teamId,title,kind,state,priority,position,body,links,addedBy,createdAt,updatedAt,closedAt,closeReason,claimedByRunIdandclaimedAt(the run working it and since when, or null),parentId(the item it sits under, or null),notBefore(the UTC instant before which no run claims it, or null), andrequestedBy(the person the work is for,{ id, name }, or null for nobody: set by the OS only when the item is added, from the person adding it or the person who asked for the run adding it, never from an argument). - API:
POST /v1/runs/self/work-items/claim(run:self)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
invalid_work_item |
kinds is not a list of 1 to 20 kinds, each one word with no spaces, up to 40 characters; id is not text; or both are given. |
Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
Example:
{
"kinds": [
"content",
"outreach"
]
}
Example, Any kind.:
{}
Example, The item you just added for an issue.:
{
"id": "0192f7d4-5b1a-7c3e-9a2b-4c5d6e7f8a9b"
}
os.read_work_item_draft
An item's draft as it is now: its latest version, text included.
What the model reads:
Read the draft a work item holds: its latest version at the moment of the call, so an edit a person saved since the last run is what you get, or one earlier version in full when you give its number. A draft is markdown, up to 256 KB, and every version is kept. The item’s own read and list carry only `draft: { version, updatedAt, updatedBy }`, never the text: read the text here. Not found for an item in another enterprise, or on the list of a team your member is not on.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The item, by its id from os.list_work_items or os.add_work_item. |
version |
integer, at least 1 | no | One version, by its number (from 1). Left out, the latest. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run, the API.
- Returns:
{ draft }: the version, withversion(its number, from 1),writtenAt,writtenBy(who wrote it:{ kind: "run", runId, taskId, memberId },{ kind: "person", humanUserId },{ kind: "member", memberId }or{ kind: "api_key", apiKeyId }) andcontent, the markdown.draftis null when the item has no draft, or no version of that number. - API:
POST /v1/runs/self/tools/os.read_work_item_draft(run:self)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031"
}
Example, The first version.:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031",
"version": 1
}
os.write_work_item_draft
Write a new version of an item's draft.
What the model reads:
Write the draft a work item holds, as markdown of up to 256 KB of UTF-8 text: a new version written by this run, after every earlier one, all of which are kept for a person to read and edit on the item. Text the latest version already holds adds nothing and answers that version. Give baseVersion, the version you read, to be refused (draft_conflict) rather than go over a version saved since, such as a person’s edit; left out, the write goes on top of whatever is current. A closed item’s draft cannot be changed (work_item_closed). Each write is kept in the item’s history, without the text.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The item, by its id from os.list_work_items or os.add_work_item. |
content |
string | yes | The whole draft, as markdown: up to 256 KB of UTF-8 text. |
baseVersion |
integer, at least 0 | no | The version you read and changed, 0 when the item had no draft. Left out, the write never conflicts. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same tool call sent again writes the version once and answers with the version it wrote.
- Called by: a run, the API.
- Returns: The version this write made, or the current one when its text was unchanged:
version(its number, from 1),writtenAt,writtenBy(who wrote it:{ kind: "run", runId, taskId, memberId },{ kind: "person", humanUserId },{ kind: "member", memberId }or{ kind: "api_key", apiKeyId }) andcontent, the markdown. - API:
POST /v1/runs/self/tools/os.write_work_item_draft(run:self)
| Error | When | What happens |
|---|---|---|
no_team |
The member running the run sits on no team and leads none, so it has no list to keep. | Tool error |
work_item_not_found |
id names no item this caller can reach: none at all, another enterprise's, or, for a run, a team it is not on. |
Tool error |
work_item_closed |
The item is closed (done or dropped), so it can no longer be changed or closed the other way. |
Tool error |
invalid_work_item |
content is not text, or baseVersion is not a whole version number (0 when the item had no draft). |
Tool error |
draft_too_large |
The draft is over 256 KB of UTF-8 text. Shorten it, or keep a larger document elsewhere and link it. | Tool error |
draft_conflict |
baseVersion is no longer the current version: someone (a person, or another run) saved a newer one since you read it. The refusal names the current version: read it again and make your change on that one. |
Tool error |
Example:
{
"id": "5f0c1d2e-0000-4000-8000-000000000031",
"content": "# Launch note\n\nShipping on **Friday**.",
"baseVersion": 1
}
os.publish_role
Publish one of the enterprise’s roles to the catalog, by its portable name and slug.
What the model reads:
Publish one of the enterprise’s roles to the catalog, where any company can clone it. Pass sourceRoleId, the role’s id from os.list_roles. Only the role’s name and slug are published: its members stay with the enterprise, and its tasks are listed with it once each is published to the catalog itself (those already published join it at once). Public role slugs are global, so a slug the catalog already holds is refused (catalog_role_slug_taken). A plan without catalog publishing is refused with its reason (catalog_publish_not_in_plan) and nothing is written. A task that declares this tool is refused when it is saved. A task reaches it only through a bound connection to the OS’s own MCP server, with a gate naming the tool, as with every write that server serves. The response is the public role, with its id and slug.
| Field | Type | Required | Description |
|---|---|---|---|
sourceRoleId |
string | yes | The role to publish, by its id from os.list_roles. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat after a successful publish is refused (catalog_role_slug_taken): the catalog then holds the role. Read the catalog’s roles to see it there.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The public role:
id,slug,name,visibility(public) andownerEnterpriseId. - API:
POST /v1/catalog/roles(catalog:write)
| Error | When | What happens |
|---|---|---|
catalog_publish_not_in_plan |
The enterprise’s plan does not include catalog publishing. The refusal says so in a sentence and names /billing. Nothing is written. | Tool error |
catalog_role_slug_taken |
The catalog already holds a public role with this role’s slug. Public role slugs are global, so a role is published once; rename the role’s slug to publish it as another. | Tool error |
role_not_found |
sourceRoleId names no role in this enterprise, another enterprise’s included. |
Tool error |
source_role_required |
sourceRoleId is missing or empty. |
Tool error |
Example:
{
"sourceRoleId": "5f0c1d2e-0000-4000-8000-000000000021"
}
os.publish_team
Publish one of the enterprise’s teams to the catalog, with its roles, as the portal’s Share does.
What the model reads:
Publish one of the enterprise’s teams to the catalog, as Share on the team’s page does. Pass teamId, the team’s id from os.list_teams. The team’s roles the catalog does not hold yet are published first, then the team as one entry under its slug: a teammate slot per member carrying the roles they hold and nothing of the member, its KPIs, the cadence of each schedule on a task the catalog holds, and its goal. Its tasks travel once each is published to the catalog itself. roleSlugs names the roles that go; the rest are left out, and stay left out when the team is published again without roleSlugs. name and description are the words the catalog shows, and default to the team’s name and goal; kindOfWork and businessFunction file it. Publishing a team that has an entry brings that entry up to date instead of adding a second. Refused on a plan without catalog publishing (catalog_publish_not_in_plan), for a team with no roles (team_has_no_roles), and while another publisher holds a public role of one of its slugs (catalog_role_slug_taken, naming the slugs); nothing is written then. A task that declares this tool is refused when it is saved. A task reaches it only through a bound connection to the OS’s own MCP server, with a gate naming the tool, as with every write that server serves. The response is the entry and the public roles it names.
| Field | Type | Required | Description |
|---|---|---|---|
teamId |
string | yes | The team to publish, by its id from os.list_teams. |
roleSlugs |
array of string | no | The slugs of the team’s roles that go to the catalog; the rest are left out. Leave it out to keep what was left out last time. |
name |
string | no | The name the catalog shows, at most 200 characters. Leave it out for the team’s name. |
description |
string | no | One line the catalog shows, at most 280 characters. Leave it out for the team’s goal. |
kindOfWork |
string | no | The kind of work setup offers the team for: one lowercase word, such as support. Leave it out for none. |
businessFunction |
string, one of support, marketing, sales, operations, engineering |
no | The business function the catalog files the team under. Leave it out for none. |
No other fields are accepted.
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat publishes the team again: its entry is brought up to date from the team as it stands, and no second entry is made.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns: The catalog entry as
entry(id,slug,name,teammates), and the public roles it names asroles. - API:
POST /v1/catalog/share/teams/:teamId(catalog:write)
| Error | When | What happens |
|---|---|---|
catalog_publish_not_in_plan |
The enterprise’s plan does not include catalog publishing. The refusal says so in a sentence and names /billing. Nothing is written. | Tool error |
catalog_role_slug_taken |
A public role with one of the team’s role slugs comes from another publisher. The refusal names them as slugs; rename those roles and publish again. Nothing is written. |
Tool error |
team_has_no_roles |
No member of the team holds a role and none of its tasks runs as one, or roleSlugs leaves every role out, so a clone would have nothing to hold. |
Tool error |
team_not_found |
teamId names no team in this enterprise, another enterprise’s included. |
Tool error |
invalid_catalog_team |
name is longer than 200 characters, or description longer than 280. |
Tool error |
invalid_team_roles |
roleSlugs is not a list of slugs, or names a role the team does not have. |
Tool error |
invalid_kind_of_work |
kindOfWork is not one lowercase word (letters, digits and underscores, at most 64 characters), or is something_else. |
Tool error |
invalid_business_function |
businessFunction is not one of support, marketing, sales, operations or engineering. |
Tool error |
Example:
{
"teamId": "5f0c1d2e-0000-4000-8000-000000000022",
"name": "Support desk",
"kindOfWork": "support",
"businessFunction": "support"
}
os.attach_repair
Report the repair issue you filed for the shared cause this run was started for.
What the model reads:
Attach the repair issue you filed to the shared cause this run was started for (your input's sharedCause), so the OS resumes the work that cause holds once that issue's pipeline is done. Only a run the OS started for a cause can call it, and only for that cause. Pass issue (the number of the issue you filed) and, optionally, cause (sharedCause.key from your input). A cause keeps the first issue attached to it: a later call with another number changes nothing and answers with the first.
| Field | Type | Required | Description |
|---|---|---|---|
issue |
integer, at least 1 | yes | The number of the repair issue you filed |
cause |
string | no | The cause's key, sharedCause.key from your input. Defaults to it. |
No other fields are accepted.
- Effect: write.
- Side effects: From then on the cause is finished when that issue's work item is done (its held runs are re-queued) or dropped (they return to Blockers, naming the cause).
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. The same call sent twice attaches once. A cause keeps the first issue attached to it.
- Called by: a run, the API.
- Returns:
{ cause, issue, attached }: the cause, the repair issue it now waits on, and whether that is the issue you passed (false when the cause already had another). - API:
POST /v1/runs/self/tools/os.attach_repair(run:self)
| Error | When | What happens |
|---|---|---|
not_a_repair_run |
The calling run was not started by the OS for a shared cause: its input carries no sharedCause.key. |
Tool error |
cause_not_yours |
cause names another cause than the one this run was started for. |
Tool error |
issue_invalid |
issue is not a positive whole number. |
Tool error |
cause_not_open |
The cause has cleared, or holds no run any more: nothing waits on a repair for it. | Tool error |
causes_unavailable |
This OS keeps no shared causes, so there is nothing to attach to. | Tool error |
Example:
{
"issue": 949
}