Server definition

Hash: sha256:3d19ad399f7358633316aa0d8d5a0f5e4c96d03f5df30f95a471f7c9e16ca769
What it is: What a remote MCP server returned when asked what it offers: 8 tools

The blob, as servednamed by its sha256

{
  "instructions": null,
  "tools": [
    {
      "description": "List the immutable audit-archive entries for the caller's API key: every Montgomery evidence report the key generated (text or json), newest first, each with its entry id, generation timestamp, DOT number, scoring date, methodology version and the SHA-256 of the archived report text. Requires a paid CarrierScore API key.\n\nUse it to answer \"which carriers did we generate evidence for, and when?\" and to find the entry id to cite or verify for a given carrier and date. Monitor keys see the last 90 days; Compliance keys see everything ever archived.\n\nArgs:\n  - dot_number (optional): only entries for this US DOT number\n  - since (optional): YYYY-MM-DD; only entries generated on/after this date (UTC)\n  - limit (optional): 1-500, default 50\n\nReturns JSON: { tier, retention_days, total_entries, matched, count, entries: [{ entry_id, generated_at, dot_number, sha256, format_requested, scored_as_of, score_version }] }.\n\nErrors: 403 without a paid key; 400 if since is malformed.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_number": {
            "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
            "pattern": "^\\d{1,8}$",
            "type": "string"
          },
          "limit": {
            "description": "Max entries to return (default 50)",
            "maximum": 500,
            "minimum": 1,
            "type": "integer"
          },
          "since": {
            "description": "Only entries generated on/after this date (YYYY-MM-DD, UTC)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string"
          }
        },
        "type": "object"
      },
      "name": "audit_entries",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "count": {
            "description": "Entries returned (<= limit)",
            "type": "number"
          },
          "entries": {
            "description": "Newest first",
            "items": {
              "additionalProperties": true,
              "properties": {
                "dot_number": {
                  "type": "string"
                },
                "entry_id": {
                  "description": "Archive entry id: <dot>_<UTC timestamp>_<sha8>",
                  "type": "string"
                },
                "format_requested": {
                  "description": "\"text\" or \"json\" as originally requested",
                  "type": "string"
                },
                "generated_at": {
                  "description": "When the report was generated (ISO 8601 UTC)",
                  "type": "string"
                },
                "score_version": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "scored_as_of": {
                  "description": "Scoring run the report was built from",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "sha256": {
                  "description": "SHA-256 of the archived plain-text report",
                  "type": "string"
                },
                "tier": {
                  "type": "string"
                }
              },
              "required": [
                "entry_id",
                "generated_at",
                "dot_number",
                "sha256"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "matched": {
            "description": "Entries matching the filters within the retention window",
            "type": "number"
          },
          "retention_days": {
            "description": "Retrieval window in days (monitor 90; compliance null = unlimited)",
            "type": [
              "number",
              "null"
            ]
          },
          "tier": {
            "description": "Caller's tier (monitor / compliance)",
            "type": "string"
          },
          "total_entries": {
            "description": "All entries ever archived for this key",
            "type": "number"
          }
        },
        "required": [
          "tier",
          "retention_days",
          "total_entries",
          "matched",
          "count",
          "entries"
        ],
        "type": "object"
      }
    },
    {
      "description": "Look up an FMCSA-registered motor carrier's identity by US DOT number: legal name, DBA, operating status, FMCSA safety rating, fleet size (power units, drivers), physical address, and registration dates.\n\nUse this first when a booking/dispatch agent needs to confirm WHO a carrier is — that a DOT number is real, active, and matches the company name on a rate confirmation. It does not return risk indices (use carrier_score for those).\n\nReturns JSON: { dot_number, legal_name, dba_name, status_code, safety_rating, power_units, total_drivers, phy_street, phy_city, phy_state, phy_zip, add_date, mcs150_date }.\n\nErrors: 404 if the DOT is not in the FMCSA census (likely a typo or a fraudulent/never-registered carrier — treat as a red flag for booking).",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_number": {
            "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
            "pattern": "^\\d{1,8}$",
            "type": "string"
          }
        },
        "required": [
          "dot_number"
        ],
        "type": "object"
      },
      "name": "carrier_lookup",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "add_date": {
            "$ref": "#/properties/legal_name",
            "description": "Date added to the FMCSA census (YYYY-MM-DD)"
          },
          "dba_name": {
            "$ref": "#/properties/legal_name",
            "description": "Doing-business-as name, if any"
          },
          "dot_number": {
            "description": "US DOT number",
            "type": "string"
          },
          "legal_name": {
            "description": "Registered legal name",
            "type": [
              "string",
              "null"
            ]
          },
          "mcs150_date": {
            "$ref": "#/properties/legal_name",
            "description": "Latest MCS-150 filing date (YYYY-MM-DD)"
          },
          "phy_city": {
            "$ref": "#/properties/phy_street"
          },
          "phy_state": {
            "$ref": "#/properties/phy_street"
          },
          "phy_street": {
            "$ref": "#/properties/legal_name"
          },
          "phy_zip": {
            "$ref": "#/properties/phy_street"
          },
          "power_units": {
            "description": "Fleet size: number of power units",
            "type": [
              "number",
              "null"
            ]
          },
          "safety_rating": {
            "$ref": "#/properties/legal_name",
            "description": "FMCSA safety rating code (e.g. \"S\" = satisfactory)"
          },
          "status_code": {
            "$ref": "#/properties/legal_name",
            "description": "FMCSA operating status code (e.g. \"A\" = active)"
          },
          "total_drivers": {
            "$ref": "#/properties/power_units",
            "description": "Total drivers reported"
          }
        },
        "required": [
          "dot_number"
        ],
        "type": "object"
      }
    },
    {
      "description": "Get the CarrierScore risk indices for a carrier by US DOT number: two first-class, separately validated indices (0-100, HIGHER = RISKIER), each with a full component breakdown.\n\nThis is the core \"is this carrier safe to book?\" signal for AI booking agents. Served methodology v0.5 returns TWO indices, both population-relative and built from point-in-time public FMCSA data:\n  - inspection_risk — inspection / compliance risk: violations and out-of-service rates per roadside inspection (24-month chronic, 6-month acute). Historically validated against the carrier's future out-of-service rate (validation block on the index).\n  - crash_risk — crash risk: reportable crashes, fatal/injury crashes and tow-away crashes per roadside inspection (24 months). Historically validated against future reportable crashes (validation block on the index).\nPresent BOTH indices; do not collapse them into one number. Hard flags (active out-of-service order, no active insurance filing, high-confidence reincarnated-carrier link) add explicit surcharges — a carrier with any flag deserves extra scrutiny regardless of index values.\n\nReturns JSON: { dot_number, legal_name, inspection_risk: { label, description, score, base, surcharge, percentile_basis, band, band_note, data_sufficiency, components: { <name>: { label, value, percentile, weight } }, validation: { auc_holdout, label, holdout_origins, post_selection_origin, source, text } }, crash_risk: { ...same shape... }, legacy_composite: { score, base_score, surcharge, rule, rule_text, validated: false, note }, carrier_score (backward-compatible: == legacy_composite.score under v0.5), base_score, surcharge, score_version (\"0.5\"), methodology_note, components (flat, backward-compatible), flags: string[], data_sufficiency (0-1, share of the components resting on observed vs neutral-imputed data), scored_as_of, disclaimer }. Older opt-in methodologies keep their shapes: v0 (six components), v0.3 (sub_indices), v0.4 (indices + composite).\n\nInterpreting for booking decisions: treat the indices as documented decision-support evidence, not an approve/deny verdict. legacy_composite / carrier_score is NOT validated and is kept only so older integrations keep working — never present it as the carrier's risk score. Low data_sufficiency means limited inspection history — common for new carriers, itself a risk signal. Always relay each index's validation text and the disclaimer when presenting the result.\n\nErrors: 404 if the DOT is not in the scored population; 503 if scores have not been computed yet.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_number": {
            "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
            "pattern": "^\\d{1,8}$",
            "type": "string"
          }
        },
        "required": [
          "dot_number"
        ],
        "type": "object"
      },
      "name": "carrier_score",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "base_score": {
            "$ref": "#/properties/carrier_score",
            "description": "Score before hard-flag surcharges (v0.5: legacy composite base)"
          },
          "carrier_score": {
            "description": "0-100, higher = riskier. Under v0.5 this equals legacy_composite.score (kept for backward compatibility); under v0/v0.3/v0.4 it is that version's headline score",
            "type": [
              "number",
              "null"
            ]
          },
          "components": {
            "additionalProperties": {
              "$ref": "#/properties/inspection_risk/properties/components/additionalProperties"
            },
            "description": "Flat component map keyed by component name (v0.5: within-index weights of both indices, for backward compatibility; the per-index components live under inspection_risk / crash_risk)",
            "type": "object"
          },
          "composite": {
            "additionalProperties": true,
            "description": "v0.4 only: how the headline carrier_score is derived from the two indices",
            "properties": {
              "base_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "carrier_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              },
              "rule": {
                "type": "string"
              },
              "rule_text": {
                "type": "string"
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "crash_risk": {
            "$ref": "#/properties/inspection_risk",
            "description": "v0.5 (served default): CRASH RISK index 0-100 (higher = riskier) — crashes, fatal/injury and tow-away crashes per roadside inspection relative to the population; validated against future reportable crashes. Read this second."
          },
          "data_sufficiency": {
            "$ref": "#/properties/carrier_score",
            "description": "0-1: share of the score resting on observed vs neutral-imputed data"
          },
          "disclaimer": {
            "description": "Methodology disclaimer — relay verbatim",
            "type": "string"
          },
          "dot_number": {
            "description": "US DOT number",
            "type": "string"
          },
          "flags": {
            "description": "Hard flags (OOS order, no insurance, reincarnation link)",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "indices": {
            "additionalProperties": {
              "$ref": "#/properties/inspection_risk"
            },
            "description": "v0.4 only: inspection_risk / crash_risk first-class indices (0-100), each with components, percentile basis and band",
            "type": "object"
          },
          "inspection_risk": {
            "additionalProperties": true,
            "description": "v0.5 (served default): INSPECTION / COMPLIANCE RISK index 0-100 (higher = riskier) — violations and out-of-service rates per roadside inspection relative to the population; validated against future out-of-service rate. Read this first.",
            "properties": {
              "band": {
                "description": "Carrier's 24m inspection-count band",
                "type": [
                  "string",
                  "null"
                ]
              },
              "band_note": {
                "type": "string"
              },
              "base": {
                "description": "Percentile blend before surcharge (0-100)",
                "type": [
                  "number",
                  "null"
                ]
              },
              "components": {
                "additionalProperties": {
                  "additionalProperties": true,
                  "properties": {
                    "label": {
                      "description": "Human-readable component label",
                      "type": "string"
                    },
                    "percentile": {
                      "description": "Population percentile of the value, 0-1",
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "value": {
                      "description": "Raw component value",
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "weight": {
                      "description": "Component weight in the base score",
                      "type": "number"
                    }
                  },
                  "required": [
                    "label"
                  ],
                  "type": "object"
                },
                "type": "object"
              },
              "data_sufficiency": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "description": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "percentile_basis": {
                "description": "\"global\" or \"banded\" (24m inspection-activity band)",
                "type": "string"
              },
              "score": {
                "description": "Index 0-100 incl. its own surcharge, higher = riskier",
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharges_applied": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "validation": {
                "additionalProperties": true,
                "description": "v0.5: this index's own historical validation (point-in-time backtest, held-out cohorts)",
                "properties": {
                  "auc_holdout": {
                    "description": "Held-out AUC range on the index's own outcome",
                    "type": "string"
                  },
                  "auc_post_selection_holdout": {
                    "type": "string"
                  },
                  "holdout_origins": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "label": {
                    "description": "The future outcome the index was validated against",
                    "type": "string"
                  },
                  "post_selection_origin": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source": {
                    "description": "Path of the validation report in docs/research",
                    "type": "string"
                  },
                  "text": {
                    "description": "One-line validation statement — relay with the index",
                    "type": "string"
                  },
                  "top_decile_lift": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "legacy_composite": {
            "additionalProperties": true,
            "description": "v0.5: backward-compatible legacy composite (0.70 x higher index + 0.30 x lower index + surcharges). Not validated, not the headline — do not present it as the carrier's risk score.",
            "properties": {
              "base_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              },
              "rule": {
                "type": "string"
              },
              "rule_text": {
                "type": "string"
              },
              "score": {
                "description": "Legacy composite 0-100 (== top-level carrier_score)",
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "validated": {
                "description": "Always false: the composite is not validated or gated",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "legal_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "methodology_note": {
            "$ref": "#/properties/legal_name",
            "description": "One-line description of the weighting used"
          },
          "score_version": {
            "$ref": "#/properties/legal_name",
            "description": "Documented methodology version (\"0.5\" is the served default; \"0\", \"0.3\", \"0.4\" are opt-in)"
          },
          "scored_as_of": {
            "$ref": "#/properties/legal_name",
            "description": "Date of the scoring run (YYYY-MM-DD)"
          },
          "sub_indices": {
            "additionalProperties": {
              "additionalProperties": true,
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "description": "Sub-index 0-100, population-relative",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "weight": {
                  "description": "Sub-index weight in the composite",
                  "type": "number"
                }
              },
              "type": "object"
            },
            "description": "v0.3 only: inspection_risk / crash_risk sub-indices (0-100) and their weights",
            "type": "object"
          },
          "surcharge": {
            "$ref": "#/properties/carrier_score",
            "description": "Additional points from hard flags"
          }
        },
        "required": [
          "dot_number",
          "components",
          "flags"
        ],
        "type": "object"
      }
    },
    {
      "description": "Retrieve the alert history for a saved carrier list (see save_carrier_list), newest first. Requires the same paid API key that saved the list.\n\nEach alert records one change detected between consecutive daily scoring runs for one carrier: type (oos_order_activated, authority_lost, insurance_lapsed, status_changed, inspection_risk_jump, crash_risk_jump, score_jump, reincarnation_link), severity (critical / high / medium / low), the field that changed with its before/after values, the DOT and legal name, and the scoring dates compared. inspection_risk_jump / crash_risk_jump (index base up >= 10 points, medium) are the primary deterioration signals; score_jump on the legacy composite is emitted at low severity for backward compatibility. Use it to answer \"did anything change on my carrier list?\" — critical alerts (new OOS order, authority lost) mean the carrier should not be dispatched until verified; follow up with carrier_score or montgomery_file for the full picture.\n\nArgs:\n  - list_id: the lst_... id returned by save_carrier_list\n  - since (optional): YYYY-MM-DD; only alerts from scoring runs on/after this date\n\nReturns JSON: { list_id, since, count, alerts: [{ ts, as_of, prev_as_of, list_id, list_name, dot, legal_name, type, severity, field, before, after }] }. An empty alerts array means no monitored change since the given date (alerts only exist once two daily scoring runs have happened).\n\nErrors: 403 without a paid key; 404 if the list id is unknown for this key; 400 if since is not YYYY-MM-DD.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "list_id": {
            "description": "Saved list id from save_carrier_list",
            "pattern": "^lst_[A-Za-z0-9_-]+$",
            "type": "string"
          },
          "since": {
            "description": "Only alerts from scoring runs on/after this date (YYYY-MM-DD)",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string"
          }
        },
        "required": [
          "list_id"
        ],
        "type": "object"
      },
      "name": "list_alerts",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "alerts": {
            "description": "Alert history, newest first",
            "items": {
              "additionalProperties": true,
              "properties": {
                "after": {
                  "description": "Value in the current scoring run"
                },
                "as_of": {
                  "description": "Scoring run date that surfaced the change (YYYY-MM-DD)",
                  "type": "string"
                },
                "before": {
                  "description": "Value in the previous scoring run"
                },
                "dot": {
                  "description": "US DOT number",
                  "type": "string"
                },
                "field": {
                  "description": "Score field that changed",
                  "type": "string"
                },
                "legal_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "list_id": {
                  "type": "string"
                },
                "list_name": {
                  "type": "string"
                },
                "prev_as_of": {
                  "description": "Previous scoring run date compared against",
                  "type": "string"
                },
                "severity": {
                  "description": "critical | high | medium",
                  "type": "string"
                },
                "ts": {
                  "description": "When the alert was recorded (ISO 8601 UTC)",
                  "type": "string"
                },
                "type": {
                  "description": "oos_order_activated | authority_lost | insurance_lapsed | status_changed | score_jump | reincarnation_link",
                  "type": "string"
                }
              },
              "required": [
                "ts",
                "as_of",
                "list_id",
                "dot",
                "type",
                "severity"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "count": {
            "description": "Number of alerts returned",
            "type": "number"
          },
          "list_id": {
            "type": "string"
          },
          "since": {
            "description": "Lower bound applied (YYYY-MM-DD) or null",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "list_id",
          "count",
          "alerts"
        ],
        "type": "object"
      }
    },
    {
      "description": "Batch risk check for a list of carriers by US DOT number (max 100 per call): score summary and hard flags for each.\n\nUse when an agent is screening multiple candidate carriers for a load, or re-checking a broker's active carrier roster (\"did any of my carriers pick up an out-of-service order or drop insurance?\"). For a full breakdown of any single carrier that looks risky here, follow up with carrier_score or montgomery_file.\n\nArgs:\n  - dot_numbers: array of DOT number strings, 1-100 entries\n\nReturns JSON: { scored_as_of, requested, found, carriers: [{ dot_number, legal_name, inspection_risk (0-100 inspection / compliance risk index, higher = riskier), crash_risk (0-100 crash risk index), carrier_score (legacy composite under v0.5 — backward compatibility only; use the two indices), data_sufficiency, flags: string[] }], not_found: string[], disclaimer }. DOTs in not_found are absent from the scored population — verify them with carrier_lookup; an unknown DOT on your roster is itself a red flag.\n\nErrors: 400 if the list is empty or exceeds 100 (split into batches); 503 if scores are not computed yet.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_numbers": {
            "description": "US DOT numbers to check, 1-100 per call",
            "items": {
              "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
              "pattern": "^\\d{1,8}$",
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "dot_numbers"
        ],
        "type": "object"
      },
      "name": "monitor_carriers",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "carriers": {
            "description": "Score summary per found carrier",
            "items": {
              "additionalProperties": true,
              "properties": {
                "carrier_score": {
                  "description": "0-100, higher = riskier (v0.5: legacy composite, backward compatibility only — use the two indices)",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "crash_risk": {
                  "description": "Crash risk index 0-100 (v0.5 headline; also present for v0.3/v0.4 parquets)",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "data_sufficiency": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "dot_number": {
                  "type": "string"
                },
                "flags": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "inspection_risk": {
                  "description": "Inspection / compliance risk index 0-100 (v0.5 headline; also present for v0.3/v0.4 parquets)",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "legal_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "dot_number"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "disclaimer": {
            "description": "Methodology disclaimer — relay verbatim",
            "type": "string"
          },
          "found": {
            "description": "How many were found in the scored population",
            "type": "number"
          },
          "not_found": {
            "description": "Requested DOTs absent from the scored population",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "requested": {
            "description": "How many DOT numbers were requested",
            "type": "number"
          },
          "scored_as_of": {
            "description": "Date of the scoring run (YYYY-MM-DD)",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requested",
          "found",
          "carriers",
          "not_found"
        ],
        "type": "object"
      }
    },
    {
      "description": "Generate a timestamped Montgomery file — a carrier-selection evidence report — for a carrier by US DOT number.\n\nSince Montgomery v. Caribe Transport II (SCOTUS, May 2026), freight brokers are exposed to state-law negligent-selection claims and need documented, timestamped, safety-data-based carrier selection. This report is that artifact: the two risk indices (inspection / compliance risk and crash risk, each with its components, percentiles, activity-band context and its own historical-validation line), the legacy composite (labelled backward-compatibility only), hard flags, FMCSA safety rating, and the methodology disclaimer, dated as of the scoring run. A booking agent should generate and retain this file at the moment a carrier is selected for a load.\n\nArgs:\n  - dot_number: US DOT number, digits only\n  - format: \"text\" (default; the filing-ready plain-text report, available on the free tier) or \"json\" (structured fields; requires an API key on the monitor or compliance tier)\n\nReturns: format=\"text\" gives the plain-text report (structured field report_text); format=\"json\" gives structured fields { report, generated, dot_number, legal_name, dba_name, safety_rating, status_code, power_units, inspection_risk, crash_risk, legacy_composite (v0.5), carrier_score (backward-compatible), components, flags, data_sufficiency, score_version, scored_as_of, disclaimer } (v0.4 parquets return indices + composite instead). Every report embeds the disclaimer verbatim — keep it when storing or quoting the report.\n\nAudit archive (paid tiers): every report generated with an API key is stored immutably server-side and the result carries audit_entry_id + sha256 (SHA-256 of the plain-text report). Quote both when citing the report; later, verify_evidence(entry_id) proves the archived copy is unchanged and audit_entries lists what was generated. Monitor keys can retrieve the last 90 days (2,000 reports/month); Compliance keys have unlimited retention and reports.\n\nErrors: 403 if format=json without an API key; 404 unknown DOT; 429 if a Monitor key has used its 2,000 reports this month (upgrade hint in the message); 503 if scores are not computed yet.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_number": {
            "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
            "pattern": "^\\d{1,8}$",
            "type": "string"
          },
          "format": {
            "default": "text",
            "description": "\"text\" = filing-ready report (free tier); \"json\" = structured fields (requires API key)",
            "enum": [
              "text",
              "json"
            ],
            "type": "string"
          }
        },
        "required": [
          "dot_number"
        ],
        "type": "object"
      },
      "name": "montgomery_file",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "audit_entry_id": {
            "description": "Paid tiers: id of the immutable archived copy of this report (use with verify_evidence / audit_entries)",
            "type": "string"
          },
          "base_score": {
            "$ref": "#/properties/power_units"
          },
          "carrier_score": {
            "$ref": "#/properties/power_units",
            "description": "0-100, higher = riskier (v0.5: == legacy_composite.score)"
          },
          "components": {
            "additionalProperties": {
              "$ref": "#/properties/inspection_risk/properties/components/additionalProperties"
            },
            "type": "object"
          },
          "composite": {
            "additionalProperties": true,
            "properties": {
              "base_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "carrier_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              },
              "rule": {
                "type": "string"
              },
              "rule_text": {
                "type": "string"
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "crash_risk": {
            "$ref": "#/properties/inspection_risk",
            "description": "v0.5: crash risk index with components and validation"
          },
          "data_sufficiency": {
            "$ref": "#/properties/power_units"
          },
          "dba_name": {
            "$ref": "#/properties/legal_name"
          },
          "disclaimer": {
            "type": "string"
          },
          "dot_number": {
            "type": "string"
          },
          "flags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "generated": {
            "description": "Report generation date (YYYY-MM-DD)",
            "type": [
              "string",
              "null"
            ]
          },
          "indices": {
            "additionalProperties": {
              "$ref": "#/properties/inspection_risk"
            },
            "type": "object"
          },
          "inspection_risk": {
            "additionalProperties": true,
            "description": "v0.5: inspection / compliance risk index with components and validation",
            "properties": {
              "band": {
                "description": "Carrier's 24m inspection-count band",
                "type": [
                  "string",
                  "null"
                ]
              },
              "band_note": {
                "type": "string"
              },
              "base": {
                "description": "Percentile blend before surcharge (0-100)",
                "type": [
                  "number",
                  "null"
                ]
              },
              "components": {
                "additionalProperties": {
                  "additionalProperties": true,
                  "properties": {
                    "label": {
                      "description": "Human-readable component label",
                      "type": "string"
                    },
                    "percentile": {
                      "description": "Population percentile of the value, 0-1",
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "value": {
                      "description": "Raw component value",
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "weight": {
                      "description": "Component weight in the base score",
                      "type": "number"
                    }
                  },
                  "required": [
                    "label"
                  ],
                  "type": "object"
                },
                "type": "object"
              },
              "data_sufficiency": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "description": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "percentile_basis": {
                "description": "\"global\" or \"banded\" (24m inspection-activity band)",
                "type": "string"
              },
              "score": {
                "description": "Index 0-100 incl. its own surcharge, higher = riskier",
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharges_applied": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "validation": {
                "additionalProperties": true,
                "description": "v0.5: this index's own historical validation (point-in-time backtest, held-out cohorts)",
                "properties": {
                  "auc_holdout": {
                    "description": "Held-out AUC range on the index's own outcome",
                    "type": "string"
                  },
                  "auc_post_selection_holdout": {
                    "type": "string"
                  },
                  "holdout_origins": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "label": {
                    "description": "The future outcome the index was validated against",
                    "type": "string"
                  },
                  "post_selection_origin": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "source": {
                    "description": "Path of the validation report in docs/research",
                    "type": "string"
                  },
                  "text": {
                    "description": "One-line validation statement — relay with the index",
                    "type": "string"
                  },
                  "top_decile_lift": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "legacy_composite": {
            "additionalProperties": true,
            "description": "v0.5: legacy composite, backward compatibility only",
            "properties": {
              "base_score": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              },
              "rule": {
                "type": "string"
              },
              "rule_text": {
                "type": "string"
              },
              "score": {
                "description": "Legacy composite 0-100 (== top-level carrier_score)",
                "type": [
                  "number",
                  "null"
                ]
              },
              "surcharge": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "validated": {
                "description": "Always false: the composite is not validated or gated",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "legal_name": {
            "$ref": "#/properties/generated"
          },
          "methodology_note": {
            "$ref": "#/properties/legal_name"
          },
          "power_units": {
            "type": [
              "number",
              "null"
            ]
          },
          "report": {
            "description": "Report title line (format=\"json\")",
            "type": "string"
          },
          "report_text": {
            "description": "Filing-ready plain-text evidence report (format=\"text\")",
            "type": "string"
          },
          "safety_rating": {
            "$ref": "#/properties/legal_name"
          },
          "score_version": {
            "$ref": "#/properties/legal_name"
          },
          "scored_as_of": {
            "$ref": "#/properties/legal_name"
          },
          "sha256": {
            "description": "Paid tiers: SHA-256 of the archived plain-text report — cite it alongside the entry id",
            "type": "string"
          },
          "status_code": {
            "$ref": "#/properties/legal_name"
          },
          "sub_indices": {
            "additionalProperties": {
              "additionalProperties": true,
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "description": "Sub-index 0-100, population-relative",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "weight": {
                  "description": "Sub-index weight in the composite",
                  "type": "number"
                }
              },
              "type": "object"
            },
            "type": "object"
          },
          "surcharge": {
            "$ref": "#/properties/power_units"
          }
        },
        "type": "object"
      }
    },
    {
      "description": "Save a named list of carriers (by US DOT number) for continuous monitoring. Requires a paid CarrierScore API key (Monitor or Compliance tier) — connect with your key via OAuth (or set CARRIERSCORE_API_KEY on a self-hosted server); the free tier gets a 403 with an upgrade link.\n\nOnce saved, CarrierScore diffs every carrier on the list against the previous day's scoring run after each daily run and records alerts: new out-of-service order (critical), operating authority lost (critical), insurance filing lapsed (high), operating status leaving Active (high), risk score up 10+ points (medium), high-confidence reincarnated-carrier link appearing (medium). Alerts are always retrievable with list_alerts; optionally they are also pushed to a webhook (JSON POST, HMAC-signed via the X-CarrierScore-Signature header with the per-key secret from GET /v1/lists) and/or summarized in one daily digest email.\n\nUse this when a broker asks to \"watch\" or \"keep an eye on\" their carrier roster. Caps: 500 DOTs total across all lists on the Monitor tier, 5000 on Compliance; up to 50 lists per key. Saving the same DOT twice in one list is deduped.\n\nArgs:\n  - name: short label for the list (1-100 chars)\n  - dot_numbers: array of DOT number strings (1-8 digits each)\n  - webhook_url (optional): https URL to POST new alerts to\n  - email (optional): address for the daily digest\n\nReturns JSON: { list_id, name, dots, created, updated, webhook_url?, email? }. Keep list_id — list_alerts needs it.\n\nErrors: 403 without a paid key; 400 on invalid DOTs, empty list, or exceeding the tier cap (message says which); 401 bad key.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_numbers": {
            "description": "US DOT numbers to monitor",
            "items": {
              "description": "US DOT number of the carrier, digits only (e.g. \"1234567\")",
              "pattern": "^\\d{1,8}$",
              "type": "string"
            },
            "maxItems": 5000,
            "minItems": 1,
            "type": "array"
          },
          "email": {
            "description": "Optional daily digest email",
            "format": "email",
            "type": "string"
          },
          "name": {
            "description": "List name, e.g. \"Active roster Q3\"",
            "maxLength": 100,
            "minLength": 1,
            "type": "string"
          },
          "webhook_url": {
            "description": "Optional https URL to receive alert POSTs",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "name",
          "dot_numbers"
        ],
        "type": "object"
      },
      "name": "save_carrier_list",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "created": {
            "description": "Creation timestamp (ISO 8601 UTC)",
            "type": "string"
          },
          "dots": {
            "description": "US DOT numbers on the list (deduped)",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "email": {
            "description": "Daily digest email, if configured",
            "type": "string"
          },
          "list_id": {
            "description": "Saved list id (lst_...) — use with list_alerts",
            "type": "string"
          },
          "name": {
            "description": "List name",
            "type": "string"
          },
          "updated": {
            "description": "Last update timestamp (ISO 8601 UTC)",
            "type": "string"
          },
          "webhook_url": {
            "description": "Alert webhook URL, if configured",
            "type": "string"
          }
        },
        "required": [
          "list_id",
          "name",
          "dots"
        ],
        "type": "object"
      }
    },
    {
      "description": "Verify an archived Montgomery evidence report by its audit entry id: CarrierScore re-reads the immutable stored copy, recomputes its SHA-256 and reports whether it matches the hash recorded at generation time (and, optionally, a hash the caller supplies — e.g. the sha256 printed on a broker's filed copy). Requires the same paid API key that generated the report.\n\nUse it when a broker or auditor needs to prove that a filed evidence report is exactly what CarrierScore produced on the stated date. match=true means the archived report is byte-identical to what was served; match_supplied compares against the caller's own hash. Follow up with the audit_entries list to find ids, or with montgomery_file to generate a fresh report.\n\nArgs:\n  - entry_id: the audit_entry_id returned by montgomery_file (also listed by audit_entries)\n  - sha256 (optional): a 64-hex SHA-256 to compare against the archived report (text or canonical json)\n\nReturns JSON: { entry_id, dot_number, generated_at, scored_as_of, score_version, format_requested, sha256_stored, sha256_computed, match, sha256_json_stored, sha256_json_computed, match_json, sha256_supplied?, match_supplied? }.\n\nErrors: 403 without a paid key, or (Monitor tier) if the entry is older than the 90-day retrieval window; 404 if the entry id is unknown for this key.",
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "entry_id": {
            "description": "Audit entry id from montgomery_file / audit_entries",
            "pattern": "^\\d{1,8}_\\d{8}T\\d{12}Z_[0-9a-f]{8}$",
            "type": "string"
          },
          "sha256": {
            "description": "Optional SHA-256 to compare against the archived report",
            "pattern": "^[0-9a-fA-F]{64}$",
            "type": "string"
          }
        },
        "required": [
          "entry_id"
        ],
        "type": "object"
      },
      "name": "verify_evidence",
      "outputSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "additionalProperties": false,
        "properties": {
          "dot_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "entry_id": {
            "type": "string"
          },
          "format_requested": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "match": {
            "description": "true = the archived report is byte-identical to what was served",
            "type": "boolean"
          },
          "match_json": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "match_supplied": {
            "description": "Whether the supplied hash matches the archived report",
            "type": "boolean"
          },
          "score_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "scored_as_of": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256_computed": {
            "description": "Hash recomputed now from the stored report text",
            "type": "string"
          },
          "sha256_json_computed": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256_json_stored": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256_stored": {
            "description": "Hash recorded when the report was archived",
            "type": [
              "string",
              "null"
            ]
          },
          "sha256_supplied": {
            "description": "Echo of the hash the caller supplied, if any",
            "type": "string"
          }
        },
        "required": [
          "entry_id",
          "sha256_computed",
          "match"
        ],
        "type": "object"
      }
    }
  ]
}

Verify it yourself

curl -s https://api.teppi.xyz/v1/evidence/sha256:3d19ad399f7358633316aa0d8d5a0f5e4c96d03f5df30f95a471f7c9e16ca769 | sha256sum