Skip to main content
This page documents all 65 tools available through the OrgX MCP server, organized by category.
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

Tool Catalog Overview

CategoryToolsDescription
Recommended Entry Points5orgx_decide, orgx_spawn, orgx_search, …
Decisions4orgx_decide, get_decision_history, orgx_decide, …
Agents4orgx_spawn, orgx_spawn, orgx_recommend, …
Memory1orgx_search
Initiative Monitoring1orgx_recommend
Entity Management11batch_create_entities, batch_delete_entities, comment_on_entity, …
Organization1orgx_recommend
Planning5orgx_plan, get_active_sessions, orgx_plan, …
Scoring & Queue2get_scoring_signals, orgx_recommend
Streams2get_initiative_stream_state, update_stream_progress
Client Integration6orgx_spawn, orgx_spawn, orgx_apply_changeset, …
Workspace1workspace
Onboarding1configure_org
Stats1stats
Intelligence Flywheel7orgx_recommend, get_my_trust_context, orgx_recommend, …
Billing3account_status, account_upgrade, account_usage_report
Other10get_decision_detail, get_job_timeline, get_logs, …

Recommended Entry Points

5 tools for recommended entry points operations.

orgx_decide

Review agent decisions or work items awaiting human approval. 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": "orgx_decide",
  "args": {}
}

orgx_spawn

Assign work to a specialist AI agent and track the result. 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": "orgx_spawn",
  "args": {
      "agent": "engineering-agent",
      "task": "task_value"
  }
}

orgx_search read-only

Search 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": "orgx_search",
  "args": {
      "query": "pricing strategy"
  }
}

orgx_decide

Save a decision to organizational memory so agents and teammates can recall it later. Also known as: decision log, team memory, agent memory, record decision, remember what we decided.
decision
string
required
Decision text or short decision title to remember
context
string
Optional background, rationale, or source context
title
string
Optional explicit decision title
initiative_id
string
Optional parent initiative UUID
workspace_id
string
Workspace UUID
priority
string
Priority / urgency Options: low, medium, high, urgent.
Required Scopes: initiatives:write, memory:write Profiles: memory Request:
{
  "tool": "orgx_decide",
  "args": {
      "decision": "decision_value"
  }
}

orgx_recommend read-only

Get health, blockers, milestones, owners, and recent activity for a project or initiative. 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": "orgx_recommend",
  "args": {}
}

Decisions

4 tools for decisions operations.

orgx_decide

Approve a specific pending OrgX decision after the user confirms. USE WHEN: user says to approve a decision returned from orgx_search with type=decision and status=pending (or the legacy orgx_decide alias). 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
note
string
option_id
string
Optional decision option id when the decision includes selectable options.
Required Scopes: decisions:write Profiles: commander Request:
{
  "tool": "orgx_decide",
  "args": {
      "decision_id": "dec_abc123"
  }
}
Response:
{
  "decision_id": "dec_abc123",
  "status": "approved",
  "artifact_id": "art_xyz789",
  "resolved_at": "2026-02-26T10:05:00Z"
}

get_decision_history read-only

Search past OrgX decisions related to a topic. USE WHEN: older clients still call this tool directly. NEXT: Present results with context; suggest orgx_decide or orgx_decide if relevant pending ones exist. DO NOT USE: for new prompts or skills. Read-only. Compatibility alias retained for older clients. Prefer orgx_search with scope=decisions with a topic query for new prompts, skills, and examples.
topic
string
required
initiative_id
string
limit
number
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, observer 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"
}

orgx_decide read-only

List OrgX decisions awaiting approval. USE WHEN: older clients still call this tool directly. NEXT: Present each decision with title and urgency, then ask which to orgx_decide or orgx_decide. DO NOT USE: for new prompts or skills. Read-only. Compatibility alias retained for older clients. Prefer orgx_search with type=decision and status=pending for new prompts, skills, and examples.
limit
number
Maximum number of decisions to return
urgency_filter
string
Options: all, critical, high.
initiative_id
string
Required Scopes: initiatives:read Profiles: commander, observer Request:
{
  "tool": "orgx_decide",
  "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
}

