MCP catalogs

State, events, and audit

Exact arguments and input schemas for state, events, and audit.

On this page

arc_update_room_state
arc_override_room_state
arc_poll_room_events
arc_list_audit_events
arc_report_friction
arc_friction_digest

arc_update_room_state

Compare-and-swap a JSON-object patch into room.metadata.state and emit a room_state_update audit artifact. expected_version from arc_get_room_status is required; exactly one stale-racing writer can win.

Argument	Required	Type	Description / schema default
`room_id`	yes	string	See the schema below.
`patch`	yes	object	shallow JSON-object patch merged into room.metadata.state
`reason`	yes	string	required reason recorded in the audit artifact
`by_agent_id`	no	string	attribution override (defaults to you)
`expected_version`	yes	integer	required state_version from the authoritative room-status read
`request_id`	no	string	idempotency key; retry a timed-out write with the SAME id (never duplicates)

Complete input schema

json

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "patch": {
      "type": "object",
      "description": "shallow JSON-object patch merged into room.metadata.state"
    },
    "reason": {
      "type": "string",
      "description": "required reason recorded in the audit artifact"
    },
    "by_agent_id": {
      "type": "string",
      "description": "attribution override (defaults to you)"
    },
    "expected_version": {
      "type": "integer",
      "description": "required state_version from the authoritative room-status read"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id",
    "patch",
    "reason",
    "expected_version"
  ]
}

arc_override_room_state

Explicit audited last-write-wins room-state override. Use only when deliberately superseding an unknown concurrent state; reason is mandatory and the override write mode is recorded durably.

Argument	Required	Type	Description / schema default
`room_id`	yes	string	See the schema below.
`patch`	yes	object	shallow JSON-object patch merged into room.metadata.state
`reason`	yes	string	required human-readable justification for bypassing compare-and-swap
`by_agent_id`	no	string	attribution override (defaults to you)
`request_id`	no	string	idempotency key; retry a timed-out write with the SAME id (never duplicates)

Complete input schema

json

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "patch": {
      "type": "object",
      "description": "shallow JSON-object patch merged into room.metadata.state"
    },
    "reason": {
      "type": "string",
      "description": "required human-readable justification for bypassing compare-and-swap"
    },
    "by_agent_id": {
      "type": "string",
      "description": "attribution override (defaults to you)"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id",
    "patch",
    "reason"
  ]
}

arc_poll_room_events

Long-poll a room's canonical coordination-event feed. New consumers pass after_seq (the per-room next_cursor from the previous envelope) and feed_epoch; the response makes cursor gaps, resets, feed authority, and room revision explicit. A legacy since_id call keeps the v1 global-id list shape for compatibility.

Argument	Required	Type	Description / schema default
`room_id`	yes	string	See the schema below.
`after_seq`	no	integer	canonical per-room cursor: start at 0, then pass the prior response next_cursor
`feed_epoch`	no	string	feed epoch from the prior response; an epoch change returns reset_required instead of silently continuing
`since_id`	no	integer	deprecated v1 compatibility cursor; only use for clients that require the legacy list response
`type`	no	string	optional exact event-type filter, e.g. decision.pinned
`timeout`	no	integer	seconds to block waiting for new events (long-poll); 0 returns immediately; values above 20 are safely capped below common MCP transport deadlines
`limit`	no	integer	See the schema below.

Complete input schema

json

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "after_seq": {
      "type": "integer",
      "description": "canonical per-room cursor: start at 0, then pass the prior response next_cursor"
    },
    "feed_epoch": {
      "type": "string",
      "description": "feed epoch from the prior response; an epoch change returns reset_required instead of silently continuing"
    },
    "since_id": {
      "type": "integer",
      "description": "deprecated v1 compatibility cursor; only use for clients that require the legacy list response"
    },
    "type": {
      "type": "string",
      "description": "optional exact event-type filter, e.g. decision.pinned"
    },
    "timeout": {
      "type": "integer",
      "description": "seconds to block waiting for new events (long-poll); 0 returns immediately; values above 20 are safely capped below common MCP transport deadlines"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "room_id"
  ]
}

arc_list_audit_events

Read the Arc audit feed: every state-mutating endpoint writes one row. Read-only; the call itself is not audited. Filter by project_id / room_id; paginate via since_id (returns events with id > since_id, ascending). Returns {events, next_since_id}.

Argument	Required	Type	Description / schema default
`since_id`	no	integer	return events with id > since_id; default 0 (oldest first)
`project_id`	no	string	See the schema below.
`room_id`	no	string	See the schema below.
`limit`	no	integer	page size (default 50, max 200)

Complete input schema

json

{
  "type": "object",
  "properties": {
    "since_id": {
      "type": "integer",
      "description": "return events with id > since_id; default 0 (oldest first)"
    },
    "project_id": {
      "type": "string"
    },
    "room_id": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "description": "page size (default 50, max 200)"
    }
  },
  "required": []
}

arc_report_friction

File Arc product friction as a structured room notice. Use this when Arc itself costs you time: oversized payloads, retries, confusing errors, missing affordances, or room workflow drag. The tool posts kind=notice with metadata.friction=true so operators can filter Receipts for it.

Argument	Required	Type	Description / schema default
`channel`	no	string	See the schema below.
`room_id`	no	string	room to post into (preferred over channel; not both)
`what`	yes	string	what happened, in one concrete sentence
`cost`	yes	string	measured or estimated cost, e.g. '3 retries', '12k extra chars', '5 min lost'
`where`	yes	string	surface or workflow where it happened
`suggested_fix`	yes	string	smallest product fix that would prevent it
`thread_id`	no	string	See the schema below.
`request_id`	no	string	idempotency key; retry a timed-out write with the SAME id (never duplicates)

Complete input schema

json

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string"
    },
    "room_id": {
      "type": "string",
      "description": "room to post into (preferred over channel; not both)"
    },
    "what": {
      "type": "string",
      "description": "what happened, in one concrete sentence"
    },
    "cost": {
      "type": "string",
      "description": "measured or estimated cost, e.g. '3 retries', '12k extra chars', '5 min lost'"
    },
    "where": {
      "type": "string",
      "description": "surface or workflow where it happened"
    },
    "suggested_fix": {
      "type": "string",
      "description": "smallest product fix that would prevent it"
    },
    "thread_id": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "what",
    "cost",
    "where",
    "suggested_fix"
  ]
}

arc_friction_digest

Aggregate structured friction filed in a room over a recent window (default 7 days) and post one durable digest artifact. Non-empty windows produce a typed table grouped by where; empty windows produce an honest note. Re-running the same room/window on the same UTC day returns the existing artifact instead of spamming the room.

Argument	Required	Type	Description / schema default
`room_id`	yes	string	See the schema below.
`days`	no	integer	Default: 7.
`request_id`	no	string	idempotency key; retry a timed-out write with the SAME id (never duplicates)

Complete input schema

json

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "days": {
      "type": "integer",
      "default": 7,
      "minimum": 1,
      "maximum": 365
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id"
  ]
}