MCP Tools Reference

Reference for the current OrgX MCP tools and migration aliases.

This page documents 78 current tools in the published catalog. The source catalog also records 19 migration aliases, listed separately below.

This reference is auto-generated from the MCP server source code and the discovery-first routing aliases used by public MCP clients. To regenerate: pnpm docs:generate-mdx

Tool Catalog Overview

Category	Tools	Description
Recommended Entry Points	4	approve_agent_work, delegate_agent_task, recall_memory, …
Decisions	4	approve_decision, get_decision_history, get_pending_decisions, …
Agents	4	get_agent_status, handoff_task, recommend_next_action, …
Initiative Monitoring	1	get_initiative_pulse
Entity Management	6	batch_create_entities, batch_delete_entities, comment_on_entity, …
Organization	1	get_org_snapshot
Planning	5	complete_plan, get_active_sessions, improve_plan, …
Scoring & Queue	1	get_scoring_signals
Streams	2	get_initiative_stream_state, update_stream_progress
Client Integration	8	check_spawn_guard, classify_task_model, consolidate_pr, …
Workspace	1	workspace
Onboarding	1	configure_org
Stats	1	stats
Intelligence Flywheel	6	get_morning_brief, get_my_trust_context, get_relevant_learnings, …
Billing	3	account_status, account_upgrade, account_usage_report
MCP v2 Public Surface	11	orgx_act, orgx_attach, orgx_bootstrap, …
Other	16	check_execution_readiness, configure_outcome_type, get_operator_chronicle, …
Proof Runtime v1	3	orgx_complete_work, orgx_create_work, orgx_events_tail

---

Recommended Entry Points

4 tools for recommended entry points operations.

approve_agent_work

Use when agent work is paused waiting for a human yes — review pending decisions, then approve or reject them. Also known as: pending approvals, agent blocked, sign off, review decisions, approve AI work.

decision_id · string

Decision ID to approve or reject after user confirmation

action · string

Use list to review pending approvals, or approve/reject a specific decision_id Options: list, approve, reject.

note · string

Optional approval note

reason · string

Required rejection reason

limit · number

Maximum number of pending decisions to return when listing

urgency_filter · string

Optional urgency filter for the pending decision list Options: all, critical, high.

initiative_id · string

Optional initiative UUID to scope pending decisions

Required Scopes: decisions:read, decisions:write

Profiles: memory

Request:

{
  "tool": "approve_agent_work",
  "args": {}
}

---

delegate_agent_task

Use when the user says “delegate this and tell me when it’s done” — assign work to a specialist AI agent that owns the task and reports back with results. Also known as: hand this off, spawn agent, assign task, delegate to agent, have an AI agent do it.

agent · string · required

Target agent identifier or alias

task · string · required

Task instructions for the target agent

context · string

Optional supporting context or background for the task

initiative_id · string

Optional initiative UUID to associate with the spawned task

initiative_name · string

Optional initiative title to resolve automatically if ID is unknown

expected_artifacts · string[]

Optional final outputs you expect

deadline · string

Optional due date or plain-text deadline

style_guidelines · string

Optional voice, format, or style constraints

Required Scopes: agents:write

Profiles: commander, executor, full

Request:

{
  "tool": "delegate_agent_task",
  "args": {
      "agent": "<agent_id>",
      "task": "task_value"
  }
}

---

recall_memory read-only

Use when the user asks “what did we decide about X” or prior context must be recovered from team memory. Searches organizational memory for prior decisions, artifacts, project context, and team knowledge. Also known as: search memory, recall decisions, find context, retrieve artifacts, what did we decide.

query · string · required

Search query for organizational memory

scope · string

Optional scope filter for the memory search Options: all, artifacts, decisions, initiatives.

limit · number

Maximum number of results to return

Required Scopes: memory:read

Profiles: memory

Request:

{
  "tool": "recall_memory",
  "args": {
      "query": "<search_query>"
  }
}

---

track_project_progress read-only

Use when the user asks how a project is going, what is blocked, or whether an initiative is on track. Returns health, blockers, milestones, owners, and recent activity. Also known as: project status, initiative pulse, blockers, roadmap progress, execution health.

initiative_id · string

Optional initiative UUID to check

initiative_name · string

Optional initiative title to resolve automatically if ID is unknown

Required Scopes: initiatives:read

Profiles: memory

Request:

{
  "tool": "track_project_progress",
  "args": {}
}

---

Decisions

4 tools for decisions operations.

approve_decision

Use when the user has reviewed a pending decision that is blocking agent work and gives explicit confirmation to approve it. Also known as: sign off, approve AI work, unblock agent, accept decision. USE WHEN: user says to approve a decision returned from the deprecated alias with type=decision and status=pending (or the legacy get_pending_decisions alias). Approval can resume or continue connected agent execution. NEXT: Confirm approval to user; agent is notified automatically. DO NOT USE: without showing the decision to the user first. Requires decisions:write.

decision_id · string · required

Decision ID to approve

note · string

Optional note recorded with the approval

option_id · string

Optional decision option id when the decision includes selectable options.

Required Scopes: decisions:write

Profiles: v2, chatgpt

Request:

{
  "tool": "approve_decision",
  "args": {
      "decision_id": "<decision_id>"
  }
}

Response:

{
  "decision_id": "dec_abc123",
  "status": "approved",
  "artifact_id": "art_xyz789",
  "resolved_at": "2026-02-26T10:05:00Z"
}

---

get_decision_history read-only

Recall past decisions about a topic, project, customer, feature, or artifact. Also known as: decision log, what did we decide, prior approvals. USE WHEN: older clients still call this tool directly. NEXT: Present results with context; suggest approve_decision or reject_decision if relevant pending ones exist. DO NOT USE: for new prompts or skills. Read-only. Compatibility alias retained for older clients. Prefer the deprecated alias with scope=decisions with a topic query for new prompts, skills, and examples.

topic · string · required

Topic or theme to search decision history for

initiative_id · string

Optional initiative UUID to scope decision history

limit · number

Maximum number of historical decisions to return

Required Scopes: decisions:read

Profiles: all

Request:

{
  "tool": "get_decision_history",
  "args": {
      "topic": "topic_value"
  }
}

Response:

{
  "decisions": [
    {
      "id": "dec_abc123",
      "type": "approval",
      "status": "approved",
      "resolved_by": "user_123",
      "resolved_at": "2026-02-26T10:05:00Z"
    }
  ],
  "total": 42,
  "cursor": "cur_next"
}

---

get_pending_decisions read-only

List agent decisions and work items awaiting human approval. Also known as: pending approvals, agent blocked, sign off, review decisions, approve AI work. USE WHEN: older clients still call this tool directly. NEXT: Present each decision with title and urgency, then ask which to approve_decision or reject_decision. DO NOT USE: for new prompts or skills. Read-only. Compatibility alias retained for older clients. Prefer the deprecated alias with type=decision and status=pending for new prompts, skills, and examples.

limit · number

Maximum number of decisions to return

urgency_filter · string

Optional urgency filter for the pending decision list Options: all, critical, high.

initiative_id · string

Optional initiative UUID to scope pending decisions

workspace_id · string

Optional workspace UUID to scope pending decisions

Required Scopes: decisions:read

Profiles: all

Request:

{
  "tool": "get_pending_decisions",
  "args": {}
}

Response:

{
  "decisions": [
    {
      "id": "dec_abc123",
      "type": "approval",
      "title": "Campaign brief ready for Q1 launch",
      "urgency": "high",
      "agent": "marketing-agent",
      "artifact_id": "art_xyz789",
      "created_at": "2026-02-26T10:00:00Z"
    }
  ],
  "total": 4,
  "cursor": null
}

---

reject_decision

Use when the user has reviewed a pending decision and wants to reject it or send the agent back with revisions. Also known as: request revisions, send feedback, decline decision. USE WHEN: user wants to reject or request revisions on a decision. NEXT: Agent will revise their approach based on the reason. DO NOT USE: without a reason — always include why. Requires decisions:write.

decision_id · string · required

Decision ID to reject

reason · string · required

Reason for rejecting the decision

option_id · string

Optional decision option id when the decision includes selectable options.

Required Scopes: decisions:write

Profiles: v2, chatgpt

Request:

{
  "tool": "reject_decision",
  "args": {
      "decision_id": "<decision_id>",
      "reason": "<reason>"
  }
}

Response:

{
  "decision_id": "dec_abc123",
  "status": "rejected",
  "resolved_at": "2026-02-26T10:05:00Z"
}

---

Agents

4 tools for agents operations.

get_agent_status

Use when the user asks what agents are working on right now, whether delegated work is still running, or why nothing has landed yet. Successful calls record metered MCP allowance usage but do not change business records. Also known as: agent status, what agents are doing, active runs. USE WHEN: user asks about agent activity, progress, or what agents are working on. NEXT: If agents are stuck, use orgx_search or orgx_inspect to read the related blocker context. DO NOT USE: to check initiative health — use get_initiative_pulse instead.

agent_id · string

Optional agent ID to inspect

workspace_id · string

Optional workspace UUID to scope agent status

command_center_id · string

Deprecated alias for workspace_id

initiative_id · string

Optional initiative UUID to scope agent status

include_idle · boolean

Include idle agents in the response

Required Scopes: agents:read

Profiles: v2, chatgpt, claude-plugin, read-only

Request:

{
  "tool": "get_agent_status",
  "args": {}
}

Response:

{
  "agent_type": "engineering-agent",
  "status": "idle",
  "current_task_id": null,
  "completed_tasks": 12,
  "trust_level": "act_with_approval"
}

---

handoff_task

Use when in-flight work must move to a different specialist agent without losing its context or execution state. Also known as: handoff task, transfer work, change assignee. USE WHEN: a task needs to be reassigned to a different specialist agent. NEXT: Use get_agent_status to confirm the new agent picked up the task. DO NOT USE: for new tasks — use spawn_agent_task instead.

task_id · string · required

Task UUID to hand off

agent · string · required

Target agent (e.g., “engineering-agent”, “marketing-agent”)

note · string

Handoff note: what to do, constraints, context, definition of done

spawn · boolean

If true (default), spawn a new agent run for the target agent

Required Scopes: agents:write, initiatives:write

Profiles: v2, chatgpt

Request:

{
  "tool": "handoff_task",
  "args": {
      "task_id": "<task_id>",
      "agent": "<agent_id>"
  }
}

Response:

{
  "task_id": "tsk_abc123",
  "from_agent": "product-agent",
  "to_agent": "engineering-agent",
  "status": "handed_off"
}

---

recommend_next_action read-only

Use this tool to recommend what should happen next after time away or when priority is unclear. It ranks progress gaps, blockers, and execution templates. Pass agent_id or domain for an agent-owned runnable queue instead of the workspace-wide operator queue. Also known as: next best action, prioritize work, unblock project. USE WHEN: the user asks what to do next or needs help prioritizing. NEXT: Execute the recommended action (the deprecated alias, spawn_agent_task, etc.). DO NOT USE: when the user already knows what they want to do. Read-only.

entity_type · string

Entity type to recommend for (default: workspace) Options: workspace, initiative, workstream, milestone.

entity_id · string

Entity ID. For workspace, use “default” or a workspace ID.

workspace_id · string

Optional workspace ID to scope recommendations (canonical).

command_center_id · string

Deprecated alias for workspace_id.

agent_id · string

Optional canonical agent ID. When present, only return work assigned to that agent.

domain · string

Optional agent domain used to derive the canonical agent ID when agent_id is omitted. Options: engineering, product, design, marketing, sales, operations, orchestration.

canonical_only · boolean

When true, return only the canonical next task linked to the active objective structure.

limit · number

Max recommendations to return (default 5, max 25)

cascade · boolean

If true, refresh recommendations across the entity chain first

Required Scopes: initiatives:read

Profiles: v2

Request:

{
  "tool": "recommend_next_action",
  "args": {}
}

Response:

{
  "recommendation": {
    "action": "approve_decision",
    "target_id": "dec_abc123",
    "confidence": 0.92
  }
}

---

spawn_agent_task

Use when the user says “delegate this and tell me when it’s done” — assign work to a specialist AI agent that owns the task and reports back with results. Also known as: hand this off, assign task, spawn agent, have an agent do it, autonomous work. Automatically checks authorization, rate limits, quality gates, model routing, and budget policy before spawning. Omit model_tier/provider/model to let OrgX auto-route from task complexity; provide them only when the user or verification plan intentionally constrains routing. Returns modelTier, budget, and run details on success, or blockedReason if spawn is denied. USE WHEN: user explicitly wants to delegate work to an agent. NEXT: Use get_agent_status to monitor progress and record_quality_score after reviewing output. DO NOT USE: for creating tasks in the hierarchy — use the deprecated alias type=task instead. Requires agents:write.

agent · string · required

Target agent identifier or alias

task · string · required

Task instructions for the target agent