orgx_decide

Reject a pending OrgX decision with a reason. 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
reason
string
required
option_id
string
Optional decision option id when the decision includes selectable options.
Required Scopes: decisions:write Profiles: commander Request:
{
  "tool": "orgx_decide",
  "args": {
      "decision_id": "dec_abc123",
      "reason": "Blocked by external dependency"
  }
}
Response:
{
  "decision_id": "dec_abc123",
  "status": "rejected",
  "resolved_at": "2026-02-26T10:05:00Z"
}

Agents

4 tools for agents operations.

orgx_spawn read-only

Show what OrgX agents are currently doing (running/idle). USE WHEN: user asks about agent activity, progress, or what agents are working on. NEXT: If agents are stuck, suggest orgx_decide or orgx_act. DO NOT USE: to check initiative health — use orgx_recommend instead. Read-only.
agent_id
string
include_idle
boolean
Required Scopes: initiatives:read Profiles: commander, observer Request:
{
  "tool": "orgx_spawn",
  "args": {}
}
Response:
{
  "agent_type": "engineering-agent",
  "status": "idle",
  "current_task_id": null,
  "completed_tasks": 12,
  "trust_level": "act_with_approval"
}

orgx_spawn

Hand a task to another agent, updating assignment and optionally spawning a new run. USE WHEN: a task needs to be reassigned to a different specialist agent. NEXT: Use orgx_spawn to confirm the new agent picked up the task. DO NOT USE: for new tasks — use orgx_spawn 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: executor Request:
{
  "tool": "orgx_spawn",
  "args": {
      "task_id": "tsk_abc123",
      "agent": "engineering-agent"
  }
}
Response:
{
  "task_id": "tsk_abc123",
  "from_agent": "product-agent",
  "to_agent": "engineering-agent",
  "status": "handed_off"
}

orgx_recommend read-only

Recommend the next best action based on progress gaps and templates. USE WHEN: user asks what to do next, or needs help prioritizing. NEXT: Execute the recommended action (orgx_act, orgx_spawn, etc.). DO NOT USE: when 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
Deprecated alias for workspace_id.
limit
number
Max recommendations to return (default 5, max 5)
cascade
boolean
If true, refresh recommendations across the entity chain first
Required Scopes: initiatives:read Profiles: commander, planner, observer Request:
{
  "tool": "orgx_recommend",
  "args": {}
}
Response:
{
  "recommendation": {
    "action": "orgx_decide",
    "target_id": "dec_abc123",
    "reasoning": "Campaign brief matches brand guidelines and has strong CTAs.",
    "confidence": 0.92
  }
}

orgx_spawn

Assign work to a specialist OrgX agent. Automatically checks authorization, rate limits, and quality gates before spawning. Returns modelTier and run details on success, or blockedReason if spawn is denied. USE WHEN: user explicitly wants to delegate work to an agent. NEXT: Use orgx_spawn to monitor progress. DO NOT USE: for creating tasks in the hierarchy — use orgx_write type=task instead. Requires agents:write.
agent
string
required
task
string
required
context
string
initiative_id
string
initiative_name
string
Optional: Initiative title to resolve automatically if ID is unknown.
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.
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.
model_tier
string
Model quality tier for this task. standard=fast/cheap (Haiku/GPT-nano), balanced=best trade-off (Sonnet/GPT-mini, default), precision=highest quality (Opus/GPT-4). Overrides the initiative’s default tier. Options: standard, balanced, precision.
Required Scopes: agents:write Profiles: executor Request:
{
  "tool": "orgx_spawn",
  "args": {
      "agent": "engineering-agent",
      "task": "task_value"
  }
}
Response:
{
  "task_id": "tsk_new123",
  "agent_type": "engineering-agent",
  "status": "queued",
  "estimated_start": "2026-02-26T10:10:00Z"
}

