Skip to main content
Glama
Sign In

FMCSA Carrier Intelligence

by io.github.KMCTO
OverviewDiscussionsAdmin

lookup_carrier

Read-onlyIdempotent

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "usdot_number": "<usdot_number>"
    },
    "name": "lookup_carrier"
  }
}

Input Schema

NameRequiredDescriptionDefault
claimed_zipNoOptional: claimed ZIP code.
claimed_cityNoOptional: claimed city, used with the other claimed_* address fields.
claimed_nameNoOptional: the legal or DBA name the carrier claims; returns name_match true/false, never the name on file.
usdot_numberYesCarrier USDOT number (digits only), the canonical FMCSA carrier identifier.
claimed_stateNoOptional: claimed two-letter US state code.
claimed_streetNoOptional: claimed street address; compared with the physical address on file.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / claimed_city / description
      Added value: +"Optional: claimed city, used with the other claimed_* address fields."
    • addedInput schema / properties / claimed_name / description
      Added value: +"Optional: the legal or DBA name the carrier claims; returns name_match true/false, never the name on file."
    • addedInput schema / properties / claimed_state / description
      Added value: +"Optional: claimed two-letter US state code."
    • addedInput schema / properties / claimed_street / description
      Added value: +"Optional: claimed street address; compared with the physical address on file."
    • addedInput schema / properties / claimed_zip / description
      Added value: +"Optional: claimed ZIP code."
    • addedInput schema / properties / usdot_number / description
      Added value: +"Carrier USDOT number (digits only), the canonical FMCSA carrier identifier."
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial value beyond them: a pay-per-record-returned pricing model with free exact-key misses, a monthly snapshot with record_as_of semantics, the rarity of insurance_cancel_pending, days_to_cancel_effective being relative to record_as_of not today, and a dated removal of contact fields. The privacy guarantee that claim results are booleans and never the on-file value is exactly the kind of behavior an agent cannot infer from structured fields.

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 core operation and cost model are front-loaded, then edge cases follow in short paragraphs. Some interpretive detail about insurance_cancel_pending and days_to_cancel_effective is dense for a description, but with no output schema it earns its place; a tighter list format would read better.

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

Completeness4/5

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

With no output schema, the description carries the burden of return semantics and does so for the tricky fields (carrier_status, name_match, physical_address_match, insurance flags). It does not enumerate the rest of the returned profile, so an agent still doesn't know the full shape of a successful response.

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 the baseline is 3, and the description genuinely adds meaning on top: claimed_name is matched against legal_name OR dba_name, the address claims are matched against physical_address, any subset may be supplied, and unsupplied claims return null rather than false. These matching and null-vs-false semantics are the main thing an agent could get wrong and are spelled out.

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?

Opens with a specific verb and resource plus an explicit key: "Look up a single carrier's current profile by USDOT number." The single-record/by-USDOT scoping distinguishes it from list-style siblings such as search_carriers and from MC-number lookups without the agent needing to open the schema.

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?

Gives clear operational context: check the carrier_status field rather than assuming Active, and use claimed_* fields for identity confirmation (e.g., double-brokering checks). It does not name an alternative tool or state when NOT to use this (e.g., 'if you have an MC number, use find_carrier_by_mc'), so it stops short of explicit routing.

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

All FMCSA Carrier Intelligence toolsInspect
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.

Resources