carrierscore

Generate Montgomery Evidence File

montgomery_file

Read-onlyIdempotent

Generate a timestamped Montgomery file — a carrier-selection evidence report — for a carrier by US DOT number.

Since 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.

Args:

dot_number: US DOT number, digits only
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)

Returns: 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.

Audit 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.

Errors: 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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`format`	No	"text" = filing-ready report (free tier); "json" = structured fields (requires API key)	text
`dot_number`	Yes	US DOT number of the carrier, digits only (e.g. "1234567")

Output Schema

TableJSON Schema

Name	Required	Description
`flags`	No
`report`	No	Report title line (format="json")
`sha256`	No	Paid tiers: SHA-256 of the archived plain-text report — cite it alongside the entry id
`indices`	No
`dba_name`	No
`composite`	No
`generated`	No	Report generation date (YYYY-MM-DD)
`surcharge`	No
`base_score`	No
`components`	No
`crash_risk`	No	v0.5: crash risk index with components and validation
`disclaimer`	No
`dot_number`	No
`legal_name`	No
`power_units`	No
`report_text`	No	Filing-ready plain-text evidence report (format="text")
`status_code`	No
`sub_indices`	No
`scored_as_of`	No
`carrier_score`	No	0-100, higher = riskier (v0.5: == legacy_composite.score)
`safety_rating`	No
`score_version`	No
`audit_entry_id`	No	Paid tiers: id of the immutable archived copy of this report (use with verify_evidence / audit_entries)
`inspection_risk`	No	v0.5: inspection / compliance risk index with components and validation
`data_sufficiency`	No
`legacy_composite`	No	v0.5: legacy composite, backward compatibility only
`methodology_note`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedAug 18, 2026

addedOutput schema / properties / audit_entry_id

Added value: +{
+  "description": "Paid tiers: id of the immutable archived copy of this report (use with verify_evidence / audit_entries)",
+  "type": "string"
+}

addedOutput schema / properties / sha256

Added value: +{
+  "description": "Paid tiers: SHA-256 of the archived plain-text report — cite it alongside the entry id",
+  "type": "string"
+}

Changed13 schema fields changedAug 17, 2026

changedOutput schema / properties / carrier_score / description

Previous value: -"CarrierScore 0-100, higher = riskier"New value: +"0-100, higher = riskier (v0.5: == legacy_composite.score)"

addedOutput schema / properties / components / additionalProperties / $ref

Added value: +"#/properties/inspection_risk/properties/components/additionalProperties"

removedOutput schema / properties / components / additionalProperties / additionalProperties
```
Removed value: -true
```

removedOutput schema / properties / components / additionalProperties / properties

Removed value: -{
-  "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"
-  }
-}

removedOutput schema / properties / components / additionalProperties / required
```
Removed value: -[
-  "label"
-]
```
removedOutput schema / properties / components / additionalProperties / type
```
Removed value: -"object"
```

addedOutput schema / properties / crash_risk

Added value: +{
+  "$ref": "#/properties/inspection_risk",
+  "description": "v0.5: crash risk index with components and validation"
+}

addedOutput schema / properties / indices / additionalProperties / $ref
```
Added value: +"#/properties/inspection_risk"
```
removedOutput schema / properties / indices / additionalProperties / additionalProperties
```
Removed value: -true
```

removedOutput schema / properties / indices / additionalProperties / properties

Removed value: -{
-  "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": {
-      "$ref": "#/properties/components/additionalProperties"
-    },
-    "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"
-  }
-}

removedOutput schema / properties / indices / additionalProperties / type
```
Removed value: -"object"
```

addedOutput schema / properties / inspection_risk

Added value: +{
+  "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"
+}

addedOutput schema / properties / legacy_composite

Added value: +{
+  "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"
+}

Changed2 schema fields changedAug 17, 2026

addedOutput schema / properties / composite

Added value: +{
+  "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"
+}

addedOutput schema / properties / indices

Added value: +{
+  "additionalProperties": {
+    "additionalProperties": true,
+    "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": {
+          "$ref": "#/properties/components/additionalProperties"
+        },
+        "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"
+      }
+    },
+    "type": "object"
+  },
+  "type": "object"
+}

Changed3 schema fields changedAug 17, 2026

addedOutput schema / properties / methodology_note

Added value: +{
+  "$ref": "#/properties/legal_name"
+}

addedOutput schema / properties / score_version

Added value: +{
+  "$ref": "#/properties/legal_name"
+}

addedOutput schema / properties / sub_indices

Added value: +{
+  "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"
+}

First observedAug 17, 2026

TDQS

A3.7/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description contradicts the annotations. Annotations claim readOnlyHint=true, but the description states that reports are stored immutably server-side (a write side effect) and each call generates a new audit entry, violating idempotentHint=true. Per the rules, this contradiction scores 1.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose and includes substantial detail, but it is verbose (multiple paragraphs, legal background, exhaustive error list). While every sentence adds value, it could be more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 params, output schema, annotations), the description covers purpose, usage, parameters, return values, audit storage, tier limitations, and error conditions. It references sibling tools appropriately and leaves no obvious gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds significant extra meaning: it explains the default format, return structures for each format (text vs json), and the implications of each parameter choice (free tier vs API key). This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate a timestamped Montgomery file — a carrier-selection evidence report — for a carrier by US DOT number.' It uses specific verbs and resources, and the legal context and mention of 'filing-ready' distinguish it from sibling tools like carrier_score or carrier_lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: 'A booking agent should generate and retain this file at the moment a carrier is selected for a load.' It also explains format choices and tier requirements. However, it does not explicitly compare to sibling tools or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All carrierscore tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.