Memory

1 tool for memory operations.

orgx_search read-only

Search OrgX organizational memory (decisions, initiatives, artifacts) for a query. USE WHEN: user asks about past decisions, context, or knowledge. NEXT: Present relevant results; suggest drill-down with orgx_search. Prefer orgx_search with scope=decisions with a topic query for new prompts, skills, and examples. DO NOT USE: for listing current entities — use orgx_search instead. Read-only.
query
string
required
scope
string
Options: all, artifacts, decisions, initiatives.
limit
number
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, planner, observer Request:
{
  "tool": "orgx_search",
  "args": {
      "query": "pricing strategy"
  }
}
Response:
{
  "results": [
    {
      "type": "artifact",
      "id": "art_xyz789",
      "title": "Q1 Campaign Brief",
      "relevance": 0.95,
      "snippet": "Launch messaging for the Q1 product update..."
    }
  ],
  "total": 3
}

Initiative Monitoring

1 tool for initiative monitoring operations.

orgx_recommend read-only

Get health, milestones, blockers, and recent activity for a single initiative. USE WHEN: user asks how an initiative is going, or wants a status update. NEXT: If blockers exist, suggest orgx_act to resolve. For deeper drill-down, use orgx_search with initiative_id. DO NOT USE: for org-wide overview — use orgx_recommend instead. Read-only.
initiative_id
string
Optional: Initiative UUID to check.
initiative_name
string
Optional: Initiative title to resolve automatically if ID is unknown.
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, planner, observer Request:
{
  "tool": "orgx_recommend",
  "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

11 tools for entity management operations.

batch_create_entities

Create multiple entities in one call with ref-based dependency resolution. No parameters required. Required Scopes: initiatives:write Profiles: planner Request:
{
  "tool": "batch_create_entities",
  "args": {}
}
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: commander, executor Request:
{
  "tool": "comment_on_entity",
  "args": {
      "entity_id": "ent_abc123",
      "body": "This is looking great!"
  }
}
Response:
{
  "comment_id": "cmt_abc123",
  "entity_id": "tsk_abc123",
  "body": "Looking good so far!",
  "created_at": "2026-02-26T10:00:00Z"
}

orgx_write

Create a new entity of any type. For full initiative hierarchies, use scaffold_initiative instead. No parameters required. Required Scopes: initiatives:write Profiles: commander, planner Request:
{
  "tool": "orgx_write",
  "args": {}
}
Response:
{
  "id": "tsk_new456",
  "type": "task",
  "title": "Design hero section",
  "status": "pending",
  "parent_id": "ws_abc123",
  "created_at": "2026-02-26T10:00:00Z"
}

orgx_act

Perform lifecycle actions on any entity (launch, pause, complete, etc.). Use action=list_actions to discover available actions.
type
string
required
Entity type Options: initiative, milestone, workstream, task, objective, playbook, decision, stream, studio_content.
id
string
required
Entity ID
action
string
Action to perform (launch, pause, complete, etc.). Omit to list available actions.
force
boolean
Force the action even if preconditions are not met.
note
string
Optional note attached to the action.
Required Scopes: initiatives:write Profiles: commander, planner, executor Request:
{
  "tool": "orgx_act",
  "args": {
      "type": "initiative",
      "id": "id_value"
  }
}
Response:
{
  "id": "init_abc123",
  "type": "initiative",
  "action": "launch",
  "previous_status": "pending",
  "new_status": "active",
  "timestamp": "2026-02-26T10:00:00Z"
}

orgx_inspect read-only

Fetch a task with hydrated context attachments (entities, artifacts, plan sessions).
task_id
string
required
Task ID
Required Scopes: initiatives:read Profiles: commander, planner, executor, observer Request:
{
  "tool": "orgx_inspect",
  "args": {
      "task_id": "tsk_abc123"
  }
}
Response:
{
  "task": {
    "id": "tsk_abc123",
    "title": "Build hero section",
    "status": "in_progress"
  },
  "parent": {
    "id": "ws_001",
    "type": "workstream",
    "title": "Frontend"
  },
  "initiative": {
    "id": "init_abc123",
    "title": "Q1 Product Launch"
  },
  "artifacts": [],
  "comments": []
}

orgx_search read-only

List entities of any type with filters and pagination. Supported types: workspace, project, initiative, milestone, workstream, task, objective, playbook, decision, artifact, run, blocker, workflow, agent, skill, plan_session, stream, studio_brand, studio_content, video_template.
type
string
required
Entity type to list 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.
limit
number
Max results (default: 20, max: 100).
cursor
string
Pagination cursor.
status
string
Filter by status.
parent_id
string
Filter by parent entity ID.
id
string
Fetch a single entity by ID (with hydrated context when hydrate_context=true).
hydrate_context
boolean
Include relationships and rich context.
include_relationships
boolean
Include related entities.
Required Scopes: initiatives:read Profiles: commander, planner, executor, observer Request:
{
  "tool": "orgx_search",
  "args": {
      "type": "workspace"
  }
}
Response:
{
  "entities": [
    {
      "id": "init_abc123",
      "type": "initiative",
      "title": "Q1 Product Launch",
      "status": "active",
      "created_at": "2026-01-15T00:00:00Z"
    }
  ],
  "total": 3,
  "cursor": null
}

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: commander, observer Request:
{
  "tool": "list_entity_comments",
  "args": {
      "entity_id": "ent_abc123"
  }
}
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: commander, planner Request:
{
  "tool": "scaffold_initiative",
  "args": {
      "title": "Q1 Product Launch"
  }
}
Response:
{
  "initiative": {
    "id": "init_new789",
    "title": "Q1 Product Launch",
    "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 orgx_act. No parameters required. Required Scopes: initiatives:write Profiles: commander, planner Request:
{
  "tool": "update_entity",
  "args": {}
}
Response:
{
  "id": "tsk_abc123",
  "type": "task",
  "title": "Updated title",
  "updated_at": "2026-02-26T10:00:00Z"
}

orgx_act dry_run=true read-only

Run pre-completion verification to confirm all child work is done before completing an entity.
type
string
required
Entity type Options: initiative, milestone, workstream, task, objective, playbook, decision, stream, studio_content.
id
string
required
Entity ID
Required Scopes: initiatives:read Profiles: commander Request:
{
  "tool": "orgx_act",
  "args": {
    "dry_run": true,
    "type": "initiative",
    "id": "id_value"
  }
}
Response:
{
  "id": "init_abc123",
  "can_complete": false,
  "blockers": [
    {
      "type": "task",
      "id": "tsk_xyz",
      "title": "Pending review",
      "status": "in_progress"
    }
  ]
}

Organization

1 tool for organization operations.

orgx_recommend 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: commander, observer Request:
{
  "tool": "orgx_recommend",
  "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.

orgx_plan

Mark a plan as complete and record implementation details. 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: decisions:write Profiles: planner Request:
{
  "tool": "orgx_plan",
  "args": {
      "session_id": "ps_abc123"
  }
}
Response:
{
  "session_id": "ps_abc123",
  "status": "completed",
  "entities_created": 8,
  "completed_at": "2026-02-26T10:10:00Z"
}

get_active_sessions read-only

Check for any active planning sessions you have open. USE WHEN: resuming a conversation or checking if a plan session exists. NEXT: Continue with orgx_plan or orgx_plan. Read-only. No parameters required. Required Scopes: initiatives:read Profiles: planner Request:
{
  "tool": "get_active_sessions",
  "args": {}
}
Response:
{
  "sessions": [
    {
      "id": "ps_abc123",
      "initiative_id": "init_abc123",
      "status": "active",
      "created_at": "2026-02-26T10:00:00Z"
    }
  ]
}

orgx_plan

Get AI suggestions to improve your plan based on past patterns and best practices. USE WHEN: user wants feedback on a plan draft. NEXT: Apply suggestions via orgx_plan. DO NOT USE: without an active plan session — call orgx_plan first.
session_id
string
required
Plan session ID
plan_content
string
required
Current plan content to analyze
Required Scopes: decisions:write Profiles: planner Request:
{
  "tool": "orgx_plan",
  "args": {
      "session_id": "ps_abc123",
      "plan_content": "plan_content_value"
  }
}
Response:
{
  "session_id": "ps_abc123",
  "suggestions": [
    {
      "type": "add_task",
      "workstream": "Frontend",
      "title": "Add responsive breakpoints",
      "reasoning": "Mobile traffic accounts for 60% of visits."
    }
  ]
}

orgx_plan

Record an edit made to a plan to learn planning patterns. USE WHEN: user modifies their plan during a session. NEXT: Continue editing or call orgx_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: decisions:write Profiles: planner Request:
{
  "tool": "orgx_plan",
  "args": {
      "session_id": "ps_abc123",
      "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"
}

orgx_plan

Start a new planning session to track your feature plan. USE WHEN: user begins planning a new feature or initiative. NEXT: Use orgx_plan for suggestions, orgx_plan to track changes, orgx_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
Required Scopes: decisions:write Profiles: planner Request:
{
  "tool": "orgx_plan",
  "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

2 tools 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 orgx_recommend. 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": "init_abc123"
  }
}
Response:
{
  "signals": [
    {
      "name": "urgency",
      "weight": 0.3,
      "description": "Time sensitivity based on deadlines"
    },
    {
      "name": "impact",
      "weight": 0.25,
      "description": "Business value"
    }
  ]
}

orgx_recommend read-only

Run the composite scoring engine and return ranked queue items with factor breakdowns. USE WHEN: older clients explicitly need raw queue scoring output. NEXT: Execute the top-ranked item via orgx_act or orgx_spawn. DO NOT USE: for new prompts or skills. Read-only. Compatibility alias retained for older clients. Prefer orgx_recommend with workspace or initiative recommendations for new prompts, skills, and examples.
initiative_id
string
Initiative UUID to score
workspace_id
string
Deprecated alias for workspace_id.
limit
number
Max items to return (default 10)
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, observer Request:
{
  "tool": "orgx_recommend",
  "args": {}
}
Response:
{
  "queue": [
    {
      "entity_id": "tsk_abc123",
      "score": 92,
      "signals": {
        "urgency": 30,
        "impact": 25,
        "recency": 20,
        "dependency": 17
      }
    }
  ],
  "scored_at": "2026-02-26T10:00:00Z"
}

Streams

2 tools for streams operations.

get_initiative_stream_state read-only

Get aggregate stream state for an initiative including overall progress, blockers, and computed metrics. USE WHEN: checking stream execution status for an initiative. NEXT: If streams are blocked, use orgx_act to unblock. DO NOT USE: for raw stream records — use orgx_search type=stream instead. Read-only.
initiative_id
string
required
The initiative ID
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: executor, observer Request:
{
  "tool": "get_initiative_stream_state",
  "args": {
      "initiative_id": "init_abc123"
  }
}
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 orgx_act 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: executor 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

6 tools for client integration operations.

orgx_spawn

Check whether an agent spawn is allowed before executing. Returns model tier, rate limit status, quality gate, and task verification. USE WHEN: before any orgx_spawn call. NEXT: If allowed, proceed with orgx_spawn 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:write Profiles: all Request:
{
  "tool": "orgx_spawn",
  "args": {
      "domain": "domain_value"
  }
}
Response:
{
  "allowed": true,
  "trust_level": "act_with_approval",
  "budget_remaining_usd": 4.5
}

orgx_spawn read-only

Classify a task and get the recommended model tier (opus for planning/architecture, sonnet for execution, local for routine). USE WHEN: deciding which model to use for agent work. NEXT: Use the returned tier when spawning via orgx_spawn. Read-only.
title
string
required
Task title
description
string
Task description
entity_type
string
Entity type: task, decision, initiative
domain
string
Agent domain
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: all Request:
{
  "tool": "orgx_spawn",
  "args": {
      "title": "Q1 Product Launch"
  }
}
Response:
{
  "task_id": "tsk_abc123",
  "recommended_model": "claude-sonnet-4-6",
  "reasoning": "Standard complexity task with clear requirements."
}

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 orgx_act or update_entity instead.
initiative_id
string
required
Initiative UUID
idempotency_key
string
required
Idempotency key for safe retries
operations
object[]
required
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, api.
Required Scopes: Authenticated user Profiles: executor Request:
{
  "tool": "orgx_apply_changeset",
  "args": {
      "initiative_id": "init_abc123",
      "idempotency_key": "idempotency_key_value",
      "operations": []
  }
}
Response:
{
  "applied": true,
  "changeset_id": "cs_abc123",
  "entities_affected": 3
}

orgx_emit_activity

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 orgx_act instead. No parameters required. Required Scopes: Authenticated user Profiles: executor Request:
{
  "tool": "orgx_emit_activity",
  "args": {}
}
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 orgx_spawn decisions. DO NOT USE: for in-progress tasks — wait until completion.
task_id
string
required
OrgX task ID
agent_domain
string
required
Agent domain that completed the task
score
number
required
Quality score: 1=poor, 3=acceptable, 5=excellent
scored_by
string
Who scored this Options: human, auto, peer.
notes
string
Notes on the score
Required Scopes: decisions:write Profiles: commander Request:
{
  "tool": "record_quality_score",
  "args": {
      "task_id": "tsk_abc123",
      "agent_domain": "agent_domain_value",
      "score": 10
  }
}
Response:
{
  "recorded": true,
  "entity_id": "tsk_abc123",
  "score": 0.88
}

sync_client_state

Sync local memory with OrgX. 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: Authenticated user Profiles: executor 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

List, get, or set the active workspace. USE WHEN: user wants to see their workspaces, check which is active, or switch workspaces. action=list to see all, action=get for current, action=set to switch.
action
string
required
list=show all, get=current, set=switch active Options: list, get, set.
workspace_id
string
Workspace UUID to switch to (action=set only)
Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, planner, executor, observer 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 setup status, configure agents, or set org policies. 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. No parameters required. Required Scopes: initiatives:read Profiles: commander Request:
{
  "tool": "configure_org",
  "args": {}
}
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 productivity stats, achievements, and streaks. scope=personal for your stats, scope=session for current session diagnostics. Read-only.
scope
string
required
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: initiatives:read Profiles: commander, observer Request:
{
  "tool": "stats",
  "args": {
      "scope": "personal"
  }
}
Response:
{
  "period": "30d",
  "decisions_resolved": 42,
  "artifacts_shipped": 18,
  "agents_spawned": 7,
  "avg_decision_time_hours": 2.3
}

Intelligence Flywheel

7 tools for intelligence flywheel operations.

orgx_recommend read-only

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 orgx_recommend 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: all Request:
{
  "tool": "orgx_recommend",
  "args": {
      "workspace_id": "ws_abc123"
  }
}
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

Agent-facing: “What’s my trust level per capability? What do I need for promotion? Which receipts are helping/hurting?” Returns the full trust context for an agent including 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": "ws_abc123",
      "agent_type": "engineering-agent"
  }
}
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
}

orgx_recommend read-only

ROI summary from the economic ledger. Human: “3.2x ROI this month.” Agent: “My outreach_draft receipts average $0.26 attributed value.” Returns cost/value/ROI breakdowns by agent, capability, and time period. Compatibility alias retained for older clients. Prefer orgx_recommend with workspace brief with value and exception summaries for new prompts, skills, and examples.
workspace_id
string
required
Workspace ID
period
string
required
Time period for ROI calculation Options: 7d, 30d, 90d. Default: "30d".
agent_type
string
Filter by specific agent type
capability_key
string
Filter by capability key
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "orgx_recommend",
  "args": {
      "workspace_id": "ws_abc123",
      "period": "7d"
  }
}
Response:
{
  "outcomes": [
    {
      "entity_id": "tsk_abc123",
      "cost_usd": 0.12,
      "value_attributed": "high",
      "receipt_id": "rcp_abc123"
    }
  ],
  "total_cost_usd": 3.45,
  "period": "30d"
}

