# FMCSA Carrier Intelligence

> US carrier vetting on FMCSA data: authority, insurance, safety, identity links. Pay per call (x402)

- name: io.github.KMCTO/fmcsa-carrier-intelligence
- version: 0.2.0
- connection class: R0 (autonomous)
- trust: 80/100 flags: no-repository
- quality: 70/100 (needs work)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.KMCTO%2Ffmcsa-carrier-intelligence
- tools: https://api.protogrid.dev/v1/servers/io.github.KMCTO%2Ffmcsa-carrier-intelligence/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "fmcsa-carrier-intelligence": {
      "type": "http",
      "url": "https://fmcsa-mcp-843680657471.us-central1.run.app/mcp"
    }
  }
}
```


## Trust

- hygiene: 80
- liveness: 100
- freshness: 100
- provenance: 45
- drivers: +website +reachable +uptime-100% +updated-5d-ago -no-repository
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 70/100 (needs work)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-11-25; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 64 (weight 30)

- pass `tools.descriptions`: every tool has a description
- warn `tools.description_length`: 10 tools have descriptions over 1,024 characters, which crowds the context
- pass `tools.schemas`: every tool has an object input schema
- fail `tools.annotations`: no tool declares readOnlyHint or destructiveHint, so clients cannot tell safe calls from risky ones
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: lookup_carrier (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); screen_carrier_identity (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); check_roster_changes (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); …
- pass `tools.token_cost`: about 5,364 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 75 (weight 15)

- warn `stability.changes`: 11 tool changes in 30 days
- pass `stability.rug_pull`: no tool changed its meaning under the same name

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 16, about 5,364 tokens to load them all
- tool set hash: a0e6471b085ceb628907aa1f7a4e3819
- tools last changed: 2026-10-15T14:12:01.250Z
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.KMCTO/fmcsa-carrier-intelligence.svg)](https://protogrid.dev/servers/io.github.KMCTO/fmcsa-carrier-intelligence)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

- 2026-10-15 `check_broker_authority` added
  - Does this broker hold active broker authority, and what does FMCSA's record say around it? Give exactly one of mc_number (the broker's MC docket, written MC123456, MC-123456 or 123456) or usdot_number. Paid, flat price; billed whenever the carrier resolves, including when it holds no broker authority (that is the answer). An unknown docket or USDOT number is a free not_found; giving neither or both, or a docket FMCSA lists under several carriers without naming a holder, is a free error. Returns holds_active_broker_authority and the broker dockets (docket number, status, how current that status is, active types, first grant and last event dates); the bond (BMC-84/85) on-file flag with its continuity (coverage unbroken since, current gap, closed lapses in 24 and 60 months, longest gap, data-through date); the authority event history (grants, reinstatements, revocations, suspensions, in total and over 24 and 60 months); revocation, suspension and reinstatement flags; and the identity linkage screen. A record, not a recommendation or a rating. How far to trust "holds active broker authority": it is as complete as the two FMCSA sources behind it. FMCSA froze its legacy licensing archive on 2026-05-14, so a docket known only from it (status_source legacy_li) describes that date, and a docket whose status changed afterwards and is not yet on FMCSA's live MOTUS roster is not seen. There is no independent count of real brokers to check against. Confirm the broker's current authority and bond with FMCSA before relying on it.
- 2026-10-15 `get_carrier_selection_record` changed (description)
  - before: One dated, hashed record of what public FMCSA data shows about a carrier, built for a broker's carrier-vetting file. Paid, flat price. It gathers, in one response: the carrier's current profile (authority, insurance flags, FMCSA safety rating and its date, out-of-service orders, fleet and classifications, MCS-150 filing date, first authority grant, revocation, suspension and reinstatement history), the SMS inspection and violation summary with out-of-service rates, the trailing-24-month crash summary, the last year's changes, and the identity-linkage triage screen. review_factors lists each factor a documented review commonly considers and whether this record carries it. It is a record, not a score. It never says a carrier is safe or unsafe, "Unrated" is reported as exactly that, and it is not legal advice or a statement that choosing a carrier was reasonable. This project's own safety_tier_derived is deliberately left out. Integrity: record_hash is the SHA-256 of the record's canonical JSON (see hash_method) without record_hash and verify_url. Keep the record; later, GET verify_url (free) confirms that we issued exactly that hash, when, and for which carrier, so an edited copy is detectable. If the hash cannot be registered the call returns registry_unavailable and is not billed. An unknown USDOT number is a free not_found.
  - after: One dated, hashed record of what public FMCSA data shows about a carrier, built for a broker's carrier-vetting file. Paid, flat price. It gathers, in one response: the carrier's current profile (authority, insurance flags, FMCSA safety rating and its date, out-of-service orders, fleet and classifications, MCS-150 filing date, first authority grant, revocation, suspension and reinstatement history), the SMS inspection and violation summary with out-of-service rates, the trailing-24-month crash summary, the last year's changes, and the identity-linkage triage screen, the insurance continuity history (gaps and cancellations, each with its data-through date) and the authority event history (grants, reinstatements, revocations, suspensions). review_factors lists each factor a documented review commonly considers and whether this record carries it. It is a record, not a score. It never says a carrier is safe or unsafe, "Unrated" is reported as exactly that, and it is not legal advice or a statement that choosing a carrier was reasonable. This project's own safety_tier_derived is deliberately left out. Integrity: record_hash is the SHA-256 of the record's canonical JSON (see hash_method) without record_hash and verify_url. Keep the record; later, GET verify_url (free) confirms that we issued exactly that hash, when, and for which carrier, so an edited copy is detectable. If the hash cannot be registered the call returns registry_unavailable and is not billed. An unknown USDOT number is a free not_found.
- 2026-10-15 `find_carrier_by_mc` changed (description)
  - before: Free. Finds the USDOT number(s) for an operating-authority docket number (MC, MX or FF), so a broker holding the MC number from a rate confirmation can reach the other tools, which take a USDOT number. mc_number may be written "MC123456", "MC-123456", "mc 123456" or just "123456" (a bare number is taken as MC). Almost every docket number belongs to one carrier; a few have been carried by more than one USDOT number, so usdot_numbers is a list (at most 10). Returns only the identifiers, no names or addresses. An unknown docket number is a not_found error; an unreadable one is invalid_arguments. Never billed.
  - after: Free. Finds the USDOT number for an operating-authority docket number (MC, MX or FF), so a broker holding the MC number from a rate confirmation can reach the other tools, which take a USDOT number. mc_number may be written "MC123456", "MC-123456", "mc 123456" or just "123456" (a bare number is taken as MC); zero-padding is ignored, because FMCSA's own files disagree on it. authority_holder_usdot_number is the carrier FMCSA's authority records tie the docket to, and there is never more than one. usdot_numbers lists every carrier that lists the docket (FMCSA's census lists about 26,000 dockets under a second carrier too, so a docket can legitimately appear under two), the holder first. docket_status and status_source say how current that is: "motus" is live, "legacy_li" is FMCSA's archive as of 2026-05-14, "census" is the census file's code. Returns only identifiers and a status, no names or addresses. An unknown docket is a not_found error; an unreadable one is invalid_arguments. Never billed.
- 2026-10-15 `get_inspection_crash_summary` added
  - A carrier's roadside inspection, violation and crash summary on its own. Paid, flat price; billed whenever the USDOT number resolves, even if the carrier had no inspections (that is the finding). An unknown number is a free not_found. inspections (SMS data, a 24-month window that ends weeks before today: read window_end): inspection counts by driver and vehicle, out-of-service counts and rates (FMCSA's own method; no national average is carried, so cite FMCSA's), violation counts in total and by BASIC, last inspection date. When there were no inspections the measures are null, never zero, and data_quality_flags says why: inspection_summary_no_inspections (in SMS, none in the window) or inspection_summary_unavailable (in neither SMS file, so SMS says nothing either way). A carrier inspected only after window_end reads as having none. crashes (federally recordable crashes, trailing 730 days ending at the build date): counts by fatal, injury, tow-away and hazmat release, plus fatalities and injuries and the last crash date. A floor, not a total: about 19% of crash records carry no USDOT number and cannot be attributed to any carrier. Counts, not a rating: this does not say a carrier is safe or unsafe, and it carries no contact information.
- 2026-10-15 `get_carrier_selection_record` added
  - One dated, hashed record of what public FMCSA data shows about a carrier, built for a broker's carrier-vetting file. Paid, flat price. It gathers, in one response: the carrier's current profile (authority, insurance flags, FMCSA safety rating and its date, out-of-service orders, fleet and classifications, MCS-150 filing date, first authority grant, revocation, suspension and reinstatement history), the SMS inspection and violation summary with out-of-service rates, the trailing-24-month crash summary, the last year's changes, and the identity-linkage triage screen. review_factors lists each factor a documented review commonly considers and whether this record carries it. It is a record, not a score. It never says a carrier is safe or unsafe, "Unrated" is reported as exactly that, and it is not legal advice or a statement that choosing a carrier was reasonable. This project's own safety_tier_derived is deliberately left out. Integrity: record_hash is the SHA-256 of the record's canonical JSON (see hash_method) without record_hash and verify_url. Keep the record; later, GET verify_url (free) confirms that we issued exactly that hash, when, and for which carrier, so an edited copy is detectable. If the hash cannot be registered the call returns registry_unavailable and is not billed. An unknown USDOT number is a free not_found.
- 2026-10-15 `check_roster_changes` added
  - Which carriers on your roster changed on or after a date, and what changed: authority, insurance, out-of-service and the other tracked fields, each with its old and new value. Paid, metered: a base price plus a per-roster-entry price, both shown in get_catalog. roster_usdot_numbers is your own list of USDOT numbers (non-empty, at most settings.roster_screen_max_size distinct entries, currently 100: over the limit is a free invalid_arguments, never a truncation). since is an ISO date, YYYY-MM-DD. A roster entry that matches no carrier is listed in roster_not_found but still counts toward the price. "Nothing changed" is a complete answer and bills like any other; a roster where no entry resolves is a free not_found. How fresh this is: changes appear only when the underlying data is refreshed (roughly weekly lately, with no committed schedule), so a change made at FMCSA today may not be here yet. provenance.record_as_of says how current the data is. Only real changes are returned (the warehouse's one-time "field started being tracked" rows are not). At most settings.roster_changes_max_rows changes come back, newest first; truncated says whether more existed. Carries no contact information, and no change to legal_name, dba_name, phone or email, same as get_safety_history.
- 2026-10-15 `find_carrier_by_mc` added
  - Free. Finds the USDOT number(s) for an operating-authority docket number (MC, MX or FF), so a broker holding the MC number from a rate confirmation can reach the other tools, which take a USDOT number. mc_number may be written "MC123456", "MC-123456", "mc 123456" or just "123456" (a bare number is taken as MC). Almost every docket number belongs to one carrier; a few have been carried by more than one USDOT number, so usdot_numbers is a list (at most 10). Returns only the identifiers, no names or addresses. An unknown docket number is a not_found error; an unreadable one is invalid_arguments. Never billed.
- 2026-10-11 `get_safety_history` changed (description)
  - before: Historical snapshots and changelog entries for a carrier. Paid — you pay only when a call returns records; an exact-key miss is free. changelog may legitimately be empty for a carrier without two distinct-date snapshots yet — a diff needs both. authority_types, oos_orders_active, insurance_bipd_on_file, insurance_cargo_on_file, insurance_bond_on_file, has_been_revoked, and last_revocation_date are null (not false/empty) on a history row recorded before 2026-09-02 — carrier_history wasn't tracking those fields yet, so null there means "not tracked on this date," not a negative answer. Likewise has_been_suspended/last_suspension_date are null before 2026-09-06, and has_authority_reinstated/last_reinstatement_date/ has_insurance_identity_mismatch are null before 2026-09-12, and insurance_cancel_pending/days_to_cancel_effective/ soonest_cancel_effective_date are null before 2026-10-04. changelog holds real changes only (change_kind "value_changed"): the row the warehouse writes when a field first starts being tracked is never returned. About 97% of authority_status changes are dated 2026-09-02, when FMCSA's licensing data switched systems; treat that date's authority_status changes with some caution. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile); changelog excludes field_name in {legal_name, dba_name, phone, email} for the same reason — a changed value is still the value.
  - after: Historical snapshots and changelog entries for a carrier. Paid — you pay only when a call returns records; an exact-key miss is free. changelog may legitimately be empty for a carrier without two distinct-date snapshots yet — a diff needs both. authority_types, oos_orders_active, insurance_bipd_on_file, insurance_cargo_on_file, insurance_bond_on_file, has_been_revoked, and last_revocation_date are null (not false/empty) on a history row recorded before 2026-09-02 — carrier_history wasn't tracking those fields yet, so null there means "not tracked on this date," not a negative answer. Likewise has_been_suspended/last_suspension_date are null before 2026-09-06, and has_authority_reinstated/last_reinstatement_date/ has_insurance_identity_mismatch are null before 2026-09-12, and insurance_cancel_pending/days_to_cancel_effective/ soonest_cancel_effective_date are null before 2026-10-04. changelog holds real changes only (change_kind "value_changed"): the row the warehouse writes when a field first starts being tracked is never returned. About 97% of authority_status changes are dated 2026-09-02, when FMCSA's licensing data switched systems; treat that date's authority_status changes with some caution. Likewise most safety_tier_derived changes dated 2026-10-10 come from a method change (a second SMS file added; never-inspected carriers moved from tier 1 to null), not from the carrier. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile); changelog excludes field_name in {legal_name, dba_name, phone, email} for the same reason — a changed value is still the value.
- 2026-10-11 `search_carriers` changed (description)
  - before: Filtered carrier search. Paid — you pay only when a call returns records; a zero-row result is free, same as an exact-key miss. Defaults to Active carriers only — pass include_inactive=true to also see Inactive/Pending. Capped at 100 rows per response regardless of the requested limit; never a full-table dump. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile) — a filterable, multi-result endpoint returning personal contact details for whoever matched a filter was the sharpest version of that risk in this product; use lookup_carrier's claimed_name/claimed_street/etc. if you need to confirm a specific carrier's claimed identity.
  - after: Filtered carrier search. Paid — you pay only when a call returns records; a zero-row result is free, same as an exact-key miss. safety_tier filters on safety_tier_derived: 1 = inspected with zero BASIC alerts, up to 6 = all five BASICs alerted. Carriers with no tier (never inspected, or not in SMS) never match a tier filter. Defaults to Active carriers only — pass include_inactive=true to also see Inactive/Pending. Capped at 100 rows per response regardless of the requested limit; never a full-table dump. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile) — a filterable, multi-result endpoint returning personal contact details for whoever matched a filter was the sharpest version of that risk in this product; use lookup_carrier's claimed_name/claimed_street/etc. if you need to confirm a specific carrier's claimed identity.
- 2026-10-04 `get_safety_history` changed (description)
  - before: Historical snapshots and changelog entries for a carrier. Paid — you pay only when a call returns records; an exact-key miss is free. changelog may legitimately be empty for a carrier without two distinct-date snapshots yet — a diff needs both. authority_types, oos_orders_active, insurance_bipd_on_file, insurance_cargo_on_file, insurance_bond_on_file, has_been_revoked, and last_revocation_date are null (not false/empty) on a history row recorded before 2026-09-02 — carrier_history wasn't tracking those fields yet, so null there means "not tracked on this date," not a negative answer. Likewise has_been_suspended/last_suspension_date are null before 2026-09-06, and has_authority_reinstated/last_reinstatement_date/ has_insurance_identity_mismatch are null before 2026-09-12. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile); changelog excludes field_name in {legal_name, dba_name, phone, email} for the same reason — a changed value is still the value.
  - after: Historical snapshots and changelog entries for a carrier. Paid — you pay only when a call returns records; an exact-key miss is free. changelog may legitimately be empty for a carrier without two distinct-date snapshots yet — a diff needs both. authority_types, oos_orders_active, insurance_bipd_on_file, insurance_cargo_on_file, insurance_bond_on_file, has_been_revoked, and last_revocation_date are null (not false/empty) on a history row recorded before 2026-09-02 — carrier_history wasn't tracking those fields yet, so null there means "not tracked on this date," not a negative answer. Likewise has_been_suspended/last_suspension_date are null before 2026-09-06, and has_authority_reinstated/last_reinstatement_date/ has_insurance_identity_mismatch are null before 2026-09-12, and insurance_cancel_pending/days_to_cancel_effective/ soonest_cancel_effective_date are null before 2026-10-04. changelog holds real changes only (change_kind "value_changed"): the row the warehouse writes when a field first starts being tracked is never returned. About 97% of authority_status changes are dated 2026-09-02, when FMCSA's licensing data switched systems; treat that date's authority_status changes with some caution. Carries no contact information (legal_name, dba_name, addresses, phone, email — removed 2026-09-19, see schemas.CarrierProfile); changelog excludes field_name in {legal_name, dba_name, phone, email} for the same reason — a changed value is still the value.

Full history: https://api.protogrid.dev/v1/servers/io.github.KMCTO%2Ffmcsa-carrier-intelligence/changes

## Remotes

- https://fmcsa-mcp-843680657471.us-central1.run.app/mcp (streamable-http, auth none, reachable true, uptime30d 1)

## Packages

_none_

## Tools (16)

- `check_address_consistency`: How many distinct business addresses and phones this carrier
reports across FMCSA's independent records of it (census
registration, licensing and insurance filings, and its own
self-reported crash records). Mailing addresses are excluded —
differing from the physical address there is normal.

Paid. Cheaper than either identity tool; one row, no graph.

- `check_applicant_against_roster`: Screens one applicant carrier against a roster of carriers you
already do business with (or are vetting) — the batch generalization
of confirm_identity_link, for the real-world case of catching a
carrier that was previously cut from your network (revoked,
suspended, or otherwise let go) trying to re-enter under a new USDOT
number. usdot_number is the applicant; roster_usdot_numbers is your
own list, supplied by you.

Returns linked (true if the applicant shares an identity cluster with
ANY roster member) and matched_roster_usdot_numbers (which ones,
always a subset of what you supplied — never a carrier you didn't
already name). roster_not_found lists any roster entries that simply
don't resolve to a known carrier (still your own input, not a new
disclosure). usdot_number's own cluster_id is always included, same
as check_carrier_identity's convention — it's the applicant's own
data, not something withheld pending a match.

usdot_number must not also appear in roster_usdot_numbers, and
roster_usdot_numbers must be a non-empty list of at most
settings.roster_screen_max_size distinct entries (currently 100) —
either violation is a free invalid_arguments; split a larger roster
into multiple calls rather than expecting it to be truncated for you.
An unresolved usdot_number (the applicant itself) is a free not_found,
same as confirm_identity_link/check_carrier_identity.

Paid, metered: price = price_check_applicant_against_roster_base +
price_check_applicant_against_roster_per_entry * (the deduped roster
size) — see get_catalog for current rates. A "not linked to anything
on your roster" result is a complete, valuable answer and bills the
same as a match, same reasoning as check_carrier_identity's
cluster_size == 1.

- `check_broker_authority`: Does this broker hold active broker authority, and what does FMCSA's
record say around it? Give exactly one of mc_number (the broker's MC
docket, written MC123456, MC-123456 or 123456) or usdot_number. Paid, flat
price; billed whenever the carrier resolves, including when it holds no
broker authority (that is the answer). An unknown docket or USDOT number
is a free not_found; giving neither or both, or a docket FMCSA lists under
several carriers without naming a holder, is a free error.

Returns holds_active_broker_authority and the broker dockets (docket
number, status, how current that status is, active types, first grant and
last event dates); the bond (BMC-84/85) on-file flag with its continuity
(coverage unbroken since, current gap, closed lapses in 24 and 60 months,
longest gap, data-through date); the authority event history (grants,
reinstatements, revocations, suspensions, in total and over 24 and 60
months); revocation, suspension and reinstatement flags; and the identity
linkage screen. A record, not a recommendation or a rating.

How far to trust "holds active broker authority": it is as complete as the
two FMCSA sources behind it. FMCSA froze its legacy licensing archive on
2026-05-14, so a docket known only from it (status_source legacy_li)
describes that date, and a docket whose status changed afterwards and is
not yet on FMCSA's live MOTUS roster is not seen. There is no independent
count of real brokers to check against. Confirm the broker's current
authority and bond with FMCSA before relying on it.

- `check_carrier_identity`: Full identity-linkage detail for a carrier: why it's flagged and how
confident that is. Priced meaningfully above the free
screen_carrier_identity — call that first if you only need the flag
and a count.

Never names or points at another carrier (redesigned 2026-09-18 — see
schemas.IdentityAssessment's docstring): no linked USDOT number, legal
name, or shared-identifier hash. A linked carrier's own identity was
never this caller's to receive, and an unsalted hash of a low-entropy
value like a phone number or address doesn't meaningfully withhold it
from a determined party anyway (confirmed by reading Truckin's own
hashing code). Every field here is either the subject carrier's own
data or a derivative signal — a score, a match-term-type label
(which *kind* of identifier matched, never the value), a count, a
boolean.

SSN and EIN matches carry weight 2.0 each in FMCSA's ARCHI methodology
and are not present in public data; D&B is nominally weight 2.0 too
but is only genuinely available for ~4% of carriers, and officer data
(needed for the name x officer term) is missing for another ~15%. So
score_provenance.match_score_ceiling is computed per carrier, not a
flat 4.5 — most responses cap out at 2.5 or lower. It also states
plainly that recall against FMCSA's own declared-predecessor label
set is not measurable. flagged applies FMCSA's own ARCHI flag rule
(match_score >= 1.5 AND a linked motive >= 1); it is not a fraud
determination and must not be presented as one. Note flagged and
match_score >= 1.5 are NOT the same condition — clustering requires
2+ independent identifier-type families to agree, so materially more
carriers clear the score threshold than are ever flagged.

Paid. A carrier with no linked carriers is a complete answer and
bills; an unknown USDOT number is a free not_found.

- `check_roster_changes`: Which carriers on your roster changed on or after a date, and what
changed: authority, insurance, out-of-service and the other tracked
fields, each with its old and new value. Paid, metered: a base price plus
a per-roster-entry price, both shown in get_catalog.

roster_usdot_numbers is your own list of USDOT numbers (non-empty, at
most settings.roster_screen_max_size distinct entries, currently 100:
over the limit is a free invalid_arguments, never a truncation). since is
an ISO date, YYYY-MM-DD. A roster entry that matches no carrier is
listed in roster_not_found but still counts toward the price. "Nothing
changed" is a complete answer and bills like any other; a roster where
no entry resolves is a free not_found.

How fresh this is: changes appear only when the underlying data is
refreshed (roughly weekly lately, with no committed schedule), so a
change made at FMCSA today may not be here yet. provenance.record_as_of
says how current the data is. Only real changes are returned (the
warehouse's one-time "field started being tracked" rows are not). At
most settings.roster_changes_max_rows changes come back, newest first;
truncated says whether more existed. Carries no contact information, and
no change to legal_name, dba_name, phone or email, same as
get_safety_history.

- `confirm_identity_link`: Confirms or denies that two carriers YOU ALREADY SUSPECT are linked
in fact share an identity cluster — the lower-risk alternative to
check_carrier_identity's removed linked_carriers field (see
schemas.IdentityAssessment's docstring for why that was removed
2026-09-18).

This never discloses a carrier's identity to a caller who didn't
already have it: both usdot_number_a and usdot_number_b are supplied
by you. It only ever answers "do these two specific carriers share a
cluster?", never "who is linked to this carrier?" — call
check_carrier_identity for that, which stops at a score and a count
for exactly this reason. cluster_id is returned only when linked is
true, and isn't new information even then — you could obtain the same
value directly from either carrier's own check_carrier_identity or
screen_carrier_identity response.

usdot_number_a and usdot_number_b must differ (invalid_arguments,
free — there is no comparison to make). Either number failing to
resolve in carrier_identity_cluster is a free not_found, same as
check_carrier_identity.

Paid — pricier than check_carrier_identity, since it resolves two
carriers' clusters per call, not one. A "not linked" result is a
complete, valuable answer and bills the same as "linked", same
reasoning as check_carrier_identity's cluster_size == 1.

- `find_carrier_by_mc`: Free. Finds the USDOT number for an operating-authority docket number
(MC, MX or FF), so a broker holding the MC number from a rate
confirmation can reach the other tools, which take a USDOT number.

mc_number may be written "MC123456", "MC-123456", "mc 123456" or just
"123456" (a bare number is taken as MC); zero-padding is ignored, because
FMCSA's own files disagree on it. authority_holder_usdot_number is the
carrier FMCSA's authority records tie the docket to, and there is never
more than one. usdot_numbers lists every carrier that lists the docket
(FMCSA's census lists about 26,000 dockets under a second carrier too, so
a docket can legitimately appear under two), the holder first. docket_status
and status_source say how current that is: "motus" is live, "legacy_li" is
FMCSA's archive as of 2026-05-14, "census" is the census file's code.
Returns only identifiers and a status, no names or addresses. An unknown
docket is a not_found error; an unreadable one is invalid_arguments.
Never billed.

- `get_carrier_selection_record`: One dated, hashed record of what public FMCSA data shows about a
carrier, built for a broker's carrier-vetting file. Paid, flat price.

It gathers, in one response: the carrier's current profile (authority,
insurance flags, FMCSA safety rating and its date, out-of-service
orders, fleet and classifications, MCS-150 filing date, first authority
grant, revocation, suspension and reinstatement history), the SMS
inspection and violation summary with out-of-service rates, the
trailing-24-month crash summary, the last year's changes, and the
identity-linkage triage screen, the insurance continuity history (gaps and
cancellations, each with its data-through date) and the authority event
history (grants, reinstatements, revocations, suspensions). review_factors lists each factor a
documented review commonly considers and whether this record carries it.

It is a record, not a score. It never says a carrier is safe or unsafe,
"Unrated" is reported as exactly that, and it is not legal advice or a
statement that choosing a carrier was reasonable. This project's own
safety_tier_derived is deliberately left out.

Integrity: record_hash is the SHA-256 of the record's canonical JSON (see
hash_method) without record_hash and verify_url. Keep the record; later,
GET verify_url (free) confirms that we issued exactly that hash, when, and
for which carrier, so an edited copy is detectable. If the hash cannot be
registered the call returns registry_unavailable and is not billed. An
unknown USDOT number is a free not_found.

- `get_catalog`: Free, unauthenticated dataset catalog.

Describes every table this service sells, its fields, current pricing,
and freshness. Read this before paying for anything.

- `get_identity_sample`: Free, unauthenticated sample of identity/fraud responses, covering
both screen_carrier_identity's free IdentityScreen shape and
check_carrier_identity's paid IdentityAssessment shape.

Lets a buying agent see the paid response shape and evaluate data
quality before spending USDC on check_carrier_identity.

- `get_inspection_crash_summary`: A carrier's roadside inspection, violation and crash summary on its
own. Paid, flat price; billed whenever the USDOT number resolves, even if
the carrier had no inspections (that is the finding). An unknown number is
a free not_found.

inspections (SMS data, a 24-month window that ends weeks before today:
read window_end): inspection counts by driver and vehicle, out-of-service
counts and rates (FMCSA's own method; no national average is carried, so
cite FMCSA's), violation counts in total and by BASIC, last inspection
date. When there were no inspections the measures are null, never zero,
and data_quality_flags says why: inspection_summary_no_inspections (in
SMS, none in the window) or inspection_summary_unavailable (in neither
SMS file, so SMS says nothing either way). A carrier inspected only after
window_end reads as having none.

crashes (federally recordable crashes, trailing 730 days ending at the
build date): counts by fatal, injury, tow-away and hazmat release, plus
fatalities and injuries and the last crash date. A floor, not a total:
about 19% of crash records carry no USDOT number and cannot be attributed
to any carrier.

Counts, not a rating: this does not say a carrier is safe or unsafe, and
it carries no contact information.

- `get_safety_history`: Historical snapshots and changelog entries for a carrier. Paid —
you pay only when a call returns records; an exact-key miss is free.

changelog may legitimately be empty for a carrier without two
distinct-date snapshots yet — a diff needs both. authority_types,
oos_orders_active, insurance_bipd_on_file, insurance_cargo_on_file,
insurance_bond_on_file, has_been_revoked, and last_revocation_date are
null (not false/empty) on a history row recorded before 2026-09-02 —
carrier_history wasn't tracking those fields yet, so null there means
"not tracked on this date," not a negative answer. Likewise
has_been_suspended/last_suspension_date are null before 2026-09-06,
and has_authority_reinstated/last_reinstatement_date/
has_insurance_identity_mismatch are null before 2026-09-12, and
insurance_cancel_pending/days_to_cancel_effective/
soonest_cancel_effective_date are null before 2026-10-04. changelog
holds real changes only (change_kind "value_changed"): the row the
warehouse writes when a field first starts being tracked is never
returned. About 97% of authority_status changes are dated 2026-09-02,
when FMCSA's licensing data switched systems; treat that date's
authority_status changes with some caution. Likewise most
safety_tier_derived changes dated 2026-10-10 come from a method change
(a second SMS file added; never-inspected carriers moved from tier 1
to null), not from the carrier. Carries no
contact information (legal_name, dba_name, addresses, phone, email —
removed 2026-09-19, see schemas.CarrierProfile); changelog excludes
field_name in {legal_name, dba_name, phone, email} for the same reason
— a changed value is still the value.

- `get_sample`: Free, unauthenticated sample of carrier_profile rows.

Lets a buying agent evaluate data quality before spending USDC on the
paid tools.

- `lookup_carrier`: Look up a single carrier's current profile by USDOT number. Paid —
you pay only when a call returns records; an exact-key miss is free.

Returns every carrier_status (Active, Inactive, Pending) — check the
carrier_status field, don't assume Active.

insurance_cancel_pending is true when an insurance cancellation is on
file and not yet effective as of record_as_of (rare: dozens of carriers,
not thousands). Compare soonest_cancel_effective_date with today: the
data is a monthly snapshot, so the cancellation may already have taken
effect. days_to_cancel_effective counts from record_as_of, not today.

Carries no contact information (legal_name, dba_name, addresses,
phone, email — removed 2026-09-19, see schemas.CarrierProfile). The one
legitimate use those fields served — confirming a carrier's claimed
identity against records, e.g. to catch a carrier-identity-theft
("double brokering") attempt — is available instead via claimed_name
(matched against legal_name OR dba_name) and claimed_street/
claimed_city/claimed_state/claimed_zip (matched against
physical_address; supply any subset). Returns name_match/
physical_address_match as a boolean per claim actually supplied, `null`
for a claim not supplied — never the value on file itself.

- `screen_carrier_identity`: Free triage screen for a carrier: whether it's flagged under FMCSA's
own chameleon-carrier methodology, how big its identity cluster is,
and how many linked carriers carry a motive — with no member detail.
Call check_carrier_identity (paid) for that.

This is the entire discovery/sales motion in an agent-only channel,
not a discount tier — free by design (Identity-API-Revision-
2026-09-06.md Section 1), so it never bills and never requires
payment. By the same design, it withholds anything that identifies a
linked carrier: no member USDOT number, no legal name, no link type,
no identifier hash. A caller learns THAT there is something to look
at here, not WHAT.

confidence_caveat discloses the known ~6% artifact rate and that
recall is not measurable in FMCSA's public data — read it, don't just
check the flagged boolean. match_score_practical_ceiling is computed
per carrier from which ARCHI terms were actually available for it,
not a flat constant — most carriers cap out well below the
theoretical 8.5.

An unknown USDOT number returns a not_found error.

- `search_carriers`: Filtered carrier search. Paid — you pay only when a call returns
records; a zero-row result is free, same as an exact-key miss.

safety_tier filters on safety_tier_derived: 1 = inspected with zero
BASIC alerts, up to 6 = all five BASICs alerted. Carriers with no tier
(never inspected, or not in SMS) never match a tier filter.

Defaults to Active carriers only — pass include_inactive=true to also
see Inactive/Pending. Capped at 100 rows per response regardless of the
requested limit; never a full-table dump. Carries no contact
information (legal_name, dba_name, addresses, phone, email — removed
2026-09-19, see schemas.CarrierProfile) — a filterable, multi-result
endpoint returning personal contact details for whoever matched a
filter was the sharpest version of that risk in this product; use
lookup_carrier's claimed_name/claimed_street/etc. if you need to
confirm a specific carrier's claimed identity.