context · string

Optional supporting context or background for the task

initiative_id · string

Optional initiative UUID to associate with the spawned task

initiative_name · string

Optional: Initiative title to resolve automatically if ID is unknown.

workstream_id · string

Optional workstream UUID. Bind the spawned run to an existing IWMT workstream so progress rolls up into the scaffolded hierarchy and the agent inherits workstream context (preferred over relying on domain resolution). Initiative is inferred from the workstream if initiative_id is omitted.

milestone_id · string

Optional milestone UUID under the workstream to bind the spawned run to.

task_id · string

Optional task UUID to bind the spawned run to a specific scaffolded task, enabling direct task-level progress rollup. Use the deprecated alias type=task first if the task does not exist yet.

expected_artifacts · string[]

Optional: Final outputs you expect (e.g., “PRD”, “10 ad images”).

deadline · string

Optional: When this is needed by (ISO date or plain text).

style_guidelines · string

Optional: Voice/format/style constraints for the agent.

wait_for_completion · boolean

Optional: If true and safe, wait briefly for the first result before replying.

model_tier · string

Optional model tier override. Omit to let OrgX auto-route according to task complexity. Use standard for controlled verification runs; use balanced or precision when explicitly selected by the user, policy, or routing decision. Legacy tiers local/sonnet/opus are accepted for older clients. Options: standard, balanced, precision, local, sonnet, opus.

model · string

Optional exact model identifier when the user explicitly chooses one. Omit to let OrgX resolve the model from task, tier, provider, policy, and budget.

provider · string

Optional provider preference. Use auto unless the user requests a specific provider or the budget/capability comparison has selected one. Options: auto, openai, anthropic, openrouter, groq, local.

budget_mode · string

Optional budget posture override. Omit to let OrgX apply workspace policy. Use cheapest_valid for controlled reliability/validation runs where cost must be pinned while the loop is being proven. Options: cheapest_valid, balanced, highest_quality.

max_cost_usd · number

Optional per-task hard cost ceiling in USD. If the estimate exceeds this, OrgX should block, downgrade, or ask for approval before dispatch.

execution_target · string

Where to execute: cloud (default), local (on your machine), local_preferred (try local first), or auto. Options: auto, cloud, local, local_preferred.

sdk_backend · string

Preferred execution backend. Use openai for cloud-safe execution, claude for Claude SDK routing, or auto to let OrgX decide. Options: auto, openai, claude.

Required Scopes: agents:write

Profiles: v2

Request:

{
  "tool": "spawn_agent_task",
  "args": {
      "agent": "<agent_id>",
      "task": "task_value"
  }
}

Response:

{
  "task_id": "tsk_new123",
  "agent_type": "engineering-agent",
  "status": "queued",
  "estimated_start": "2026-02-26T10:10:00Z"
}

---

Initiative Monitoring

1 tool for initiative monitoring operations.

get_initiative_pulse

Use when the user asks how a project is going, what is blocked, or whether an initiative is on track. Successful calls record metered MCP allowance usage but do not change business records. Also known as: project status, roadmap progress, execution health, blockers. USE WHEN: user asks how an initiative is going, or wants a status update. NEXT: If blockers exist, use orgx_inspect for one blocker or orgx_search for related records. DO NOT USE: for an org-wide brief — use orgx_recommend with mode=morning_brief instead.

initiative_id · string

Optional: Initiative UUID to check.

initiative_name · string

Optional: Initiative title to resolve automatically if ID is unknown.

Required Scopes: initiatives:read

Profiles: v2, chatgpt, claude-plugin, read-only

Request:

{
  "tool": "get_initiative_pulse",
  "args": {}
}

Response:

{
  "initiative_id": "init_abc123",
  "health": "on_track",
  "progress": 0.65,
  "active_workstreams": 3,
  "blocked_tasks": 0,
  "pending_decisions": 1,
  "last_activity": "2026-02-26T09:30:00Z"
}

---

Entity Management

6 tools for entity management operations.

batch_create_entities

Create multiple entities in one call with ref-based dependency resolution.

entities · object[] · required

Array of entities to create

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "batch_create_entities",
  "args": {
      "entities": []
  }
}

Response:

{
  "created": [
    {
      "ref": "task1",
      "id": "tsk_aaa",
      "type": "task"
    },
    {
      "ref": "task2",
      "id": "tsk_bbb",
      "type": "task"
    }
  ],
  "total": 2
}

---

batch_delete_entities

Delete multiple entities in one call. Supports cascade and force options.

ids · string[] · required

Entity IDs to delete

cascade · boolean

Also delete child entities

force · boolean

Force delete even if entity has active children

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "batch_delete_entities",
  "args": {
      "ids": []
  }
}

Response:

{
  "deleted": [
    "tsk_aaa",
    "tsk_bbb"
  ],
  "total": 2
}

---

comment_on_entity

Leave a threaded comment on an entity for annotations, concerns, or progress notes.

entity_id · string · required

Entity ID to comment on

body · string · required

Comment body (markdown supported)

parent_comment_id · string

Reply to a specific comment

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "comment_on_entity",
  "args": {
      "entity_id": "<entity_id>",
      "body": "<message_body>"
  }
}

Response:

{
  "comment_id": "cmt_abc123",
  "entity_id": "tsk_abc123",
  "body": "Looking good so far!",
  "created_at": "2026-02-26T10:00:00Z"
}

---

list_entity_comments read-only

List comments for an entity. Returns threaded discussion.

entity_id · string · required

Entity ID

limit · number

Max comments to return

Required Scopes: initiatives:read

Profiles: all

Request:

{
  "tool": "list_entity_comments",
  "args": {
      "entity_id": "<entity_id>"
  }
}

Response:

{
  "comments": [
    {
      "id": "cmt_abc123",
      "body": "Looking good!",
      "author": "user_123",
      "created_at": "2026-02-26T10:00:00Z"
    }
  ],
  "total": 1
}

---

scaffold_initiative

Create a complete initiative with workstreams, milestones, and tasks in one call.

title · string · required

Initiative title

summary · string

Initiative summary

workstreams · object[]

Workstream definitions with nested tasks

milestones · object[]

Milestone definitions

auto_launch · boolean

Auto-launch initiative after creation (default: true)

Required Scopes: initiatives:write

Profiles: v2, chatgpt, commander, planner

Request:

{
  "tool": "scaffold_initiative",
  "args": {
      "title": "<title>"
  }
}

Response:

{
  "initiative": {
    "id": "init_new789",
    "title": "<initiative_title>",
    "status": "active"
  },
  "workstreams": [
    {
      "id": "ws_001",
      "title": "Frontend"
    }
  ],
  "milestones": [
    {
      "id": "ms_001",
      "title": "Beta launch"
    }
  ],
  "tasks": [
    {
      "id": "tsk_001",
      "title": "Build hero section"
    }
  ],
  "total_entities_created": 5
}

---

update_entity

Update entity fields (title, description, metadata). For status changes, use the deprecated alias.

type · string · required

Entity type Options: workspace, project, initiative, milestone, workstream, task, objective, playbook, decision, artifact, run, blocker, workflow, agent, skill, plan_session, stream, studio_brand, studio_content, video_template.

id · string · required

Entity ID

title · string

New title

description · string

New description

metadata · object

Metadata fields to merge

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "update_entity",
  "args": {
      "type": "workspace",
      "id": "id_value"
  }
}

Response:

{
  "id": "tsk_abc123",
  "type": "task",
  "title": "Updated title",
  "updated_at": "2026-02-26T10:00:00Z"
}

---

Organization

1 tool for organization operations.

get_org_snapshot read-only

Fetch a compact organization snapshot. Returns org-wide overview of initiatives, progress, and health.

view · string

Response view mode (default: summary). Options: summary, detailed.

initiative_status · string

Filter initiatives by status. Options: active, paused, all.

include · string[]

Detailed mode payload sections.

limit · number

Max initiatives to return (default: 20, max: 100).

cursor · string

Pagination cursor from a previous result.

Required Scopes: initiatives:read

Profiles: all

Request:

{
  "tool": "get_org_snapshot",
  "args": {}
}

Response:

{
  "workspace": "My Startup",
  "initiatives": {
    "total": 3,
    "active": 2,
    "completed": 1
  },
  "pending_decisions": 4,
  "active_agents": 2,
  "recent_artifacts": 7
}

---

Planning

5 tools for planning operations.

complete_plan

Complete a planning session and attach implementation details to durable work context. Also known as: finish plan, implementation record, planning handoff. USE WHEN: user finishes building the planned feature. NEXT: Optionally attach to entities via attach_to. DO NOT USE: if the plan session is still in progress.

session_id · string · required

Plan session ID

implementation_summary · string

Summary of what was built

files_changed · string[]

List of files modified

deviations · object[]

Any deviations from the plan

attach_to · object[]

Optional: attach this plan session as context on target entities (pointers, not payloads).

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "complete_plan",
  "args": {
      "session_id": "<session_id>"
  }
}

Response:

{
  "session_id": "ps_abc123",
  "status": "completed",
  "entities_created": 8,
  "completed_at": "2026-02-26T10:10:00Z"
}

---

get_active_sessions read-only

Find active planning sessions so agents can continue prior planning context. Also known as: resume planning, active plans, planning memory. USE WHEN: resuming a conversation or checking if a plan session exists. NEXT: Continue with improve_plan or complete_plan. Read-only.

No parameters required.

Required Scopes: agents:read

Profiles: all

Request:

{
  "tool": "get_active_sessions",
  "args": {}
}

Response:

{
  "sessions": [
    {
      "id": "ps_abc123",
      "initiative_id": "init_abc123",
      "status": "active",
      "created_at": "2026-02-26T10:00:00Z"
    }
  ]
}

---

improve_plan

Improve a plan with AI suggestions based on prior patterns and best practices. Also known as: plan critique, planning feedback, refine roadmap. USE WHEN: user wants feedback on a plan draft. NEXT: Apply suggestions via record_plan_edit. DO NOT USE: without an active plan session — call start_plan_session first.

session_id · string · required

Plan session ID

plan_content · string · required

Current plan content to analyze

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "improve_plan",
  "args": {
      "session_id": "<session_id>",
      "plan_content": "plan_content_value"
  }
}

Response:

{
  "session_id": "ps_abc123",
  "suggestions": [
    {
      "type": "add_task",
      "workstream": "Frontend",
      "title": "Add responsive breakpoints"
    }
  ]
}

---

record_plan_edit

Record a plan edit so OrgX can preserve planning context and learn patterns. Also known as: save plan change, plan memory, planning history. USE WHEN: user modifies their plan during a session. NEXT: Continue editing or call improve_plan for more suggestions. DO NOT USE: without an active plan session.

session_id · string · required

Plan session ID

edit_type · string · required

Type of edit made Options: add_section, remove_section, modify_section, add_detail, change_approach, add_edge_case, add_constraint, reorder, other.

before_content · string

Content before edit

after_content · string · required

Content after edit

section_path · string

Section path like ”## API Design”

user_reason · string

Why this edit was made

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "record_plan_edit",
  "args": {
      "session_id": "<session_id>",
      "edit_type": "add_section",
      "after_content": "after_content_value"
  }
}

Response:

{
  "session_id": "ps_abc123",
  "edit_id": "ed_001",
  "recorded_at": "2026-02-26T10:05:00Z"
}

---

start_plan_session

Start a multi-agent planning session that breaks a goal into projects, tasks, owners, and agent assignments. Also known as: feature planning, roadmap planning, planning workflow. USE WHEN: user begins planning a new feature or initiative. NEXT: Use improve_plan for suggestions, record_plan_edit to track changes, complete_plan when done. DO NOT USE: for creating initiative hierarchies — use scaffold_initiative instead.

feature_name · string · required

Name of the feature being planned

initial_plan · string

Initial plan content if any

workspace_id · string

Workspace UUID to scope the planning session. Defaults to current session workspace when omitted.

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "start_plan_session",
  "args": {
      "feature_name": "feature_name_value"
  }
}

Response:

{
  "session_id": "ps_abc123",
  "initiative_id": "init_abc123",
  "status": "active",
  "created_at": "2026-02-26T10:00:00Z"
}

---

Scoring & Queue

1 tool for scoring & queue operations.

get_scoring_signals read-only

Show raw signal data (blocking decisions, stream conflicts, health, budget, critical path, quality) for scoring. USE WHEN: user wants to understand why items are ranked the way they are in the deprecated alias. NEXT: Adjust with set_scoring_weights if weights need tuning. Read-only.

initiative_id · string · required

Initiative UUID to gather signals for

workstream_id · string

Optional: filter to a specific workstream

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "get_scoring_signals",
  "args": {
      "initiative_id": "<initiative_id>"
  }
}

Response:

{
  "signals": [
    {
      "name": "urgency",
      "weight": 0.3,
      "description": "Time sensitivity based on deadlines"
    },
    {
      "name": "impact",
      "weight": 0.25,
      "description": "Business value"
    }
  ]
}