get_relevant_learnings read-only

Agent-facing: “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
required
Default: 5.
Required Scopes: memory:read Profiles: all Request:
{
  "tool": "get_relevant_learnings",
  "args": {
      "workspace_id": "ws_abc123",
      "limit": 10
  }
}
Response:
{
  "learnings": [
    {
      "id": "lrn_abc123",
      "pattern": "Auth bugs often stem from token refresh race conditions",
      "source_task": "tsk_xyz",
      "confidence": 0.85
    }
  ]
}

record_outcome

Record a business outcome (deal closed, meeting booked, cycle time reduced). Agents can self-report outcomes they detect. Triggers attribution inference to connect outcomes to receipts. No parameters required. 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

Start an autonomous execution session with budget guardrails. Human: “Run overnight with $5 budget.” Creates a session that produces receipts while executing eligible work items.
workspace_id
string
required
Workspace ID
session_type
string
required
Options: overnight, weekend, scheduled, manual. Default: "manual".
max_cost_usd
number
required
Maximum budget in USD (hard stop — zero tolerance) Default: 5.
max_receipts
integer
required
Maximum number of receipts to produce Default: 50.
allowed_trust_levels
string[]
required
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": "ws_abc123",
      "session_type": "overnight",
      "max_cost_usd": 10,
      "max_receipts": "max_receipts_value",
      "allowed_trust_levels": []
  }
}
Response:
{
  "session_id": "auto_abc123",
  "max_cost_usd": 5,
  "max_receipts": 50,
  "started_at": "2026-02-26T22:00:00Z"
}

