Chat tools

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

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

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

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

Also offered here: os.directory, which a run can call too.

os.list_tasks

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

What the model reads:

List the tasks of the roles you hold on each task’s team, plus OS-owned tasks. OS tasks are not a person.

No declared fields: the schema accepts any object.

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

os.start_task

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

What the model reads:

Start a run of a task of a role you hold, an OS task, or a colleague’s task. Pass taskId or slug, and input matching the task’s fields; a field you leave out takes the task’s default. The run goes to a free member holding the task’s role, who may not be you; when every holder is busy it queues as pending. This only queues the run: check it with os.get_run before reporting on it.

• Effect: write.
• Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the chat session and the tool call: the same call sent twice starts one run.
• Called by: the CEO chat, the API.
• Returns: { runId, status, taskId, slug, origin }.
• API: POST /v1/tasks/:taskId/runs (tasks:write)

Example:

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

os.get_run

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

What the model reads:

One run's status, why it stopped (blockedReason, when it is blocked), task id and input, and its last eight events. Not found for another enterprise's run.

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: Status, blockedReason (why a blocked run stopped, otherwise null), task id, input and the last eight events.
• API: GET /v1/runs/:runId/os-tool (runs:read)

Example:

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

os.hand_off_task_brief

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

What the model reads:

Hand the brief the person agreed to over to the OS, which designs the new task from it and asks the CEO to sign off on its definition before anything is created. Call it once, only after they have said yes to your read-back summary, with every part of the brief in their own words. It starts the design and returns its run; it does not create the task.

No other fields are accepted.

• Effect: write.
• Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on the conversation and the tool call: the same call sent twice starts one run.
• Called by: the CEO chat, the API.
• Offered in: a conversation opened for create_task only, never in a member's everyday thread.
• Returns: { runId, status, taskId }: the run designing the task.
• API: POST /v1/tasks/from-brief (tasks:write)

Example:

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

os.list_runs

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

What the model reads:

List the enterprise's runs, newest first, one page at a time. Each run carries its status, task (id, name, slug), the member it runs as, its input, and when it was created, started and finished. The response is { data, total, page, limit, pages }.

No other fields are accepted.

• Effect: read.
• Retry: Safe: repeating the call changes nothing.
• Called by: the API, the OS MCP server.
• Returns: { data, total, page, limit, pages }, each run with its status, task, member, input and times.
• API: GET /v1/runs (runs:read)

Example:

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

os.kpi_board

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

What the model reads:

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

Takes no arguments: no fields are accepted.

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

os.list_enterprise_kpis

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

What the model reads:

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

Takes no arguments: no fields are accepted.

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

Example:

{}