---

Streams

2 tools for streams operations.

get_initiative_stream_state read-only

Get execution stream progress, blockers, and computed metrics for an initiative. Also known as: project stream state, execution health, workstream progress. USE WHEN: checking stream execution status for an initiative. NEXT: If streams are blocked, use the deprecated alias to unblock. DO NOT USE: for raw stream records — use the deprecated alias type=stream instead. Read-only.

initiative_id · string · required

The initiative ID

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "get_initiative_stream_state",
  "args": {
      "initiative_id": "<initiative_id>"
  }
}

Response:

{
  "initiative_id": "init_abc123",
  "streams": [
    {
      "id": "str_abc123",
      "workstream": "Frontend",
      "progress": 0.75,
      "status": "active"
    }
  ]
}

---

update_stream_progress

Report progress and confidence on a stream with velocity tracking. USE WHEN: agent is actively working a stream and needs to report progress. NEXT: Continue work; call again at each meaningful progress change. DO NOT USE: for general entity status changes — use the deprecated alias instead.

stream_id · string · required

The stream ID to update

progress_pct · number

Progress percentage (0-100)

confidence · number

Confidence level (0-1) - separate from progress

status_note · string

Brief note about current status

expected_version · number

For optimistic locking

Required Scopes: agents:write

Profiles: all

Request:

{
  "tool": "update_stream_progress",
  "args": {
      "stream_id": "stream_id_value"
  }
}

Response:

{
  "stream_id": "str_abc123",
  "progress": 0.75,
  "updated_at": "2026-02-26T10:00:00Z"
}

---

Client Integration

8 tools for client integration operations.

check_spawn_guard read-only

Check whether agent delegation is allowed before assigning work. Also known as: spawn guard, delegation authorization, agent rate limit. Returns model tier, rate limit status, quality gate, and task verification. USE WHEN: before any spawn_agent_task call. NEXT: If allowed, proceed with spawn_agent_task using the returned model tier. If blocked, inform user of the reason.

domain · string · required

Agent domain: engineering, marketing, product, design, ops, sales, orchestration

task_id · string

OrgX task ID this spawn is for

task_title · string

Task title (for model routing if task_id not provided)

task_description · string

Task description

Required Scopes: agents:read

Profiles: all

Request:

{
  "tool": "check_spawn_guard",
  "args": {
      "domain": "domain_value"
  }
}

Response:

{
  "allowed": true,
  "trust_level": "act_with_approval",
  "budget_remaining_usd": 4.5
}

---

classify_task_model read-only

Classify a task and get pre-spawn model routing context. Also known as: estimate task cost, model routing estimate, cost frontier, route task. USE WHEN: deciding which model/budget posture to use before agent work. Returns the recommended tier and, when the backend can compute it, estimated tokens/cost and candidate route comparisons. NEXT: Use the returned tier or cost frontier when spawning via spawn_agent_task. Read-only.

title · string · required

Task title

description · string

Task description

entity_type · string

Entity type: task, decision, initiative

domain · string

Agent domain

model_tier · string

Optional tier to estimate. Omit to let OrgX auto-route. Options: standard, balanced, precision, local, sonnet, opus.

provider · string

Optional provider preference for the estimate. Use auto unless explicitly selected. Options: auto, openai, anthropic, openrouter, groq, local.

budget_mode · string

Optional budget posture for the estimate. Use cheapest_valid for controlled validation runs only. Options: cheapest_valid, balanced, highest_quality.

max_cost_usd · number

Optional per-task hard cost ceiling to compare against the estimate.

estimate_only · boolean

When true, return pre-spawn estimate context without dispatching work.

Required Scopes: agents:read

Profiles: all

Request:

{
  "tool": "classify_task_model",
  "args": {
      "title": "<title>"
  }
}

Response:

{
  "task_id": "tsk_abc123",
  "recommended_model": "claude-sonnet-4-6"
}

---

consolidate_pr

Use when the user or an engineering agent must show a pull request actually shipped and needs durable review proof, not a status glance. Generate and persist an orchestration.consolidation_pass receipt for a GitHub pull request. Requires OrgX server-side GitHub credentials; if the GitHub token is unavailable, use GitHub tools for PR facts and return a structured blocker instead of retrying. USE WHEN: Eli or another engineering agent needs a durable PR review receipt with reading order, existence evidence, deduped findings, verdict, and server-derived AQ score. NEXT: inspect the returned artifact_id or attach it to task completion proof. DO NOT USE WHEN: only asking for PR status; use GitHub tools instead.

pr_url · string · required

GitHub pull request URL, e.g. https://github.com/org/repo/pull/123. OrgX must have server-side GitHub credentials to inspect it.

workspace_id · string

OrgX workspace UUID

initiative_id · string

Initiative to attach the consolidation_pass artifact to

task_id · string

Task to attach the consolidation_pass artifact to

decision_id · string

Decision to attach the consolidation_pass artifact to

commit_sha · string

Override commit SHA for idempotency; defaults to merge commit or PR head SHA

verdict · string

Optional verdict override; defaults from PR state Options: ship, simplify_first, escalate.

reviewer_note · string

Optional reviewer note to include in critic evidence

Required Scopes: initiatives:write

Profiles: v2, commander, executor

Request:

{
  "tool": "consolidate_pr",
  "args": {
      "pr_url": "pr_url_value"
  }
}

---

orgx_apply_changeset

Apply an idempotent transactional changeset for task/milestone/decision mutations. USE WHEN: agent needs to create/update multiple tasks, milestones, or decisions atomically. NEXT: Call orgx_emit_activity to log what was changed. DO NOT USE: for single entity updates — use the deprecated alias or update_entity instead.

initiative_id · string · required

Initiative UUID

idempotency_key · string · required

Idempotency key for safe retries

operations · object[] · required

Ordered task, milestone, and decision mutations to apply atomically

run_id · string

Existing run UUID

correlation_id · string

Required when run_id is not provided

source_client · string

Required when run_id is not provided Options: openclaw, codex, claude-code, chatgpt, cursor, copilot, gemini, opencode, cline, goose, qwen, kiro, web-ui, api.

runtime · object

Runtime provenance used by /live to bucket cloud, local, Anthropic, managed, and OpenClaw changeset decisions

Required Scopes: agents:write, initiatives:write

Profiles: all

Request:

{
  "tool": "orgx_apply_changeset",
  "args": {
      "initiative_id": "<initiative_id>",
      "idempotency_key": "idempotency_key_value",
      "operations": []
  }
}

Response:

{
  "applied": true,
  "changeset_id": "cs_abc123",
  "entities_affected": 3
}

---

orgx_emit_activity

Use when an agent is mid-execution and its progress must stay visible to operators and to the next agent that resumes the run. Emit append-only run telemetry for OrgX control-plane reporting. USE WHEN: agent is executing and needs to report progress. NEXT: Continue work; emit again at each phase change. DO NOT USE: for entity status changes — use the deprecated alias instead. Setting phase=“completed” records telemetry only and does not mark tasks, workstreams, or initiatives complete.

initiative_id · string · required

Initiative UUID

message · string · required

Human-readable activity update

run_id · string

Existing run UUID

correlation_id · string

Required when run_id is not provided

source_client · string

Required when run_id is not provided Options: openclaw, codex, claude-code, chatgpt, cursor, copilot, gemini, opencode, cline, goose, qwen, kiro, web-ui, api.

phase · string

Optional reporting phase for the activity event Options: intent, execution, blocked, review, handoff, completed.

progress_pct · number

Optional progress percentage associated with this activity

level · string

Optional severity level for the activity event Options: info, warn, error.

next_step · string

Optional next step to surface after this activity event

metadata · object

Optional structured metadata to attach to the activity event

runtime · object

Runtime provenance used by /live to bucket cloud, local, Anthropic, managed, and OpenClaw chokepoints

chokepoint · object

Durable blocker/stall/error/approval to surface in /live when execution cannot proceed

Required Scopes: initiatives:write

Profiles: v2, claude-plugin, executor

Request:

{
  "tool": "orgx_emit_activity",
  "args": {
      "initiative_id": "<initiative_id>",
      "message": "message_value"
  }
}

Response:

{
  "emitted": true,
  "activity_id": "act_abc123"
}

---

record_quality_score

Record a quality score (1-5) for a completed agent task. Scores feed into the quality gate — low-scoring domains get throttled. USE WHEN: after reviewing agent output. NEXT: Scores affect future check_spawn_guard decisions. DO NOT USE: for in-progress tasks — wait until completion.

task_id · string

OrgX task ID (snake_case alias; taskId also accepted)

taskId · string

OrgX task ID (backend/camelCase alias)

agent_domain · string

Agent domain that completed the task (agentDomain/domain also accepted)

agentDomain · string

Agent domain that completed the task (backend/camelCase alias)

domain · string

Short alias for agentDomain

score · number · required

Quality score: 1=poor, 3=acceptable, 5=excellent

scored_by · string

Who scored this (snake_case alias; scoredBy also accepted) Options: human, auto, peer.

scoredBy · string

Who scored this (backend/camelCase alias) Options: human, auto, peer.

notes · string

Notes on the score

Required Scopes: decisions:write

Profiles: all

Request:

{
  "tool": "record_quality_score",
  "args": {
      "score": 10
  }
}

Response:

{
  "recorded": true,
  "entity_id": "tsk_abc123",
  "score": 0.88
}

---

review_artifact read-only

Use when the user asks to review work, sign off on a deliverable, or clear pending artifact reviews. Surfaces the next artifact awaiting review and renders the artifact-review widget with a preview, version filmstrip, and hold-to-approve / request-changes actions. USE WHEN the user asks to review work, approve a deliverable, or handle pending artifact reviews. DO NOT USE for listing all artifacts — use the deprecated alias type=artifact instead.

artifact_id · string

Specific artifact ID to review. Defaults to the next in_review artifact.

entity_id · string

Scope to artifacts attached to this entity (initiative, workstream, milestone, or task).

workspace_id · string

Workspace UUID. Defaults to the session workspace.

Required Scopes: initiatives:read

Profiles: v2, chatgpt

Request:

{
  "tool": "review_artifact",
  "args": {}
}

---

sync_client_state

Sync local agent context with OrgX organizational memory. Also known as: push session memory, pull project context, cross-tool continuity. Push decisions/logs, pull active context. USE WHEN: at session start and periodically during long sessions. NEXT: Review returned initiatives and pending decisions, ask user what to focus on. USE BEFORE: spawning agent work, to ensure latest state.

memory · string

Local MEMORY.md content to push

daily_log · string

Today’s session log to push

Required Scopes: decisions:write, initiatives:write, memory:read

Profiles: all

Request:

{
  "tool": "sync_client_state",
  "args": {}
}

Response:

{
  "synced": true,
  "last_sync": "2026-02-26T10:00:00Z",
  "pending_changes": 0
}

---

Workspace

1 tool for workspace operations.

workspace

Create, list, inspect, or switch the active OrgX workspace for shared memory and project context. Also known as: create workspace, workspace context, team scope, organization scope. USE WHEN: user wants to create a workspace, see workspaces, check which is active, or switch workspaces. action=create creates a workspace and sets it active by default; action=list to see all; action=get for current; action=set to switch.

action · string · required

list=show all, get=current, set=switch active, create=new workspace Options: list, get, set, create.

workspace_id · string

Workspace UUID to switch to (action=set only)

name · string

Workspace name (action=create)

title · string

Alias for name (action=create)

description · string

Workspace narrative/description (action=create)

tagline · string

Short workspace tagline (action=create)

narrative · string

Workspace identity narrative (action=create)

key_metrics · string[]

Workspace identity metrics (action=create)

roadmap_url · string

Roadmap URL (action=create)

source_links · string[]

Source links for workspace identity (action=create)

set_active · boolean

Whether to make the new workspace active. Defaults true.

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "workspace",
  "args": {
      "action": "list"
  }
}

Response:

{
  "workspace_id": "ws_abc123",
  "name": "My Startup",
  "plan": "team",
  "created_at": "2025-10-01T00:00:00Z"
}

---

Onboarding

1 tool for onboarding operations.

configure_org

Check organizational setup, configure agents, or set AI operating policies. Also known as: onboarding, agent policy, organization setup. USE WHEN: first connecting, onboarding, or adjusting agent/policy settings. action=status for progress, action=configure_agent to set agent preferences, action=set_policy for org-wide rules.

action · string · required

Configuration operation Options: status, configure_agent, set_policy.

agent_type · string

Agent type (configure_agent only) Options: product, engineering, marketing, sales, operations, design, orchestrator.

trust_level · string

Agent autonomy level (configure_agent only) Options: strict, balanced, autonomous.

focus_areas · string[]

Agent focus areas (configure_agent only)

approval_required · string[]

