meta.why_this_action

Live

Return substrate-grounded provenance for an action.

CategoryMeta
JSON-RPCtools/call
EndpointPOST /mcp
Sourcepackages/mcp-tools/src/tools/meta-why-this-action.ts

Description

For any action Cortex proposed or executed, returns the rule summary, contributing episodes, confidence label, and agent_version + world_version stamps. No LLM in the read path — provenance is materialized in action_ledger at decision time. Per ADR-0021 §read-API Family A.

Input schema

FieldTypeRequiredDescription
action_idstringyesThe action id from action_ledger.

Output shape

typescript
{
  action_id: string;
  rule_summary: string;
  confidence: 'strong_pattern' | 'pretty_sure' | 'just_guessing';
  contributing_episodes: Array<{ id: string; summary: string; occurred_at: string }>;
  agent_version: string;
  world_version: string;
}

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": "meta.why_this_action",
  "arguments": { "action_id": "act_01HXR4M9TZ" }
}

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
{
  "action_id": "act_01HXR4M9TZ",
  "rule_summary": "Reply to Marcus quickly on Tuesdays — he expects same-day for project updates.",
  "confidence": "strong_pattern",
  "contributing_episodes": [
    { "id": "ep_01H...", "summary": "Marcus: 'Can you confirm by EOD Tuesday?'", "occurred_at": "2026-05-12T13:24:00Z" }
  ],
  "agent_version": "av_01HXP9AGENT",
  "world_version": "wv_01HXR4WORLD"
}

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
unauthorizedMissing or invalid bearer token.
quota_exceededPer-minute, daily call, or daily inference budget exceeded.
not_foundThe requested resource (action_id, decision_id, counterparty_id, etc.) was not found.

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

Notes