Skip to main content
Glama

carrierscore

by io.carrierscore

Get Carrier Risk Indices

carrier_score
Read-onlyIdempotent

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.

This 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:

  • 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).

  • 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). Present 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.

Returns JSON: { dot_number, legal_name, inspection_risk: { label, description, score, base, surcharge, percentile_basis, band, band_note, data_sufficiency, components: { : { 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).

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

Errors: 404 if the DOT is not in the scored population; 503 if scores have not been computed yet.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dot_numberYesUS DOT number of the carrier, digits only (e.g. "1234567")

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
flagsYesHard flags (OOS order, no insurance, reincarnation link)
indicesNov0.4 only: inspection_risk / crash_risk first-class indices (0-100), each with components, percentile basis and band
compositeNov0.4 only: how the headline carrier_score is derived from the two indices
surchargeNoAdditional points from hard flags
base_scoreNoScore before hard-flag surcharges (v0.5: legacy composite base)
componentsYesFlat 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)
crash_riskNov0.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.
disclaimerNoMethodology disclaimer — relay verbatim
dot_numberYesUS DOT number
legal_nameNo
sub_indicesNov0.3 only: inspection_risk / crash_risk sub-indices (0-100) and their weights
scored_as_ofNoDate of the scoring run (YYYY-MM-DD)
carrier_scoreNo0-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
score_versionNoDocumented methodology version ("0.5" is the served default; "0", "0.3", "0.4" are opt-in)
inspection_riskNov0.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.
data_sufficiencyNo0-1: share of the score resting on observed vs neutral-imputed data
legacy_compositeNov0.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.
methodology_noteNoOne-line description of the weighting used

TDQS

A4.4/5.0
Behavior5/5

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

Even though annotations already declare readOnly/idempotent, the description adds substantial behavior: two separately validated indices, point-in-time data, legacy_composite being unvalidated, hard flags adding surcharges, data_sufficiency caveats, and 404/503 error conditions. This goes far beyond the annotation safety profile.

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

Conciseness4/5

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

The description is long but densely informative and front-loaded with the core purpose. It could be tightened because the inline JSON return shape duplicates what an output schema would provide, but each section (methodology, interpretation, errors) earns its place.

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?

For a complex, high-stakes risk tool, the description covers inputs, output shape, methodology versions, validation status, flags, data sufficiency, booking-decision interpretation, backward compatibility, and error semantics. It is fully self-sufficient for an agent to select and invoke correctly.

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

Parameters3/5

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

The only parameter dot_number is already fully described in the schema with type, pattern, and example. The description merely references 'US DOT number' and adds no additional semantic detail, so baseline 3 is appropriate given 100% schema coverage.

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 opens with a specific verb and resource: 'Get the CarrierScore risk indices for a carrier by US DOT number.' It clearly identifies the two indices and distinguishes this risk-scoring tool from sibling lookup/monitoring tools by positioning it as the core booking-safety signal.

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?

It provides strong context ('core is this carrier safe to book? signal') and explicit interpretation guidance ('treat the indices as documented decision-support evidence, not an approve/deny verdict', 'never present it as the carrier's risk score'). It does not name sibling alternatives directly, but gives clear when-to-use and when-not-to-use framing.

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

All carrierscore toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation5/5

Each tool targets a distinct function: identity lookup, detailed risk scoring, batch monitoring, alert history, report generation, and list management. There is no meaningful overlap between them; even carrier_score and montgomery_file differ in that one returns raw indices and the other produces a documented artifact.

Naming Consistency4/5

All names use snake_case and are readable, but there is a slight mix of verb-first (list_alerts, monitor_carriers, save_carrier_list) and noun-first (carrier_lookup, carrier_score, montgomery_file) patterns. This is a minor deviation; the names are still clear and predictable.

Tool Count5/5

Six tools is well-scoped for a domain-specific risk-assessment API. Each tool serves a clear purpose in the workflow, covering identity verification, scoring, batch checks, monitoring, alerting, and report generation without bloat.

Completeness4/5

The core lifecycle is covered: lookup, score, monitor, alert, report. However, there is no tool to update or delete a saved carrier list, nor a way to list the current contents of a list. These are minor gaps that can be worked around by creating new lists or relying on alert data.

Resources