Skip to main content
Glama

carrierscore

by io.carrierscore

Get Alerts for a Saved Carrier List

list_alerts
Read-onlyIdempotent

Retrieve the alert history for a saved carrier list (see save_carrier_list), newest first. Requires the same paid API key that saved the list.

Each alert records one change detected between consecutive daily scoring runs for one carrier: type (oos_order_activated, authority_lost, insurance_lapsed, status_changed, inspection_risk_jump, crash_risk_jump, score_jump, reincarnation_link), severity (critical / high / medium / low), the field that changed with its before/after values, the DOT and legal name, and the scoring dates compared. inspection_risk_jump / crash_risk_jump (index base up >= 10 points, medium) are the primary deterioration signals; score_jump on the legacy composite is emitted at low severity for backward compatibility. Use it to answer "did anything change on my carrier list?" — critical alerts (new OOS order, authority lost) mean the carrier should not be dispatched until verified; follow up with carrier_score or montgomery_file for the full picture.

Args:

  • list_id: the lst_... id returned by save_carrier_list

  • since (optional): YYYY-MM-DD; only alerts from scoring runs on/after this date

Returns JSON: { list_id, since, count, alerts: [{ ts, as_of, prev_as_of, list_id, list_name, dot, legal_name, type, severity, field, before, after }] }. An empty alerts array means no monitored change since the given date (alerts only exist once two daily scoring runs have happened).

Errors: 403 without a paid key; 404 if the list id is unknown for this key; 400 if since is not YYYY-MM-DD.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sinceNoOnly alerts from scoring runs on/after this date (YYYY-MM-DD)
list_idYesSaved list id from save_carrier_list

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countYesNumber of alerts returned
sinceNoLower bound applied (YYYY-MM-DD) or null
alertsYesAlert history, newest first
list_idYes

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint/idempotentHint annotations, the description details the alert generation process (only after two daily scoring runs), the alert types and severity semantics, and the exact error codes (403/404/400). This gives the agent a clear model of the tool's behavior without contradicting the annotations.

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 approximately 250 words, organized into three paragraphs. It is dense but structured: purpose first, then alert semantics, then args/returns/errors. Some details duplicate the output schema, but the length is justified by the tool's complexity. A 4 rather than 5 due to redundancy with schema.

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?

The description covers the tool's purpose, usage context, alert taxonomy, return shape, error conditions, and prerequisite. It also explains edge cases like empty alerts and the necessity of two scoring runs, making it complete for an agent to 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?

Schema coverage is 100%, so the baseline is 3. The description adds only marginal parameter context (e.g., list_id comes from save_carrier_list and since filters by scoring run date), but these are also present in the schema. Therefore no significant extra semantics beyond the schema are provided.

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 'Retrieve the alert history for a saved carrier list,' a specific verb and resource naming. It distinguishes this tool from siblings by explicitly directing follow-up to carrier_score or montgomery_file and referencing save_carrier_list.

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

Usage Guidelines5/5

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

It explicitly answers 'did anything change on my carrier list?' and says critical alerts mean 'the carrier should not be dispatched until verified.' It names alternatives for follow-up and states the paid API prerequisite, giving clear when-to-use guidance.

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