Actions requiring approval (configure_agent only)

skip_approval · string[]

Actions without approval (configure_agent only)

policy_type · string

Policy type (set_policy only) Options: approvals, notifications, working_hours, budget, artifact_collection.

config · object

Policy configuration (set_policy only)

workspace_id · string

Workspace UUID to scope policy overrides (set_policy only)

command_center_id · string

Deprecated alias for workspace_id (set_policy only)

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "configure_org",
  "args": {
      "action": "status"
  }
}

Response:

{
  "workspace_id": "ws_abc123",
  "steps": {
    "linear_connected": true,
    "github_connected": false,
    "first_initiative": true,
    "first_decision": false
  },
  "completion": 0.5
}

---

Stats

1 tool for stats operations.

stats read-only

Get execution statistics, achievements, and session diagnostics. Also known as: usage stats, productivity report, session status. scope=personal for your stats, scope=session for current session diagnostics. Read-only.

scope · string

personal=your stats, session=current session diagnostics Options: personal, session. Default: "personal".

timeframe · string

Time period for stats (personal only) Options: today, week, month, all_time.

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "stats",
  "args": {}
}

Response:

{
  "period": "30d",
  "decisions_resolved": 42,
  "artifacts_shipped": 18,
  "agents_spawned": 7,
  "avg_decision_time_hours": 2.3
}

---

Intelligence Flywheel

6 tools for intelligence flywheel operations.

get_morning_brief read-only

Use when the user asks ‘what happened,’ ‘catch me up,’ or starts a session after time away. Returns the morning brief: curated receipts, exceptions, ROI delta, and value signals from the most recent autonomous session. Defaults to the most recent session if no session ID is provided. Prefer get_morning_brief with workspace brief with value and exception summaries for new prompts, skills, and examples.

workspace_id · string · required

Workspace ID

session_id · string

Specific session ID (defaults to most recent)

Required Scopes: initiatives:read

Profiles: v2, chatgpt, claude-plugin, read-only

Request:

{
  "tool": "get_morning_brief",
  "args": {
      "workspace_id": "<workspace_id>"
  }
}

Response:

{
  "session_id": "auto_abc123",
  "summary": "7 tasks completed, 2 decisions pending review",
  "tasks_completed": 7,
  "decisions_created": 2,
  "total_cost_usd": 2.15,
  "artifacts": [
    "art_001",
    "art_002"
  ]
}

---

get_my_trust_context read-only

Use when an agent asks “what am I trusted to do, what do I need for promotion, and which receipts are helping or hurting?” Returns the full trust context for an agent including per-capability levels, scores, thresholds, and recent trust events.

workspace_id · string · required

Workspace ID

agent_type · string · required

Agent type to query trust for

Required Scopes: agents:read

Profiles: all

Request:

{
  "tool": "get_my_trust_context",
  "args": {
      "workspace_id": "<workspace_id>",
      "agent_type": "<agent_type>"
  }
}

Response:

{
  "agent_type": "engineering-agent",
  "trust_level": "act_with_approval",
  "capabilities": {
    "read_code": "autonomous",
    "create_pr": "act_with_approval",
    "merge_pr": "draft"
  },
  "promotion_progress": 0.7
}

---

get_relevant_learnings read-only

Use when an agent is about to attempt work the org may already have learned something about. Answers “what has the org learned about my capability?” Returns ranked org learnings relevant to a specific capability or task context.

workspace_id · string · required

Workspace ID

capability_key · string

Capability key to filter learnings

keywords · string[]

Keywords for semantic matching

limit · integer

Maximum number of learnings to return Default: 5.

Required Scopes: memory:read

Profiles: all

Request:

{
  "tool": "get_relevant_learnings",
  "args": {
      "workspace_id": "<workspace_id>"
  }
}

Response:

{
  "learnings": [
    {
      "id": "lrn_abc123",
      "pattern": "Auth bugs often stem from token refresh race conditions",
      "source_task": "tsk_xyz",
      "confidence": 0.85
    }
  ]
}

---

record_outcome

Use when a business outcome lands — deal closed, meeting booked, cycle time reduced — and it must be credited to the work that produced it. Agents can self-report outcomes they detect. Triggers attribution inference to connect outcomes to receipts. If the outcome type is unknown, call configure_outcome_type first.

workspace_id · string

Workspace ID

workspaceId · string

CamelCase alias for workspace_id

outcome_type_key · string

Outcome type key: deal_closed, meeting_booked, etc.

outcomeTypeKey · string

CamelCase alias for outcome_type_key

outcome_value · number

Value in the outcome type unit (e.g., USD amount)

outcomeValue · number

CamelCase alias for outcome_value

source · string

Source that observed or reported the outcome Options: manual, agent_self_report, crm_webhook, linear_sync. Default: "manual".

source_id · string

External source ID for deduplication

sourceId · string

CamelCase alias for source_id

occurred_at · string

ISO datetime when the outcome occurred

occurredAt · string

CamelCase alias for occurred_at

metadata · object

Additional context

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "record_outcome",
  "args": {}
}

Response:

{
  "outcome_id": "out_abc123",
  "entity_id": "tsk_abc123",
  "recorded_at": "2026-02-26T10:00:00Z"
}

---

start_autonomous_session

Use when the user says “run overnight with $5 budget” or wants eligible work executed unattended within guardrails. Starts an autonomous execution session that produces receipts while executing eligible work items.

workspace_id · string · required

Workspace ID.

session_type · string

Autonomy session mode to start. Options: overnight, weekend, scheduled, manual. Default: "manual".

max_cost_usd · number

Maximum budget in USD before the session stops. Default: 10.

max_receipts · integer

Maximum number of receipts the session may produce. Default: 100.

allowed_trust_levels · string[]

Only execute capabilities at these trust levels. Default: ["autonomous","act_with_approval"].

Required Scopes: agents:write

Profiles: all

Request:

{
  "tool": "start_autonomous_session",
  "args": {
      "workspace_id": "<workspace_id>"
  }
}

Response:

{
  "session_id": "auto_abc123",
  "max_cost_usd": 5,
  "max_receipts": 50,
  "started_at": "2026-02-26T22:00:00Z"
}

---

submit_learning

Use when an agent discovers a pattern worth teaching the whole org — a failure mode, success pattern, cost optimization, or quality heuristic. Submits it as an org learning; enters org_learnings after confidence validation. One agent’s discovery benefits all agents.

workspace_id · string · required

Workspace ID

learning_type · string · required

Type of learning Options: failure_pattern, success_pattern, cost_optimization, quality_heuristic.

summary · string · required

Human-readable learning summary

capability_key · string

Applicable capability key

evidence_receipt_ids · string[]

Receipt IDs that support this learning

keywords · string[]

Semantic keywords for matching

Required Scopes: memory:read

Profiles: all

Request:

{
  "tool": "submit_learning",
  "args": {
      "workspace_id": "<workspace_id>",
      "learning_type": "failure_pattern",
      "summary": "summary_value"
  }
}

Response:

{
  "learning_id": "lrn_new123",
  "submitted_at": "2026-02-26T10:00:00Z",
  "status": "accepted"
}

---

Billing

3 tools for billing operations.

account_status read-only

Returns account tier, usage, and current edge rate-limit allowance.

No parameters required.

Required Scopes: Authenticated user

Profiles: all

Request:

{
  "tool": "account_status",
  "args": {}
}

Response:

{
  "user_id": "usr_abc123",
  "plan": "free",
  "tier": "free",
  "rate_limit_status": {
    "window": "1h",
    "limit_per_hour": 100,
    "remaining": 92
  }
}

---

account_upgrade

Starts an account upgrade flow and returns checkout/contact URL.

target_plan · string

Target plan to upgrade to. Options: pro, enterprise.

billing_cycle · string

Billing cycle preference. Options: monthly, annual.

Required Scopes: Authenticated user

Profiles: all

Request:

{
  "tool": "account_upgrade",
  "args": {}
}

Response:

{
  "target_plan": "pro",
  "billing_cycle": "monthly",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_abc123"
}

---

account_usage_report read-only

Returns billing usage details with current edge rate-limit usage.

No parameters required.

Required Scopes: Authenticated user

Profiles: all

Request:

{
  "tool": "account_usage_report",
  "args": {}
}

Response:

{
  "user_id": "usr_abc123",
  "plan": "free",
  "usage": {
    "creditsUsed": 15,
    "creditsIncluded": 100
  },
  "edge_rate_limit": {
    "window": "1h",
    "limit_per_hour": 100,
    "remaining": 92
  }
}

---

MCP v2 Public Surface

11 tools for mcp v2 public surface operations.

orgx_act

Act on one OrgX entity. Required inputs: • update → “fields” patch object. • complete_with_proof, ship_batch → “artifact” (artifact_type + artifact_url/external_url; preview_markdown optional). • validate (studio) → “spec” payload. • block, flag_risk, decline, cancel, delete → “note” strongly recommended. • dry_run=true previews supported actions; update dry-runs must return would_update.

Allowed (type → action) pairs (others return an error): workspace: update|delete initiative: launch|pause|resume|complete|archive|update|delete milestone: start|complete|flag_risk|cancel|ship_batch|update|delete workstream: start|pause|resume|block|complete|reassign_streams|update|delete task: start|complete|complete_with_proof|block|unblock|reopen|update|delete objective, playbook, decision, studio: see field descriptions.

USE WHEN: changing entity state. Launch and resume can dispatch connected agent work. For pause, resume, retry, or cancel of running work, use manage_lifecycle so descendant tasks and active runs stay synchronized. NEXT: orgx_submit_receipt for durable proof. DO NOT USE for creating records — use orgx_write.

type · string · required

Target entity type (workspace, initiative, milestone, workstream, task, objective, playbook, decision, or studio). Options: workspace, initiative, milestone, workstream, task, objective, playbook, decision, stream, studio_content.

id · string · required

Target entity UUID or short ID prefix (8+ hex chars).

action · string · required

Lifecycle action to execute on the target entity. Must be valid for the given type — see tool description for the (type → action) matrix. Options: launch, pause, resume, complete, complete_with_proof, archive, start, flag_risk, cancel, block, unblock, reopen, activate, approve, decline, supersede, update, delete, validate, ship_batch, reassign_streams.

fields · object

REQUIRED when action=update. Map of entity fields to patch (e.g. { name?: string, description?: string, owner_id?: string, status?: string, due_date?: string }). Only include fields you want to change.

note · string

Strongly recommended for destructive or blocking actions (block, flag_risk, decline, supersede, cancel, delete). Free-text rationale shown in audit history and downstream agent context.

dry_run · boolean

Preview update/delete or supported lifecycle actions without mutating. For action=update this returns would_update and must not delegate to orgx_write.

force · boolean

Force action where server supports override semantics (skips pre-flight checks).

spec · object

REQUIRED when action=validate. Spec payload for studio validation (shape varies per studio entity subtype).

artifact · object

REQUIRED when action=complete_with_proof or action=ship_batch. Proof artifact payload. Expected shape: { artifact_type: string, artifact_url?: string, external_url?: string, preview_markdown?: string, name?: string, description?: string }. Either artifact_url or external_url is required; preview_markdown alone is rejected. Preferred founder/team artifact examples: orchestration.next_initiative, eng.pull_request, eng.deploy_proof, eng.structured_blocker, sales.strategy, sales.icp_offer_sequence, sales.send_plan, sales.conversion_gates, marketing.launch_asset, marketing.channel_hypothesis, marketing.positioning_brief, marketing.proof_distribution_plan, marketing.interview_pr_plan, product.customer_discovery, product.prd, product.pricing_hypothesis, product.decision_record, design.audit, design.component_spec, design.token_package, ops.operator_brief, ops.runbook, ops.budget_envelope, ops.incident_status, proof.link.

verification · string[]

Optional list of verification evidence URLs/IDs for completion flows.

quality_score · number

Quality score (0-5) attached to the action when used in proof/completion flows.

idempotency_key · string

Optional client-supplied retry key. Update requests transport it outside validated entity fields; lifecycle endpoints deduplicate where supported.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: decisions:write, agents:write, initiatives:write

Profiles: v2, chatgpt, commander, planner, executor

Request:

{
  "tool": "orgx_act",
  "args": {
      "type": "workspace",
      "id": "id_value",
      "action": "launch"
  }
}

---

orgx_attach

