Tools / Decisions

record_outcome()

Key

Writes the measured actuals. The expected-vs-actual comparison is computed server-side against the expectation that was frozen at recommendation time — so neither the agent nor the human can quietly move the goalposts after the fact.

record_outcome(decision_id, actuals, measured_at)→ EXPECTED VS ACTUAL

Callable over MCP as record_outcome(decision_id, actuals, measured_at). REST mirror POST /v1/outcomes Planned — alpha is MCP-only

Why your agent calls it

The loop closes. The agent writes what actually happened; the server computes expected-vs-actual against the frozen expectation. The discount cut came in at −$46k under the revenue estimate but inside the interval — and now that variance is data.

What it returns

record_outcome() · Measured actuals against the frozen expectation.ILLUSTRATIVE

Call it from an agent

Over MCP, your agent invokes it on its own when the moment calls for it — just describe the situation. A Python SDK for headless runtimes is planned; this is what the call will look like.

agent · python sdkSDK · PLANNED — ALPHA IS MCP-ONLY

from cascadian import Cascadian

cx = Cascadian(api_key=os.environ["CASCADIAN_API_KEY"])

result = cx.record_outcome(
    decision_id="dec_0142",
    actuals={"win_rate_pp": -1.7, "gross_margin_pp": 3.1},
    measured_at="2026-09-30",
)

Parameters

Param	Type	Description
decision_idREQUIRED	string	The decided decision to score.
actualsREQUIRED	object	The measured outcome values.
measured_at	timestamp	When the actuals were measured.

Example response

record_outcome()JSON · ILLUSTRATIVE

{
  "decision_id": "dec_0142",
  "expected": { "win_rate_pp": -2.1, "gross_margin_pp": 3.4, "revenue_usd": 210000 },
  "actual":   { "win_rate_pp": -1.7, "gross_margin_pp": 3.1, "revenue_usd": 164000 },
  "variance": { "revenue_usd": -46000, "within_interval": true },
  "computed": "server-side, against the frozen expectation"
}

Related — Decisions

keyopen_decision()Open a decision and pin what is knowable now.keyrecord_recommendation()The full recommendation — expectation frozen.scopedrecord_decision()The immutable commit. Approval enforced server-side.keypropose_learning()Queue what the variance taught — humans approve.keyreview_calibration()How good are the calls, over time and by type.keyget_decision()The full decision card, by id.