# Vendor health — scorecard

Companion to **AI agent for vendor performance management**.

Demo scores are fixtures. Do not treat them as a measured supplier KPI.

## Output contract

**Vendor Health → Problems → Root Causes → Recommended Actions**

Every problem needs a tool citation. Root causes without evidence stay `unconfirmed`.

## Metrics (named reads)

| Metric | Tool (example) | Watch-out |
| ------ | -------------- | --------- |
| On-time delivery | `getVendorOtif` | Port / carrier delay is not always vendor fault |
| Fill rate | `getVendorFillRate` | Partial ASN vs short-ship |
| Defects | `getReceiptDefects` | WMS damage ≠ supplier defect |
| Returns (quality) | `getQualityReturns` | Fit/size returns are not vendor defects |
| Pricing vs last PO | `getVendorPriceHistory` | Promo cost vs list |
| Lead time vs promise | `getVendorLeadTime` | Promise changed in email, not in ERP |
| Purchase history | `getVendorPoHistory` | Volume concentration |

## Sample scorecard (fixture)

```json
{
  "vendor_id": "VENDOR-KNIT-01",
  "window_days": 90,
  "health": "watch",
  "problems": [
    {
      "metric": "on_time",
      "value": "0.81",
      "evidence_tool": "getVendorOtif",
      "root_cause": "unconfirmed — week of 2026-08-03 coincides with named port delay in calendar tool",
      "recommended_action": "Do not dual-source yet; flag next three POs for ETA confirm — buyer HITL"
    }
  ],
  "do_not": ["sendVendorEmail", "cancelPurchaseOrder", "switchPreferredVendor"]
}
```

## HITL

- PO change, vendor switch, and penalty language: **human**.
- Draft a performance email; **send** only with associate/admin JWT.
- One bad week is a **watch**, not a drop. Dual-source recommendations need a second window or a named capacity constraint in a tool.