Use when work produced a deliverable that needs provenance and review — attach the artifact or proof URL to an OrgX entity. Requires artifact_url or external_url; preview_markdown is supporting context only. USE WHEN: saving evidence, PRs, documents, reports, screenshots, or external artifacts. For founder/team work, prefer practical artifact_type codes such as orchestration.next_initiative, eng.pull_request, eng.deploy_proof, eng.structured_blocker, sales.strategy, sales.icp_offer_sequence, sales.send_plan, sales.conversion_gates, marketing.launch_asset, marketing.channel_hypothesis, marketing.positioning_brief, marketing.proof_distribution_plan, marketing.interview_pr_plan, product.customer_discovery, product.prd, product.pricing_hypothesis, product.decision_record, design.audit, design.component_spec, design.token_package, ops.operator_brief, ops.runbook, ops.budget_envelope, ops.incident_status, proof.link. Include business_outcome, owner/review_date, and verification when the artifact should close agent work. NEXT: use orgx_submit_receipt to close attribution/quality loops or orgx_act to complete with proof. DO NOT USE WHEN: creating generic entities; use orgx_write.

type · string · required

Target entity type Options: workspace, initiative, milestone, workstream, task, objective, playbook, decision, stream, studio_content.

id · string · required

Target entity UUID or short ID prefix

name · string · required

Artifact title

artifact_type · string · required

Artifact type code. Preferred founder/team examples: orchestration.next_initiative, eng.pull_request, eng.deploy_proof, eng.structured_blocker, sales.strategy, sales.icp_offer_sequence, sales.send_plan, sales.conversion_gates, marketing.launch_asset, marketing.channel_hypothesis, marketing.positioning_brief, marketing.proof_distribution_plan, marketing.interview_pr_plan, product.customer_discovery, product.prd, product.pricing_hypothesis, product.decision_record, design.audit, design.component_spec, design.token_package, ops.operator_brief, ops.runbook, ops.budget_envelope, ops.incident_status, proof.link. Custom codes remain accepted.

artifact_url · string

Internal artifact URL. REQUIRED unless external_url is provided; preview_markdown alone is rejected.

external_url · string

External artifact URL. REQUIRED unless artifact_url is provided; preview_markdown alone is rejected.

description · string

Artifact description

preview_markdown · string

Optional markdown preview shown with the linked artifact. Does not replace artifact_url/external_url.

status · string

Artifact workflow status Options: draft, in_review, approved, changes_requested, superseded, archived.

metadata · object

Artifact metadata

agent_type · string

Agent/domain that produced the artifact, such as engineering, sales, product, design, operations, marketing, or orchestrator. Stored under metadata.artifact_contract.

company_stage · string

Founder/team context this artifact is calibrated for. Stored under metadata.artifact_contract. Options: early_founder, founder_led_company, operating_team.

business_outcome · string

Business outcome this artifact is meant to advance, such as ship a PR, start founder-led sales, unblock launch, reduce incident risk, or choose the next initiative. Stored under metadata.artifact_contract.

owner · string

Human or agent owner for the next review/action. Stored under metadata.artifact_contract.

review_date · string

Date or cadence for the next review point. Stored under metadata.artifact_contract.

verification · string[]

Verification evidence or checks required before the artifact can count as done. Stored under metadata.artifact_contract.

idempotency_key · string

Strongly recommended client-generated idempotency key for safe retries

session_id · string

Optional bootstrap/session identifier

Required Scopes: initiatives:write

Profiles: v2, chatgpt, claude-plugin, memory, commander, executor

Request:

{
  "tool": "orgx_attach",
  "args": {
      "type": "workspace",
      "id": "id_value",
      "name": "name_value",
      "artifact_type": "artifact_type_value"
  }
}

---

orgx_bootstrap

Use at the start of a fresh session, after reconnecting, or before continuing work another agent left behind. Establishes OrgX session context, discovers granted scopes, returns the v2 tool routing map, and persists workspace/session continuity when the selected context changes. Pass initiative_id to bind an initiative and receive its compiled work context, including resolved decisions, acceptance checks, blockers, and artifact state. Also known as: bootstrap, setup, tool routing. USE WHEN: first call in a fresh session, after reconnecting, or before performing a multi-step workflow. NEXT: use orgx_search, orgx_inspect, or orgx_recommend based on the returned routing map. DO NOT USE WHEN: you already have session context and need to read or mutate work. Updates private session state; it does not change business records.

workspace_id · string

Canonical workspace UUID to bind as the active session workspace

initiative_id · string

Optional initiative UUID to bind and hydrate as the active work context

conversation_id · string

Optional client conversation/session identifier for continuity

client_name · string

Optional MCP client name, such as codex, chatgpt, cursor, or claude

timezone · string

Optional user timezone for date-sensitive readouts

Required Scopes: initiatives:read

Profiles: v2, chatgpt, claude-plugin, memory, commander, planner, executor, observer

Request:

{
  "tool": "orgx_bootstrap",
  "args": {}
}

---

orgx_decide

Creates or remembers durable OrgX decisions, lists pending decisions, and opens human review. Approval and rejection are human-session-only: those actions return a review URL and never resolve the decision or resume work from MCP.

Per-action input requirements: • action=“list_pending” → No required fields; initiative_id and workspace_id are optional filters. • action=“create” → REQUIRES title and decision. Optional: context, initiative_id. • action=“remember” → REQUIRES decision. Optional: title, context. • action=“approve” → REQUIRES decision_id. Optional note is accepted but not persisted by MCP. • action=“reject” → REQUIRES decision_id and reason; MCP does not persist the reason.

USE WHEN: capturing judgment or reviewing a pending decision. NEXT: open the returned review URL, then act only after the decision resolves. DO NOT USE WHEN: writing non-decision entities; use orgx_write.

action · string · required

Decision operation. See top-level description for per-action required fields. Options: create, remember, list_pending, approve, reject.

decision_id · string

Decision UUID. REQUIRED for action=approve or action=reject. Returned by action=list_pending or action=create.

title · string

Short title for the decision. REQUIRED for action=create.

decision · string

The decision text itself (what was decided). REQUIRED for action=create and action=remember.

summary · string

Optional one-line summary used in lists. Falls back to title when omitted.

context · string

Background context / rationale that led to the decision. Recommended for action=create to capture provenance.

reason · string

REQUIRED for action=reject before returning the human-session review URL. MCP does not persist or submit this reason.

note · string

Optional compatibility field for action=approve. MCP does not persist it; enter the final rationale in the human review session.

initiative_id · string

Optional initiative UUID to scope the decision. Used as filter when action=list_pending; used as parent when action=create.

workspace_id · string

Optional workspace UUID to scope the decision. Defaults to the MCP session’s workspace.

idempotency_key · string

Strongly recommended client-supplied idempotency key for action=create or action=remember. Same key returns the same result without duplicating state.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: decisions:read, decisions:write

Profiles: v2, chatgpt, claude-plugin, memory, commander, planner, observer

Request:

{
  "tool": "orgx_decide",
  "args": {
      "action": "create"
  }
}

---

orgx_inspect read-only

Use when the user names a specific task, milestone, initiative, decision, artifact, or plan session and you need its real state — decisions, owners, linked proof — before acting. Hydrates one OrgX entity with execution context. Also known as: Inspect OrgX Entity, inspect initiative, get full entity context. USE WHEN: continuing work on a named entity or verifying state before a lifecycle change. NEXT: use orgx_search for related records or orgx_recommend for a read-only next-step assessment. DO NOT USE WHEN: browsing or searching many records; use orgx_search. Read-only.

type · string · required

Entity type to inspect Options: workspace, project, initiative, milestone, workstream, task, objective, playbook, decision, artifact, run, blocker, workflow, agent, skill, plan_session, stream, studio_brand, studio_content, video_template.

id · string · required

Entity UUID or accepted short ID prefix

hydrate_context · boolean

Include linked context where available; default true

max_chars · integer

Approximate maximum hydrated context characters

session_id · string

Optional bootstrap/session identifier

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: v2, chatgpt, claude-plugin, read-only, memory, commander, planner, executor, observer

Request:

{
  "tool": "orgx_inspect",
  "args": {
      "type": "workspace",
      "id": "id_value"
  }
}

---

orgx_plan

Use when planning should survive the session and become executable context instead of a lost chat draft. Starts, resumes, edits, improves, or completes a tracked OrgX planning session.

Per-action input requirements: • action=“start” → REQUIRES feature_name. Optional: initial_plan (markdown to seed the session). • action=“resume” → Optional session_id; when omitted, resumes the most recent active session in the authenticated workspace. • action=“improve” → REQUIRES session_id AND plan_content (the current draft to critique). • action=“record_edit” → REQUIRES session_id AND edit_summary (one-line description of the change). • action=“complete” → REQUIRES session_id AND plan_content (the final accepted plan). Optional: attach_to (target entity to link the completed plan to).

USE WHEN: work is still in planning or should become executable context. NEXT: use orgx_write or orgx_act after the plan is accepted and needs durable execution state. DO NOT USE WHEN: directly scaffolding a full initiative hierarchy; use scaffold_initiative for that compatibility path.

action · string · required

Planning action to perform. See top-level description for per-action required fields. Options: start, resume, improve, record_edit, complete.

session_id · string

Plan session UUID or orgx://plan_session/<uuid> URI. Optional for action=resume, which defaults to the most recent active session in the authenticated workspace. REQUIRED for action=improve | record_edit | complete. Omit for action=start.

feature_name · string

Feature or plan name. REQUIRED when action=start.

initial_plan · string

Markdown plan content to seed the new session. Optional on action=start; the session can also be started empty and filled via improve/record_edit.

plan_content · string

Current/final plan markdown. REQUIRED when action=improve (the draft to critique) or action=complete (the final accepted plan).

edit_summary · string

One-line description of the change being recorded. REQUIRED when action=record_edit.

attach_to · object

Optional target to link the completed plan to when action=complete. Shape: { entity_type: “initiative” | “workstream” | “task”, entity_id: string }.

workspace_id · string

Workspace UUID to scope action=start plan sessions. Defaults to current session workspace when omitted.

idempotency_key · string

Optional idempotency key for safe retries. Same key returns the same result without creating duplicate session state.

Required Scopes: initiatives:read, initiatives:write

Profiles: v2, chatgpt, commander, planner, executor, observer

Request:

{
  "tool": "orgx_plan",
  "args": {
      "action": "start"
  }
}

---

orgx_recommend

Use when the user asks what to do next, wants a brief, or returns after time away and needs priorities. Recommends next work, summarizes operator-chronicle/morning-brief signals, and reads prioritization context. The default next_action mode records metered MCP allowance usage; it does not change business records. USE WHEN: user asks what to do next, wants a brief, asks what changed yesterday/week/30 days, or needs priority guidance. mode=morning_brief returns the operator chronicle when available. NEXT: present the recommendation and ask for explicit confirmation before any separate action. DO NOT USE WHEN: the user already specified a concrete action.

mode · string

Recommendation mode; default next_action Options: next_action, morning_brief.

period · string

Reporting period for mode=morning_brief; default 30d Options: day, week, 30d.

entity_type · string

Recommendation scope type Options: workspace, initiative, workstream, milestone, task.

entity_id · string

Scoped entity ID

workspace_id · string

Workspace UUID

limit · integer

Maximum recommendations

session_id · string

Optional bootstrap/session identifier

Required Scopes: initiatives:read

Profiles: v2, chatgpt, claude-plugin, read-only, memory, commander, observer

Request:

{
  "tool": "orgx_recommend",
  "args": {}
}

---

orgx_search

Use when context was lost between sessions, another agent’s work must be continued, or the answer may already exist in team memory. Finds OrgX entities, decisions, artifacts, and memory. A query without type runs a mixed relevance search and records metered MCP allowance usage; typed searches provide exhaustive cursor/offset pagination without changing business records. Also known as: Search OrgX, find initiative ID, list work, browse OrgX. USE WHEN: browsing work, searching memory, finding IDs, or listing related records. NEXT: use structuredContent.next_call exactly when pagination.has_more=true, orgx_inspect for one selected result, or orgx_recommend when the user asks what to do next. DO NOT USE WHEN: you already know the exact entity and need full context; use orgx_inspect.

query · string

Search query for memory or title/text matching

type · string

Optional entity type filter, such as task, milestone, decision, artifact, or initiative. Omit with query for a mixed relevance search across memory-backed entity types. Options: workspace, project, initiative, milestone, workstream, task, objective, playbook, decision, artifact, run, blocker, workflow, agent, skill, plan_session, stream, studio_brand, studio_content, video_template.

status · string

Optional status filter

initiative_id · string

Optional initiative UUID scope

workspace_id · string

Optional workspace UUID scope

limit · integer

Maximum records to return

offset · integer

Typed-search pagination offset. Prefer cursor when next_call returns one.

cursor · string

Opaque typed-search cursor returned by pagination.next_cursor or next_call.

fields · string[]

Optional compact field list

session_id · string

Optional bootstrap/session identifier

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: v2, chatgpt, claude-plugin, read-only, memory, commander, planner, executor, observer

Request:

{
  "tool": "orgx_search",
  "args": {}
}

---

orgx_spawn

Delegate specialist work or check whether delegation is allowed. Actions: guard, estimate, classify, spawn, and handoff.

