FMCSA Carrier Intelligence

check_roster_changes

Read-onlyIdempotent

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.

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": {
      "roster_usdot_numbers": "<roster_usdot_numbers>",
      "since": "<since>"
    },
    "name": "check_roster_changes"
  }
}

Input Schema

Name	Required	Description	Default
`since`	Yes	ISO date (YYYY-MM-DD); report changes recorded on or after it.
`roster_usdot_numbers`	Yes	Your own roster: 1 to 100 USDOT numbers. Duplicates are counted once; the price depends on the size.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 9, 2026

addedInput schema / properties / roster_usdot_numbers / description

Added value: +"Your own roster: 1 to 100 USDOT numbers. Duplicates are counted once; the price depends on the size."

addedInput schema / properties / since / description

Added value: +"ISO date (YYYY-MM-DD); report changes recorded on or after it."

AddedOct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds a lot: metered billing with a base plus per-entry price, unresolved entries still billed, free invalid_arguments and not_found, roughly weekly refresh with no committed schedule, provenance.record_as_of, a max-row cap with a truncated flag, newest-first ordering, and suppression of one-time tracking rows. It also states the explicit field exclusions (contact info, legal_name, dba_name, phone, email).

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?

Front-loaded with the core answer, then parameter constraints, then freshness, then result-shape limits. Some restatement of schema detail (ISO date format) and dense parenthetical clauses cost a little, but nearly every sentence carries operational value.

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?

With no output schema, the description still conveys the return shape (old/new values per field, roster_not_found, truncated, provenance.record_as_of) and the freshness caveat that governs interpretation. For a metered, refresh-dependent tool, this is complete enough to call and to read results correctly.

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 both parameters are already documented. The description still adds meaning: non-empty roster, at most settings.roster_screen_max_size distinct entries (currently 100) with an over-limit call being a free invalid_arguments rather than a truncation, and duplicate handling. That goes beyond the schema's wording.

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+resource+scope: carriers on your roster that changed on or after a date, plus the tracked fields (authority, insurance, out-of-service) and old/new values. This is concrete enough to separate it from sibling lookups such as get_safety_history or check_applicant_against_roster.

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 substantive guidance on cost expectations (paid, metered, see get_catalog), the constraints on roster size, and the meaning of empty and all-unresolved results. It does not spell out explicit when-not-to-use conditions versus other roster checks, but the context is clear enough to select it confidently.

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