submit_learning

Agent-facing: Submit a discovery or insight 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": "ws_abc123",
      "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.
user_id
string
Optional user ID override.
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.
user_id
string
Optional user ID override.
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.
user_id
string
Optional user ID override.
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
  }
}

Other

10 tools for other operations.

get_decision_detail read-only

Get one decision with its structured interaction steps, options, questions, config requirements, evidence, and comments. USE WHEN: the UI needs to render a guided decision review instead of a simple approve/reject action.
decision_id
string
required
comments_cursor
string
Optional pagination cursor for additional comments.
comments_limit
number
Optional maximum comments to load.
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_decision_detail",
  "args": {
      "decision_id": "dec_abc123"
  }
}

get_job_timeline

Fetch background job and tool-job timeline events for a run or job. USE WHEN: diagnosing queueing, retries, dispatch, or completion order.
job_id
string
Specific job ID
run_id
string
Run ID to list related jobs
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_job_timeline",
  "args": {}
}

get_logs

Fetch correlated logs for a run or trace. USE WHEN: you need live log lines from Loki filtered by run, trace, service, or query.
run_id
string
Run ID filter
trace_id
string
Trace ID filter
query
string
Free-text filter
service
string
Service name filter
since
string
Optional ISO timestamp
limit
integer
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_logs",
  "args": {}
}