Requirements: existing-task spawn needs task_id; ad-hoc spawn needs title + instructions and should include agent_type. handoff needs task_id + agent_type. guard needs agent_type. classify needs title or task_id. action=“estimate” needs title or task_id and returns candidate routes and cost context without dispatching work. OAuth: guard/classify/estimate require agents:read; spawn requires agents:write; handoff requires BOTH agents:write and initiatives:write.

Routing: omit model_tier/provider/model for OrgX auto-routing. Set routing or budget fields only when the user, policy, or verification plan constrains them. For controlled reliability validation, use model_tier=“standard” and budget_mode=“cheapest_valid”.

USE WHEN: delegating work or checking permission/cost before delegation. NEXT: monitor with orgx_inspect or orgx_search, then attach proof with orgx_submit_receipt. DO NOT USE: to create only a task row; use orgx_write.

action · string

Spawn operation. Defaults to “spawn”. Use estimate for pre-spawn cost/routing context without dispatching work. See top-level description for per-action required fields. Options: guard, estimate, spawn, handoff, classify.

title · string

Task title. REQUIRED for ad-hoc spawn (action=spawn without task_id) or action=classify without task_id. Used as the human-readable label of the spawned task.

task_id · string

Existing task UUID. REQUIRED for action=handoff. REQUIRED for action=spawn when spawning work for an already-created task. Either task_id or title (with instructions) must be provided for action=spawn.

initiative_id · string

Optional initiative UUID to scope the spawned task. Inferred from task_id when omitted.

workspace_id · string

Optional workspace UUID to scope the spawned task. Defaults to the MCP session’s workspace.

agent_type · string

Target agent type/domain (e.g. “engineering”, “marketing”, “design”). REQUIRED for action=guard or action=handoff. Strongly recommended for action=spawn so the work routes to the right specialist.

instructions · string

Delegation instructions for the agent. REQUIRED for action=spawn when spawning ad-hoc (without task_id). Used to override the task description for action=handoff.

expected_artifacts · string[]

Optional expected final-output labels for action=spawn. Declaring at least one adds an artifact contract to the run; when the agent returns final text without a selectable artifact, OrgX persists that response as a document using the first label.

model_tier · string

Optional model tier override. Omit to let OrgX auto-route from task complexity. Legacy local/sonnet/opus are accepted for older clients. Options: standard, balanced, precision, local, sonnet, opus.

model · string

Optional exact model identifier when the user explicitly selects one. Otherwise OrgX resolves the model from task, tier, provider, policy, and budget.

provider · string

Optional provider preference. Use auto unless the user asks for a specific provider or a cost comparison selects one. Options: auto, openai, anthropic, openrouter, groq, local.

budget_mode · string

Optional budget posture override. Use cheapest_valid for controlled validation runs while reliability is being proven. Options: cheapest_valid, balanced, highest_quality.

max_cost_usd · number

Optional per-task hard cost ceiling in USD. If the estimate exceeds this, OrgX should block, downgrade, or request approval before dispatch.

idempotency_key · string

Optional client-supplied idempotency key for safe retries. Same key returns the same spawn result without re-running.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: agents:read, agents:write, initiatives:write

Profiles: v2, chatgpt, commander, executor

Request:

{
  "tool": "orgx_spawn",
  "args": {}
}

---

orgx_submit_receipt

Use when the user says “show me it actually shipped” — completion must be proven with evidence, not prose. Submits a durable receipt anchored to an OrgX entity or artifact.

Required: receipt_type + summary. Strongly recommended: one anchor (entity_type+entity_id OR artifact_id), artifact_type, business_outcome, agent_type, and a verifiable URL in evidence.

Recognized receipt_type: “proof”, “outcome” (measurable result), “quality” (review/score), “attribution” (credit link to revenue/value), “learning” (distilled lesson). Custom keys also accepted.

Recognized evidence shapes (mix and match): { prs: string[] } — GitHub PR URLs. { deploys: string[] } — deployment URLs. { test_runs: string[] } — CI run URLs. { metrics: { name, value, unit? }[] } — quantitative outcomes. { links: string[] }, { notes: string } — supporting URLs/text.

Pass idempotency_key when retrying — server deduplicates.

USE WHEN: closing the loop on agent work with provenance. Receipts should prove the practical artifact and its business outcome, not just say the agent finished. NEXT: orgx_recommend or orgx_search to find the next priority. DO NOT USE for telemetry — use orgx_emit_activity.

workspace_id · string

Workspace UUID. Defaults to the MCP session’s workspace when omitted.

entity_type · string

Related entity type (initiative, workstream, milestone, task, decision). Required if no artifact_id is provided — pair with entity_id.

entity_id · string

Related entity UUID. Required when entity_type is provided.

receipt_type · string · required

Receipt category key. Recognized values: “proof”, “outcome”, “quality”, “attribution”, “learning”. Custom domain-specific keys are also accepted.

summary · string · required

