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"
}

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 }. findings is 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.
  • 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, rejected or changes_requested), decidedAt, decisionNote, decisionChoice, answers (each question with its answer, on an answered question gate) and editedPayload when an edit was sent, with the runId, toolName and payload it 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_approved with ceoAnswers (one per question) and ceoNote, or ceo_rejected with ceoNote. 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: implement starts 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { data, total, page, limit, pages }. Each row has id, fromAddress, fromName, subject, snippet, receivedAt, readAt, hasAttachments, threadKey (the same on every message in one conversation), direction (inbound when it arrived, outbound when 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, snoozed or escalated) and snoozedUntil (only when snoozed), spamScore and spamFlag (null if the receiving edge has not scored the message). With compact, each row has only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag.
  • 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: The message: sender, subject, textBody, sanitised htmlBody, 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, snoozed or escalated) and snoozedUntil (only when snoozed), spamScore and spamFlag (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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { status, id }: sent, or send_failed with the provider’s error when it did not go out. id is 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { status, id }: sent, or send_failed with the provider’s error when it did not go out. id is 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { data }: each contact with id (null on a directory row), address, name (empty when none is known), source (auto when a send saved it, manual when it was added by hand, directory for one of the enterprise’s own people or members offered beside the contacts), nameByHand (a name set by hand, which no later send replaces), mailCount and lastMailedAt (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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: The contact saved, with id (null on a directory row), address, name (empty when none is known), source (auto when a send saved it, manual when it was added by hand, directory for one of the enterprise’s own people or members offered beside the contacts), nameByHand (a name set by hand, which no later send replaces), mailCount and lastMailedAt (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 }, taskId always 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { updated, notFound }: how many mails were changed, and the ids given that are not in this mailbox (always [] when selecting by fromAddress).
  • 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • Returns: { data }: each row has threadKey, replyToEmailId (the newest inbound message: pass it to os.mail_reply as id), correspondent, subject and lastOutboundAt. 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • 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 memberId in the payload is ignored, and an OS-owned task has no mailbox.
  • 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 has id, fromAddress, fromName, subject, snippet, receivedAt, readAt, hasAttachments, threadKey (the same on every message in one conversation), direction (inbound when it arrived, outbound when 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, snoozed or escalated) and snoozedUntil (only when snoozed), spamScore and spamFlag (null if the receiving edge has not scored the message). With compact, each row has only id, fromAddress, subject, receivedAt, labels, handledState, spamScore and spamFlag.
  • 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, sanitised htmlBody, receivedAt, readAt, attachments (each with id, filename, contentType and sizeBytes, 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, snoozed or escalated) and snoozedUntil (only when snoozed), spamScore and spamFlag (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 by fromAddress).
  • 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, or send_failed with the provider’s error when it did not go out. id is 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, or send_failed with the provider’s error when it did not go out. id is 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, or send_failed with the provider’s error when it did not go out. id is 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 of taskId and catalogTaskId set, by label. schedule is 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, or pending while it waits its turn) and taskId.
  • 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 with id (null on a directory row), address, name (empty when none is known), source (auto when a send saved it, manual when it was added by hand, directory for one of the enterprise’s own people or members offered beside the contacts), nameByHand (a name set by hand, which no later send replaces), mailCount and lastMailedAt (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 (auto when a send saved it, manual when it was added by hand, directory for one of the enterprise’s own people or members offered beside the contacts), nameByHand (a name set by hand, which no later send replaces), mailCount and lastMailedAt (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) and template (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) and template (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, with id, address, replyFromAlias (whether a reply to mail that arrived at it leaves from it, rather than from your own address) and signature (its own, { html, text } with html sanitised 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, with id, address, replyFromAlias (whether a reply to mail that arrived at it leaves from it, rather than from your own address) and signature (its own, { html, text } with html sanitised 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 (reply or snooze), ceoNote and mailId. 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 with id, name, ownerLayer (company, team, role, task, or null for a company KPI set before layers), ownerId, sourceKind (task or person), sourceRef (the task or person id), target, cadenceMinutes, light, overdue and lastReading (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, recordedBy and runId (this run), target, and the KPI’s light as 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 }. value is 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 }. deleted is 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) and recordedBy.
  • 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 takenAt first, each with id, kpiId, value, takenAt and recordedBy.
  • 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 as os.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, with runId, the sections it is listed in (failed, stopped, blocked, stalled, paused), status, reason, blockClass, its task, team, team lead and assignee, the repo, issue and pr from its input, since, taskRetries (how many times tasks have retried its chain) and escalation (to whom, toYou, the note, when) once someone escalated it; then failedTotal (every uncleared failed run), the failedPage read and its pageSize, the team-health rows (missingLead, overdueRetro, and kpiHealth: a KPI that needs attention, with its condition (no_key_kpi, no_target, overdue or light), team, kpi, layer, light, trend and owner), spendEnabled and draining. Over the API: the portal rows as they are. Waiting gates are not here: read them with os.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), createdAt and 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), repo and number (null for a work item), workItem and workItemTitle (the item and its title; null for an issue or pull request), the newest runId and its taskId, endedAs (how that run ended: succeeded, failed, cancelled, or decision_rejected), the reason it gave and what the work waitsOn (each null when it named none), since (when it ended) and waitedMs. total is 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, or pending while 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, or pending while 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. alreadyEscalated is 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. gate is 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 with id, status (idle, replying or closed), lastMessage (role, content, createdAt, or null in an empty thread), lastReadAt (when a person last opened it, or null), createdAt and updatedAt. Over the API: the Chat page’s rows as they are, which add the member and the unread and unreadCount of 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 }, where total counts every message said in the thread and each message has id, role (user for a person or an API token, assistant for the member), content, sender (the name of whoever wrote a user message, else null) and createdAt. Over the API: the thread as the portal reads it, with its member and every row, each with its sender.
  • 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, name and slug.
  • 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) and tasks (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, teams and tasks.
  • 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, teams and tasks.
  • 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 with id, slug, name, kind, status, origin, builtIn, currentVersionId and currentVersion.
  • 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, currentVersionId and currentVersion (its version number and declared inputs), 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, and unchanged (true when the save decided nothing). For a task in the catalog, or a save with visibility: public, catalogPublication: the entry’s id, version and sourceVersion (the task version it holds), updated (whether this save reached the catalog) and refusal (error and message saying 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, leadName and concurrentRunLimit.
  • 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, concurrentRunLimit and the rest, members (who is on it) and tasks (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, concurrentRunLimit and the rest, members and tasks.
  • 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, concurrentRunLimit and the rest, members and tasks.
  • 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, claimedByRunId and claimedAt (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), and requestedBy (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, with origin (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 }: data is one page of items, each as os.read_work_item gives it, claimedByRunStatus, children and requestedBy included.
  • 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, claimedByRunId and claimedAt (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), and requestedBy (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). Also claimedByRunStatus: the status of the run holding it now, or null; and children: { 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, claimedByRunId and claimedAt (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), and requestedBy (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 closedAt set. The item: id, teamId, title, kind, state, priority, position, body, links, addedBy, createdAt, updatedAt, closedAt, closeReason, claimedByRunId and claimedAt (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), and requestedBy (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, with claimedByRunId and claimedAt set, or null when no ready item fits. The item: id, teamId, title, kind, state, priority, position, body, links, addedBy, createdAt, updatedAt, closedAt, closeReason, claimedByRunId and claimedAt (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), and requestedBy (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, with 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 }) and content, the markdown. draft is 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 }) and content, 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) and ownerEnterpriseId.
  • 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 as roles.
  • 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
}