get_run_debug_bundle

Fetch a normalized live debug bundle for a run. USE WHEN: debugging a run and you need trace, logs, jobs, sessions, and sandbox state in one read-only payload. NEXT: Drill deeper with get_trace, get_logs, get_job_timeline, or get_session_state.
run_id
string
required
OrgX run ID
include
string[]
Optional sections to include. Defaults to trace, logs, jobs, sessions, and sandbox.
since
string
Optional ISO timestamp or backend-supported relative time
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_run_debug_bundle",
  "args": {
      "run_id": "run_id_value"
  }
}

get_session_state

Fetch normalized run/session/provider/sandbox session state. USE WHEN: debugging continuity, reconnects, provider session mapping, or sandbox session status.
session_id
string
Responses/session ID
provider_session_id
string
Provider-native session ID
sandbox_session_id
string
Sandbox session ID
run_id
string
Run ID
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_session_state",
  "args": {}
}

get_trace

Fetch a normalized trace summary and simplified span list. USE WHEN: you have a trace_id or run_id and need live trace data from Tempo rather than reconstructing from the database.
trace_id
string
Trace ID to fetch directly
run_id
string
Run ID to resolve to a trace
since
string
Optional search window when resolving by run ID
Required Scopes: initiatives:read Profiles: all Request:
{
  "tool": "get_trace",
  "args": {}
}

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
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: commander Request:
{
  "tool": "queue_action",
  "args": {
      "action": "pin",
      "initiative_id": "init_abc123",
      "workstream_id": "ws_abc123"
  }
}

