action.communicate · Cortex MCP Docs

Description

Drafts and routes a message through the action engine. The engine checks trust, fires applicable rules, and either executes immediately (Level 3) or returns `pending_approval` with a decision id (Levels 1–2). Send-class operations always route through the engine — there is no raw connector tool.

Input schema

Field	Type	Required	Description
`to`	`string`	yes	Recipient identifier (entity id, email, handle).
`message`	`string`	yes	Message body.
`tone`	`string`	no	Optional tone hint (e.g. `direct`, `warm`).
`context`	`string`	no	Optional context for the action.

Output shape

typescript

{
  status: "success" | "pending_approval" | "error";
  decision_id?: string;
  message?: string;
  error?: string;
}

Shape is the shared `McpActionResult` discriminated union (success | pending_approval | error). Carry the `decision_id` through to `action.approve` / `action.reject` once those ship.

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

jsontools/call params

{
  "name": "action.communicate",
  "arguments": {
    "to": "entity_01HXSARAH",
    "message": "Quick check — does Tuesday 2pm still work?",
    "tone": "warm",
    "context": "Following up on rescheduled 1:1"
  }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

jsonparsed result body

{
  "status": "pending_approval",
  "decision_id": "dec_01HXP9COMM",
  "message": "Phase 0: Action Engine (Epic 7) not yet wired. This tool is structurally registered but deferred."
}

Errors this tool can return

Code	Meaning
`invalid_arguments`	Tool input failed Zod validation.
`unauthorized`	Missing or invalid bearer token.
`trust_insufficient`	The current autonomy level for this (action class × counterparty) is too low for direct execution.
`action_engine_error`	The action engine refused to enqueue the decision (downstream failure, transient).
`quota_exceeded`	Per-minute, daily call, or daily inference budget exceeded.

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).