One-sentence human-readable description of what the receipt proves (e.g. “Merged PR #142 unblocking the auth refactor”).

evidence · object

Structured evidence payload. Recognized shapes: { prs: string[] }, { deploys: string[] }, { test_runs: string[] }, { metrics: { name, value, unit? }[] }, { links: string[] }, { notes: string }. See top-level description for full list. At least one verifiable URL is strongly recommended.

artifact_id · string

Related artifact UUID to anchor the receipt to. Alternative to entity_type+entity_id when the proof lives in OrgX as an artifact.

artifact_type · string

Artifact type this receipt proves. Preferred founder/team examples: orchestration.next_initiative, eng.pull_request, eng.deploy_proof, eng.structured_blocker, sales.strategy, sales.icp_offer_sequence, sales.send_plan, sales.conversion_gates, marketing.launch_asset, marketing.channel_hypothesis, marketing.positioning_brief, marketing.proof_distribution_plan, marketing.interview_pr_plan, product.customer_discovery, product.prd, product.pricing_hypothesis, product.decision_record, design.audit, design.component_spec, design.token_package, ops.operator_brief, ops.runbook, ops.budget_envelope, ops.incident_status, proof.link.

agent_type · string

Agent/domain that produced the receipt, such as engineering, sales, product, design, operations, marketing, or orchestrator.

business_outcome · string

Business outcome advanced by the receipt.

verification_status · string

Whether the artifact verification passed, failed, was blocked, or was not run. Options: passed, failed, blocked, not_run.

validation_rung · string

Optional OrgX loop validation rung this receipt proves. Required for promotion-grade loop validation receipts. Options: schema_discovery, dry_run_spawn, single_domain_fixture, cross_domain_initiative_fixture, overnight_canary, calibrated_auto_route_expansion.

loop_validation · boolean

Set true when this receipt should be evaluated against the OrgX loop reliability validation ladder.

model_tier · string

Model tier used for the run being receipted. For validation rungs before calibrated expansion, use standard. Options: standard, balanced, precision, local, sonnet, opus.

budget_mode · string

Budget posture used for the run being receipted. For validation rungs before calibrated expansion, use cheapest_valid. Options: cheapest_valid, balanced, highest_quality.

max_cost_usd · number

Per-task or canary spend cap used during the validation run, when known.

status · string

Terminal state of the work being receipted. Pass failed or cancelled when that is what happened — omitting it records completed, and a receipt that can only say “completed” makes every reliability number a survivorship filter. Options: in_progress, completed, failed, cancelled.

started_at · string

ISO-8601 timestamp of when the work actually started. Omit if unknown rather than guessing: the record leaves duration unknown instead of claiming zero. Must not be in the future.

idempotency_key · string

Strongly recommended client-supplied idempotency key. Submitting the same key twice will not create a duplicate receipt.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:write

Profiles: v2, chatgpt, claude-plugin, memory, commander, executor

Request:

{
  "tool": "orgx_submit_receipt",
  "args": {
      "receipt_type": "receipt_type_value",
      "summary": "summary_value"
  }
}

---

orgx_write

Create or update one OrgX record (snake_case fields).

Operations: create (default) uses per-type fields; update REQUIRES id + fields.

Create requirements: workspace name/title; initiative title/name + workspace_id + goal_ids when the workspace enforces primary objectives; workstream title + initiative_id; milestone title + workstream_id; task title + workstream_id + milestone_id when the workspace requires backlog milestones; decision title; artifact target + artifact_type + artifact_url/external_url; blocker run_id + metadata.description; skill/studio records title.

Retry behavior: pass idempotency_key on creates. A key match returns the same UUID as an idempotent replay, without creating a duplicate.

Initiative constraints: priority accepts low|medium|high|urgent, not portfolio labels such as active/critical/maintenance/hold. due_date is not accepted on initiative create; store portfolio urgency and target dates in metadata.

USE WHEN: adding/editing records. Initiative writes can publish a public live link, and update patches overwrite the supplied fields. NEXT: orgx_act to launch/complete the record. DO NOT USE for lifecycle changes — use orgx_act or orgx_attach.

operation · string

Write operation. Defaults to “create”. Set “update” (with id + fields) to patch an existing entity. Options: create, update.

type · string · required

Entity type to write: workspace, task, milestone, decision, artifact, skill, blocker, studio_brand, studio_content, initiative, workstream, or objective. See top-level description for per-type required fields.

id · string

REQUIRED when operation=“update”. Target entity UUID to patch.

title · string

REQUIRED on create (provide either “title” or “name” — they are aliases). Display title of the new entity.

name · string

Alternative to “title” on create. REQUIRED on create when “title” is not provided.

summary · string

Short description shown in lists and previews. Recommended on create.

description · string

Longer-form description used in detail views.

fields · object

REQUIRED when operation=“update”. Map of entity fields to patch (only include fields you want to change).

initiative_id · string

Parent initiative UUID. REQUIRED when type=“workstream”. Optional context for tasks/milestones/artifacts to associate them with an initiative.

workstream_id · string

Parent workstream UUID. REQUIRED when type=“milestone” or type=“task”.

milestone_id · string

Parent milestone UUID for tasks. Some workspaces require an explicit backlog milestone under the workstream; create/resolve that milestone first instead of relying on auto-resolution.

workspace_id · string

Workspace UUID. REQUIRED when the MCP session does not already carry workspace context (resolve via the deprecated alias type=command_center or orgx_inspect type=workspace).

goal_ids · string[]

Objective UUIDs for initiative/workstream/milestone/task creation. REQUIRED when the workspace enforces a primary objective. Resolve via orgx_inspect type=objective.

priority · string

Record urgency. Only low|medium|high|urgent are accepted here; do not send portfolio/live labels such as active, critical, maintenance, or hold. “urgent” is normalized to “high” server-side. Options: low, medium, high, urgent.

due_date · string

Due date as YYYY-MM-DD for supported entity types. Do not send due_date when type=“initiative”; put initiative target dates in metadata.

status · string

Initial workflow status; common agent aliases such as “active” are normalized per entity type (“active” → “in_progress”).

entity_type · string

REQUIRED when type=“artifact”. Entity type to attach the artifact to (initiative, workstream, milestone, task, or decision).

entity_id · string

REQUIRED when type=“artifact” (unless task_id is provided). UUID of the entity to attach the artifact to.

task_id · string

Shortcut for attaching an artifact directly to a task. Use instead of entity_type+entity_id when type=“artifact” and the target is a task.

artifact_type · string

REQUIRED when type=“artifact”. Artifact type code. Preferred founder/team examples: orchestration.next_initiative, eng.pull_request, eng.deploy_proof, eng.structured_blocker, sales.strategy, sales.icp_offer_sequence, sales.send_plan, sales.conversion_gates, marketing.launch_asset, marketing.channel_hypothesis, marketing.positioning_brief, marketing.proof_distribution_plan, marketing.interview_pr_plan, product.customer_discovery, product.prd, product.pricing_hypothesis, product.decision_record, design.audit, design.component_spec, design.token_package, ops.operator_brief, ops.runbook, ops.budget_envelope, ops.incident_status, proof.link. Custom codes remain accepted.

artifact_url · string

Internal artifact URL (e.g. /api/artifacts/…). Either artifact_url or external_url is required when type=“artifact”; preview_markdown alone is not accepted.

external_url · string

External artifact URL (https://). Either artifact_url or external_url is required when type=“artifact”; preview_markdown alone is not accepted.

preview_markdown · string

Optional inline markdown preview shown with the linked artifact. Supporting context only; it does not replace artifact_url/external_url.

run_id · string

REQUIRED when type=“blocker”. Agent run UUID the blocker applies to.

step_id · string

Optional agent run step UUID for blocker creation.

blocker_type · string

Blocker category/type when type=“blocker” (e.g. “missing_input”, “permission”, “external_dependency”).

resolution · string

Blocker resolution text when known. Used to mark a blocker as resolved.

live_visibility · string

Initiative live-link visibility. Only applies when type=“initiative”. Options: private, public.

live_public · boolean

Shortcut to publish an initiative live link (sets live_visibility=“public”). Only applies when type=“initiative”.

live_reveal_title · boolean

When true, public live-link visitors see the initiative title. Only applies when type=“initiative” with live_visibility=“public”.

metadata · object

Free-form object for type-specific metadata. Schema varies per entity type (e.g. for skills: { capabilities, guardrails, channels }; for studio_brand: { tokens, voice, exemplars }).

tagline · string

Workspace tagline when type=“workspace”.

narrative · string

Workspace identity narrative when type=“workspace”.

key_metrics · string[]

Workspace identity metrics when type=“workspace”.

roadmap_url · string

Workspace roadmap URL when type=“workspace”.

source_links · string[]

Workspace source links when type=“workspace”.

set_active · boolean

For workspace create, make the new workspace active. Defaults true.

idempotency_key · string

Client-generated retry key. Creates deduplicate by key; updates transport the key outside validated entity fields.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: decisions:write, agents:write, initiatives:write

Profiles: v2, chatgpt, commander, planner, executor

Request:

{
  "tool": "orgx_write",
  "args": {
      "type": "type_value"
  }
}

---

Other

16 tools for other operations.

check_execution_readiness read-only

Check whether the workspace has the credentials needed to dispatch agent work, BEFORE spawning. USE WHEN: about to call orgx_spawn / spawn_agent_task and you want to confirm execution credentials exist — avoids dispatching a run that fails on missing keys. NEXT: if not ready, surface what is missing and resolve it; if ready, proceed to orgx_spawn. Read-only; dispatches nothing.

workspace_id · string

Workspace UUID to check. Defaults to the MCP session workspace.

Required Scopes: initiatives:read

Profiles: v2, chatgpt, commander, executor

Request:

{
  "tool": "check_execution_readiness",
  "args": {}
}

---

configure_outcome_type

Use when record_outcome returns an unknown outcome type recovery hint, or a custom result must become measurable. Creates or approves a workspace outcome type before recording custom baseline, audit, or quality-gate outcomes.

workspace_id · string

Workspace ID

workspaceId · string

CamelCase alias for workspace_id

key · string · required

Outcome type key, normalized server-side to snake_case

display_name · string

Human-facing outcome type label

displayName · string

CamelCase alias for display_name

unit · string

Measurement unit for this outcome type Options: usd, hours, count, percent. Default: "count".

value_semantics · string

How the value should be interpreted by ROI/proof loops Options: revenue, time_saved, risk_reduced, quality_improved. Default: "quality_improved".

valueSemantics · string

CamelCase alias for value_semantics Options: revenue, time_saved, risk_reduced, quality_improved.

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "configure_outcome_type",
  "args": {
      "key": "key_value"
  }
}

---

get_operator_chronicle read-only

Use when the user asks what happened, wants to catch up after time away, or needs a reporting window summarized with decisions and proof. Read the operator chronicle: decision chronology, yesterday/week/30-day rollups, reportingNarrative.briefMarkdown, artifacts, PR receipts, active initiatives, goals, top priorities, velocity, and reporting gaps for a workspace. USE WHEN: user asks what changed yesterday, this week, or this month; asks for decision chronology, top priorities, PR velocity, artifacts, goals, or what OrgX is missing. NEXT: present reportingNarrative.briefMarkdown first, then use reportingNarrative.nextAction and topPriorities for drill-down. Read-only.

workspace_id · string

Workspace UUID to scope the chronicle.

command_center_id · string

Deprecated alias for workspace_id.

period · string

Reporting window. day=24h, week=7d, 30d=30 days. Options: day, week, 30d.

Required Scopes: initiatives:read

Profiles: v2, chatgpt, claude-plugin, read-only, commander, observer

Request:

{
  "tool": "get_operator_chronicle",
  "args": {}
}

---

manage_lifecycle

Pause, resume, retry, or cancel any node in the work hierarchy — an initiative, workstream, milestone, task, or run. Propagates to descendant tasks + active runs. USE WHEN: the user wants to halt, restart, or re-run part of an initiative. resume/retry re-dispatch the work; pause/cancel stop active runs. NEXT: get_initiative_pulse to confirm. DO NOT USE: to mark a task done — use the deprecated alias instead.

level · string · required

Which hierarchy node to act on Options: initiative, workstream, milestone, task, run.

id · string · required

UUID of the node

action · string · required

Lifecycle action to apply Options: pause, resume, retry, cancel.

Required Scopes: agents:write, initiatives:write

Profiles: v2, chatgpt

Request:

{
  "tool": "manage_lifecycle",
  "args": {
      "level": "initiative",
      "id": "id_value",
      "action": "pause"
  }
}

---

orgx_ack_attention

Report what happened after an owner answered an attention request. Use answer_received when stored locally, resuming when native continuation begins, resumed only after work emits again, resume_failed with an actionable detail when it cannot restart, or cancelled when intentionally stopped. USE WHEN: the source client has objective evidence for a continuation state transition. NEXT: keep the same attention_id and idempotency key through terminal resumed, resume_failed, or cancelled state. DO NOT USE: to infer that work resumed merely because the decision was resolved; wait for native execution evidence. This receipt prevents Live from claiming work is moving before the source client confirms it.

attention_id · string · required

Attention/decision UUID

state · string · required

Native continuation state proven by this receipt Options: answer_received, resuming, resumed, resume_failed, cancelled.

idempotency_key · string · required

Stable key for retrying the same receipt

session_handle · string

Native session handle that processed the answer

client_event_id · string

Client event proving the continuation transition

detail · string

Actionable continuation result or failure detail

occurred_at · string

ISO timestamp when this state was observed

metadata · object

Additional non-secret receipt metadata

Required Scopes: initiatives:write

Profiles: v2, commander, executor

Request:

{
  "tool": "orgx_ack_attention",
  "args": {
      "attention_id": "attention_id_value",
      "state": "answer_received",
      "idempotency_key": "idempotency_key_value"
  }
}

---

orgx_emit_execution_graph

Emit the deterministic execution graph + trust ledger for the active run from explicit nodes, OTel semantic events, or both. OTel promotion requires orgx.material=true plus episode/kind attributes; inferred events stay gaps and raw prompts are never retained. OrgX derives false-completion, hallucinated-receipt, and dependency-violation signals from this and surfaces them on /live. USE WHEN: reporting the structured shape of multi-step work — NOT a single progress line (use orgx_emit_activity for that). NEXT: continue work; re-emit as the graph advances (idempotent per run + graph fingerprint). DO NOT USE to mark entities complete — telemetry only.

initiative_id · string · required

Initiative UUID

run_id · string

Existing run UUID

correlation_id · string

Required when run_id is not provided

source_client · string

Required when run_id is not provided Options: openclaw, codex, claude-code, chatgpt, cursor, copilot, gemini, opencode, cline, goose, qwen, kiro, web-ui, api.

runtime · object

Runtime provenance used by /live to bucket chokepoints

summary · string

Optional human-readable rollup of the graph state

nodes · object[]

Execution graph nodes; each carries claimed status + optional verification

otel_events · object[]

Raw OTel-compatible events to semantically promote. Only explicitly material native/observed facts become graph nodes; prompts and inferred reasoning do not.

edges · object[]

depends_on edges between node ids

trust_events · object[]

Explicit trust-ledger events such as authority_exceeded that OrgX cannot infer from graph shape

metadata · object

Optional structured metadata to attach to the execution-graph emission

Required Scopes: initiatives:write

Profiles: v2, commander, executor

Request:

{
  "tool": "orgx_emit_execution_graph",
  "args": {
      "initiative_id": "<initiative_id>"
  }
}

---

orgx_expect

Pre-registers one delayed, workspace-level outcome against an exact observer before its measurement window starts. The current bounded contract supports only orgx.run_receipt_coverage.v1: the share of non-benchmark terminal OrgX Business sessions whose schema-valid automatic Agent Work Receipt is stored within the configured deadline. It records a falsifiable threshold and sample-size gate; it does not infer causality, run arbitrary SQL, or match natural-language outcomes. Defaults reproduce the first production gate: at least 95% within 60 seconds over at least 20 runs. USE WHEN: work promises this delayed reliability result and the future window has not started. NEXT: let the scheduled observer resolve it after the window; inspect compiled context after resolution. DO NOT USE WHEN: reporting execution completion — use orgx_submit_receipt; or for an unsupported business metric.

metric · string · required

REQUIRED exact observer registry ID. No other metric is currently admitted.

workspace_id · string

Workspace UUID. Defaults to the MCP session workspace. The subject and metric scope are derived from this exact workspace.

window_starts_at · string · required

REQUIRED future ISO-8601 datetime with timezone offset. Registration is rejected after this window begins.

window_ends_at · string · required

REQUIRED ISO-8601 datetime with timezone offset, after window_starts_at and no more than 31 days later.

threshold · number

Required receipt coverage ratio. Defaults to 0.95. The predicate is fixed to greater-than-or-equal.

minimum_sample_size · integer

Minimum terminal-run denominator required for a conclusive result. Defaults to 20.

receipt_deadline_seconds · integer

Maximum seconds from terminal session end to durable automatic receipt. Defaults to 60.

evaluation_interval_seconds · integer

Retry cadence when the observer is unavailable. Defaults to 300 seconds.

idempotency_key · string

Client-supplied retry key sent as Idempotency-Key. Generated when omitted; reuse the same key to replay safely.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:write

Profiles: v2, claude-plugin, memory, commander, planner, executor

Request:

{
  "tool": "orgx_expect",
  "args": {
      "metric": "metric_value",
      "window_starts_at": "window_starts_at_value",
      "window_ends_at": "window_ends_at_value"
  }
}

---

orgx_free_audit read-only

Use when a workspace wants to know how ready it is for autonomous agent work before spending anything. Runs a free autonomy benchmark from trust, proof, ROI, and workspace signals. Returns Proof Score, Context Debt, Autonomy Maturity, ROI Visibility, and next recommendations without starting an autonomous session or consuming agent credits.

workspace_id · string · required

Workspace ID to audit

agent_type · string

Agent type to benchmark trust against Default: "orchestrator".

period · string

ROI attribution period used for ROI Visibility Options: 7d, 30d, 90d. Default: "30d".

include_raw_signals · boolean

Include raw upstream signal payloads for debugging and verification Default: false.

Required Scopes: agents:read, initiatives:read

Profiles: all

Request:

{
  "tool": "orgx_free_audit",
  "args": {
      "workspace_id": "<workspace_id>"
  }
}

---

orgx_poll_attention read-only

Read the durable owner response and continuation state for orgx_request_attention. USE WHEN: the client has a preserved attention_id and must determine whether the owner answered without creating another request. When resolved=true, apply the answer to the preserved session. NEXT: call orgx_ack_attention with state=resuming, then state=resumed only after native execution actually restarts. Read-only.

attention_id · string · required

Attention/decision UUID

Required Scopes: initiatives:read

Profiles: v2, commander, planner, executor, observer

Request:

{
  "tool": "orgx_poll_attention",
  "args": {
      "attention_id": "attention_id_value"
  }
}

---

orgx_poll_question read-only

Read the durable answer receipt for a question previously forwarded with orgx_request_question. USE WHEN: an external client is paused for human input. NEXT: when resolved=true and continuation.should_resume=true, resume the preserved source session with answer and resolution_context; when false, remain paused without creating another question. Read-only.

question_id · string · required

Question/decision UUID returned by orgx_request_question

Required Scopes: initiatives:read

Profiles: v2, commander, planner, executor, observer

Request:

{
  "tool": "orgx_poll_question",
  "args": {
      "question_id": "question_id_value"
  }
}

---

orgx_request_attention

Forward a typed human-interruption request while preserving the originating run and session. Use kind=question for missing context, permission for a scoped tool or file action, approval for owner sign-off, and recovery only when automatic retry cannot safely continue. USE WHEN: a native client reaches a genuine human decision that prevents the preserved session from continuing safely. NEXT: poll orgx_poll_attention; resume only after the answer is applied, then call orgx_ack_attention so Live can show that work actually restarted. DO NOT USE: for internal turn boundaries or retryable runtime events.

initiative_id · string · required

Initiative UUID

attention_kind · string · required

Why human attention is required Options: question, permission, approval, recovery.

idempotency_key · string · required

Stable key for safe retries of this request

question · string · required

The concrete request the owner must answer

context · string

What led here, what is preserved, and what the answer changes

impact_if_delayed · string

What remains paused or at risk until the owner responds

options · object[]

Pre-allocated valid responses

response_mode · string

Answer control; inferred from options when omitted Options: single_select, multi_select, free_text, confirmation.

recommended_option_id · string

Recommended option when the agent can justify one

recommended_action · string

Concise recommendation and why it is safest or highest leverage

blocking · boolean

Whether linked work is gated; default true

urgency · string

Owner attention urgency; default medium Options: low, medium, high, urgent.

workstream_id · string

Affected workstream UUID

run_id · string

Existing OrgX run UUID

correlation_id · string

Stable client correlation when run_id is unavailable

source_client · string

Originating native client Options: openclaw, codex, claude-code, chatgpt, cursor, copilot, gemini, opencode, cline, goose, qwen, kiro, web-ui, api.

runtime · object

Runtime and provider provenance for the preserved execution

source_session_id · string

Originating client session identifier

source_tool · string · required

Native hook or tool that requested attention

source_event_id · string

Originating hook or tool-call event identifier

source_ref · object

Additional non-secret source and continuation references

continuation · object

How OrgX should return the answer to the preserved client session

metadata · object

Additional non-secret request context

Required Scopes: initiatives:write

Profiles: v2, commander, planner, executor

Request:

{
  "tool": "orgx_request_attention",
  "args": {
      "initiative_id": "<initiative_id>",
      "attention_kind": "question",
      "idempotency_key": "idempotency_key_value",
      "question": "question_value",
      "source_tool": "source_tool_value"
  }
}

---

orgx_request_question

Pause at a safe checkpoint and forward a contextual question to the initiative owner. OrgX renders the right single-select, multi-select, free-text, or confirmation control and preserves the source run/session so work can resume with the exact answer. USE WHEN: Claude Code AskUserQuestion, Codex request_user_input, Cursor, OpenClaw, or another client needs human judgment to continue. NEXT: poll orgx_poll_question with the returned question_id; continue only when continuation.should_resume is true. DO NOT USE: for runtime failures with an automatic retry path — report a chokepoint instead.

initiative_id · string · required

Initiative UUID

idempotency_key · string · required

Stable key for safe retries of the same question

question · string · required

The concrete question the owner must answer

context · string

What led here, what is preserved, and what the answer changes

options · object[]

Pre-allocated answers for single-select or multi-select questions

response_mode · string

Answer control; inferred from options when omitted Options: single_select, multi_select, free_text, confirmation.

blocking · boolean

Whether this answer gates the linked work; default true

urgency · string

Owner attention urgency; default medium Options: low, medium, high, urgent.

workstream_id · string

Affected workstream UUID

run_id · string

Existing run UUID

correlation_id · string

Required with source_client when run_id is absent

source_client · string

Originating client; required when run_id is absent Options: openclaw, codex, claude-code, chatgpt, cursor, copilot, gemini, opencode, cline, goose, qwen, kiro, web-ui, api.

runtime · object

Runtime/provider provenance for the paused execution

source_session_id · string

Claude, Codex, Cursor, or other client session identifier

source_tool · string · required

Originating tool, e.g. AskUserQuestion or request_user_input

source_event_id · string

Originating question/tool-call event identifier

source_ref · object

Additional non-secret client continuation references

metadata · object

Additional non-secret structured context

Required Scopes: initiatives:write

Profiles: v2, commander, planner, executor

Request:

{
  "tool": "orgx_request_question",
  "args": {
      "initiative_id": "<initiative_id>",
      "idempotency_key": "idempotency_key_value",
      "question": "question_value",
      "source_tool": "source_tool_value"
  }
}

---

orgx_tail read-only

Use during a long-running session to read accepted material state changes since orgx_bootstrap. Pass the exact capsule_id and as_of_global_sequence returned by bootstrap. Returns only the currently ledger-backed allowlist in ascending global-sequence order: accepted/superseded decisions, authority lease changes, blocker changes, and metric-expectation registration/resolution. It explicitly reports material classes that are not ledger-backed yet. Read-only. USE WHEN: the session may have outlived its bootstrap context. NEXT: apply the returned changes or call again with next_after_sequence while has_more=true. DO NOT USE: as a substitute for orgx_bootstrap or to infer applied learning, constraints, or incidents that the coverage boundary marks unavailable.

capsule_id · string · required

Exact capsule_id returned by orgx_bootstrap.

after_sequence · integer · required

Exact as_of_global_sequence or next_after_sequence from the previous call.

workspace_id · string

Workspace UUID. Defaults to the MCP session workspace.

limit · integer

Maximum material changes per page (1-100).

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:read

Profiles: v2, claude-plugin, commander, executor, observer

Request:

{
  "tool": "orgx_tail",
  "args": {
      "capsule_id": "capsule_id_value",
      "after_sequence": "after_sequence_value"
  }
}

---

queue_action

Pin, unpin, or skip a workstream in the Next Up queue. USE WHEN: user wants to force-prioritize or deprioritize a workstream. action=pin to force-top, action=unpin to remove pin, action=skip to temporarily deprioritize. Requires initiatives:write.

action · string · required

Queue operation Options: pin, unpin, skip.

initiative_id · string · required

Initiative UUID

workstream_id · string · required

Workstream UUID

workspace_id · string

Workspace UUID

command_center_id · string

Deprecated alias for workspace_id

rank · number

Position among pinned items, 0=top (pin only)

duration_minutes · number

Skip duration in minutes, default 60, max 10080 (skip only)

Required Scopes: initiatives:write

Profiles: all

Request:

{
  "tool": "queue_action",
  "args": {
      "action": "pin",
      "initiative_id": "<initiative_id>",
      "workstream_id": "<workstream_id>"
  }
}

---

request_independent_artifact_review

Queue OrgX’s independent evaluator for one completed agent artifact. The producing agent cannot supply or choose the score. OrgX persists the native evaluation and its 1–5 rating projection under the rubric version. USE WHEN: an agent has produced one final artifact and you need an independently scored record. NEXT: inspect the artifact evals after the queued evaluation completes. DO NOT USE: for drafts or to record a self-score.

artifact_id · string · required

Completed work_artifacts UUID to evaluate

Required Scopes: initiatives:write

Profiles: v2

Request:

{
  "tool": "request_independent_artifact_review",
  "args": {
      "artifact_id": "artifact_id_value"
  }
}

---

scoring_config

Read or update scoring engine configuration. USE WHEN: user asks about scoring setup, wants to toggle scoring, adjust weights, or change active signals. action=get to read, action=update to modify. NEXT: Run recommend_next_action to see effects in the preferred workflow, or the deprecated alias if you need raw queue scoring. Read-only for get, requires initiatives:write for update.

action · string · required

get=read config, update=modify settings Options: get, update.

workspace_id · string

Workspace UUID

command_center_id · string

Deprecated alias for workspace_id

enabled · boolean

Enable/disable scoring_v2 (action=update only)

active_signals · string[]

Signal names to activate (action=update only)

weights · object

Partial weight overrides e.g. { priority: 300 } (action=update only)

Required Scopes: decisions:read, agents:read, initiatives:read, memory:read

Profiles: all

Request:

{
  "tool": "scoring_config",
  "args": {
      "action": "get"
  }
}

---

Proof Runtime v1

3 tools for proof runtime v1 operations.

orgx_complete_work

Marks a v1 ledger work item complete (POST /api/v1/commands/complete-work) with optimistic concurrency: expected_updated_at and expected_aggregate_version must match the current task record or the command returns a conflict — read them fresh, never guess. Records summary, evidence, and cost on the completion event; it does not verify the work. An Idempotency-Key is generated when none is supplied. USE WHEN: closing a ledger-backed work item created with orgx_create_work. NEXT: orgx_submit_receipt for durable proof of the completed work. DO NOT USE WHEN: completing ordinary OrgX tasks — use orgx_act (complete_with_proof); or on a version conflict — re-read the task and retry with current values.

workspace_id · string

Workspace UUID. Defaults to the MCP session’s workspace when omitted.

task_id · string · required

REQUIRED. UUID of the ledger work item to complete.

expected_updated_at · string · required

REQUIRED. The task’s current updated_at as an ISO datetime with timezone offset. A mismatch returns a conflict.

expected_aggregate_version · integer · required

REQUIRED. The task’s current aggregate version. A mismatch returns a conflict.

summary · string

Completion summary (max 4000 characters).

evidence · object

Free-form JSON evidence recorded on the completion event.

cost_cents · integer

Actual cost in cents. Defaults to 0.

causation_id · string

Optional UUID of the event that caused this command.

correlation_id · string

Optional correlation UUID linking related commands.

idempotency_key · string

Client-supplied retry key sent as the Idempotency-Key header. Generated when omitted; reuse the same key to retry safely.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:write

Profiles: commander, executor

Request:

{
  "tool": "orgx_complete_work",
  "args": {
      "task_id": "<task_id>",
      "expected_updated_at": "expected_updated_at_value",
      "expected_aggregate_version": "expected_aggregate_version_value"
  }
}

---

orgx_create_work

Accepts organizational work onto the v1 proof-runtime ledger (POST /api/v1/commands/create-work). Records the work item as a command event; it does not start external execution. Requires an existing initiative + workstream + milestone chain. An Idempotency-Key is generated when none is supplied; retrying with the same idempotency_key returns the original result instead of duplicating. USE WHEN: registering a ledger-backed work item under an existing milestone so its lifecycle is event-sourced. NEXT: orgx_complete_work when the work finishes, or orgx_events_tail to watch the recorded events. DO NOT USE WHEN: creating initiatives, workstreams, milestones, or ordinary tasks — use orgx_write; or when dispatching an agent — use orgx_spawn.

workspace_id · string

Workspace UUID. Defaults to the MCP session’s workspace when omitted.

title · string · required

Work item title (max 240 characters).

description · string

Longer description (max 4000 characters).

initiative_id · string · required

REQUIRED. Parent initiative UUID.

workstream_id · string · required

REQUIRED. Parent workstream UUID.

milestone_id · string · required

REQUIRED. Parent milestone UUID.

priority · string

Priority. Defaults to medium. Options: low, medium, high, urgent.

due_date · string

Due date as YYYY-MM-DD.

metadata · object

Free-form JSON metadata stored on the work item.

estimated_cost_cents · integer

Estimated cost in cents. Defaults to 0.

command_id · string

Client-supplied command UUID. Generated when omitted.

expected_aggregate_version · integer

Must be 0 when provided — create-work targets a brand-new aggregate. Sent as 0 by default.

causation_id · string

Optional UUID of the event that caused this command.

correlation_id · string

Optional correlation UUID linking related commands.

idempotency_key · string

Client-supplied retry key sent as the Idempotency-Key header. Generated when omitted; reuse the same key to retry safely.

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:write

Profiles: commander, executor

Request:

{
  "tool": "orgx_create_work",
  "args": {
      "title": "<title>",
      "initiative_id": "<initiative_id>",
      "workstream_id": "<workstream_id>",
      "milestone_id": "milestone_id_value"
  }
}

---

orgx_events_tail read-only

Reads the workspace’s v1 ledger event stream (GET /api/v1/events/stream) in JSON cursor-page mode — never SSE. Returns events newest-first plus meta.nextCursor/hasMore; pass the returned cursor back (cursor or after) to continue paging. Read-only. USE WHEN: tailing what the proof runtime recorded — work commands, completions, receipts — or resuming from a saved cursor. NEXT: orgx_inspect for one referenced entity, or call again with the returned cursor while hasMore=true.

workspace_id · string

Workspace UUID. Defaults to the MCP session’s workspace when omitted.

after · string

Cursor from a previous page (alias of cursor): returns the page after it.

cursor · string

Opaque cursor from meta.nextCursor of a previous page.

limit · integer

Maximum events per page (1-100).

event_type · string

Optional event type filter. Comma-separate multiple types.

aggregate_type · string

Optional aggregate type filter (lowercase identifier).

session_id · string

Optional bootstrap/session identifier returned by orgx_bootstrap.

Required Scopes: initiatives:read

Profiles: commander, executor, observer

Request:

{
  "tool": "orgx_events_tail",
  "args": {}
}

---

Deprecated Tools

The following names are not part of the current published tool set. They are retained here only to help existing clients migrate to current operations.

Deprecated Tool	Replacement	Migration Note
create_initiative	create_entity type=initiative (or scaffold_initiative for full hierarchy)	The create_initiative tool has been replaced by the generic entity system.
list_initiatives	list_entities type=initiative	The list_initiatives tool has been replaced by the generic entity system.
create_milestone	create_entity type=milestone	The create_milestone tool has been replaced by the generic entity system.
create_task	create_entity type=task	The create_task tool has been replaced by the generic entity system.
launch_entity	entity_action action=launch	The launch_entity tool has been replaced by the unified entity_action tool.
pause_entity	entity_action action=pause	The pause_entity tool has been replaced by the unified entity_action tool.
complete_entity	entity_action action=complete	The complete_entity tool has been replaced by the unified entity_action tool.
create_entity	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
create_decision	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
remember_decision	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
entity_action	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
verify_entity_completion	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
save_artifact	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
score_next_up_queue	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
get_outcome_attribution	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
validate_studio_content	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
get_task_with_context	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
list_entities	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.
query_org_memory	Use the current resource-specific MCP operation.	Migration alias; not part of the current published tool set.

---

Next Steps

MCP Protocol

Protocol implementation details.

Agent Ops

Get started with agent workflows.