resolve_decision

Resolve a decision using the structured interaction outcome contract. USE WHEN: a user completes a guided decision review that may include option selection, questions, surfaces, config completion, or subrequest updates.
decision_id
string
required
status
string
required
Options: approved, declined, cancelled.
summary
string
note
string
option_id
string
answers
object
surface_ids
string[]
surfaces
object[]
config_session_id
string
subrequest_updates
object[]
final_step_id
string
Required Scopes: decisions:write Profiles: all Request:
{
  "tool": "resolve_decision",
  "args": {
      "decision_id": "dec_abc123",
      "status": "approved"
  }
}

save_decision_draft

Save partial progress for a structured decision review. USE WHEN: the user has started a multi-step decision and the surface needs to persist the current step, answers, option selection, or subrequest state without resolving it.
decision_id
string
required
current_step_id
string
selected_option_id
string
answers
object
note
string
surface_ids
string[]
config_session_id
string
subrequest_updates
object[]
updated_at
string
Required Scopes: decisions:write Profiles: all Request:
{
  "tool": "save_decision_draft",
  "args": {
      "decision_id": "dec_abc123"
  }
}

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 orgx_recommend to see effects in the preferred workflow, or orgx_recommend if you need raw queue scoring. Read-only for get, requires initiatives:write for update. No parameters required. Required Scopes: decisions:read, agents:read, initiatives:read, memory:read Profiles: commander, observer Request:
{
  "tool": "scoring_config",
  "args": {}
}

Deprecated Tools

The following tools are deprecated and will be removed in a future version. Migrate to the recommended replacements.
Deprecated ToolReplacementMigration Note
create_initiativeorgx_write type=initiative (or scaffold_initiative for full hierarchy)The create_initiative tool has been replaced by the generic entity system.
list_initiativesorgx_search type=initiativeThe list_initiatives tool has been replaced by the generic entity system.
orgx_writeorgx_write type=milestoneThe orgx_write tool has been replaced by the generic entity system.
orgx_writeorgx_write type=taskThe orgx_write tool has been replaced by the generic entity system.
launch_entityorgx_act action=launchThe launch_entity tool has been replaced by the unified orgx_act tool.
pause_entityorgx_act action=pauseThe pause_entity tool has been replaced by the unified orgx_act tool.
complete_entityorgx_act action=completeThe complete_entity tool has been replaced by the unified orgx_act tool.

Next Steps

MCP Protocol

Protocol implementation details.

Agent Ops

Get started with agent workflows.