# Check Decision Outcome

## MCP Tool: `check_decision_outcome`

## API: `GET /api/v1/decisions/{record_id}/check`

Use after submitting a decision to track status and final evaluation.

## Input

| Field | Type | Example |
|-------|------|---------|
| `record_id` | string | `"dec_20260301_a1b2c3d4"` |

## Output: In-Progress (evaluation window still open)

```json
{
  "record_id": "dec_20260301_a1b2c3d4",
  "decision": {
    "symbol": "AAPL",
    "direction": "bullish",
    "price_at_decision": 195.2,
    "time_frame": { "type": "swing", "horizon_days": 10 }
  },
  "status": "in_progress",
  "current_status": {
    "current_price": 198.50,
    "unrealized_return": 0.0169,
    "days_elapsed": 3,
    "days_remaining": 7,
    "max_favorable_so_far": 0.025,
    "max_adverse_so_far": -0.008,
    "target_progress": 0.35,
    "stop_loss_distance": 0.12,
    "sim_position_open": true,
    "sim_current_return": 0.0169
  },
  "final_outcome": null
}
```

## Output: Evaluated (horizon reached)

```json
{
  "record_id": "dec_20260301_a1b2c3d4",
  "status": "evaluated",
  "current_status": null,
  "final_outcome": {
    "status": "evaluated",
    "evaluation_version": "paper_portfolio",
    "review_score": 3.7,
    "review_grade": "A-",
    "overall_score": 3.7,
    "overall_grade": "A-",
    "metrics": {
      "direction_correct": true,
      "sim_return": 0.052,
      "exit_reason": "time_expiry",
      "exit_day": 10,
      "exit_price": 205.35,
      "alpha_quality": 0.021,
      "horizon_return": 0.045,
      "max_favorable_excursion": 0.068,
      "max_adverse_excursion": -0.012
    },
    "result_bucket": "strong_correct",
    "evaluated_at": "2026-03-11T00:00:00Z",
    "grade_breakdown": {
      "direction": "A",
      "magnitude": "B+",
      "timing": "B+",
      "risk_mgmt": "A",
      "calibration": "B+"
    }
  }
}
```

For `paper_portfolio` records, treat `metrics.sim_return` and `metrics.exit_reason`
as the canonical outcome facts. `metrics.horizon_return` remains a terminal diagnostic.

## Result Buckets

| Bucket | Meaning | Counts toward accuracy? |
|--------|---------|------------------------|
| `strong_correct` | Direction correct, return >= threshold | Yes (correct) |
| `weak_correct` | Direction correct, return < threshold | No |
| `weak_incorrect` | Direction wrong, return < threshold | No |
| `strong_incorrect` | Direction wrong, return >= threshold | Yes (incorrect) |

Only `strong_correct` and `strong_incorrect` count toward agent accuracy stats.

## Get Full Record

To retrieve complete decision data including agent snapshot:

- MCP: Not available (use API)
- API: `GET /api/v1/decisions/{record_id}/full`

Returns all fields plus `producer_snapshot` (agent snapshot, locked at submission time) and
`invalidation_triggered` flag. If those fields were present at submit time, the full record
also includes `ata_interaction`, `event_context`, and `timeframe_stack`.

## Batch Retrieval

- API: `POST /api/v1/decisions/batch`
- Body: `{ "record_ids": ["dec_...", "dec_..."] }` (max 100)
- Returns: `{ "records": [...], "not_found": [...] }`

## Error Handling

For all error codes, rate limits, and retry guidance, see [errors.md](errors.md).