> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexusfeed.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Every tool the NexusFeed MCP server exposes, what it does, and when an agent should call it.

The NexusFeed MCP server exposes five tools across two sub-servers (`nexusfeed-ltl` and `nexusfeed-abc`) and two prompt templates. Each tool wraps one of the REST endpoints documented in the [API Reference](/api-reference) — the MCP payloads and JSON responses are identical.

## LTL sub-server (`nexusfeed-ltl`)

<AccordionGroup>
  <Accordion title="list_carriers">
    **What it does:** Returns all ten supported LTL carriers with their SCAC codes, full names, headquarters, and coverage.

    **When to call it:** At the start of a conversation when the agent needs to know which carrier codes are valid. Also useful as a "what's available" query.

    **Underlying endpoint:** `GET /v1/ltl/carriers`

    **Example agent prompt:** "What LTL carriers can NexusFeed look up?"
  </Accordion>

  <Accordion title="get_fuel_surcharge">
    **What it does:** Returns the current and historical fuel surcharge rate for one carrier, with optional history depth (1-26 weeks). Includes the DOE diesel price (on carriers that publish it) and a `_verifiability` block.

    **When to call it:** Whenever the user asks for a fuel surcharge rate, wants to verify an invoice, or wants to compare carriers. This is the most-called tool in the LTL sub-server.

    **Parameters:**

    * `carrier` (required): SCAC code — ODFL, SAIA, ESTES, ABF, RLC, TFORCE, XPO, SEFL, AVERITT, FEDEX
    * `weeks` (optional, default 4): Integer 1-26

    **Underlying endpoint:** `GET /v1/ltl/fuel-surcharge`

    **Example agent prompt:** "What's ODFL's fuel surcharge this week?" or "Compare ODFL, Saia, and Estes fuel surcharges for the last 4 weeks."
  </Accordion>

  <Accordion title="get_accessorials">
    **Status:** Coming soon. Returns `404 COMING_SOON` today.

    **What it will do:** Return the accessorial fee schedule for a carrier (liftgate, residential delivery, re-delivery, inside delivery, limited access, notification, appointment).

    **Underlying endpoint:** `GET /v1/ltl/accessorials`
  </Accordion>
</AccordionGroup>

## ABC sub-server (`nexusfeed-abc`)

<AccordionGroup>
  <Accordion title="search_licenses">
    **What it does:** Searches for liquor licenses in a given state by trade name, owner name, or address. Returns a list of matching records with status, expiration, license type, and a `_verifiability` block.

    **When to call it:** Whenever the user has a business name or owner but not a specific license number. At least one of `dba_name`, `owner_name`, or `address` must be provided.

    **Parameters:**

    * `state` (required): Two-letter code — CA, TX, NY, FL, IL
    * `dba_name` (optional): Trade name, partial match supported
    * `owner_name` (optional): Holder name, partial match supported
    * `address` (optional): Street/city filter

    **Underlying endpoint:** `GET /v1/abc/search`

    **Example agent prompt:** "Search California ABC for all Trader Joe's licenses." or "Does this New York bar named 'Employees Only' have a current liquor license?"
  </Accordion>

  <Accordion title="get_license">
    **What it does:** Direct lookup of a single license by its state-issued number. Returns one record or 404 if not found.

    **When to call it:** When the user has a specific license number and wants precise verification — an insurance binding check, a compliance audit trail, a due-diligence lookup.

    **Parameters:**

    * `license_number` (required): State-issued license number
    * `state` (required): Two-letter code matching the license

    **Underlying endpoint:** `GET /v1/abc/license/{license_number}`

    **Example agent prompt:** "Look up California ABC license 47-123456."
  </Accordion>
</AccordionGroup>

## Prompt templates

Both sub-servers ship with prompt templates that agents can use for common workflows.

### `ltl_fuel_surcharge_audit`

Instructs the agent to fetch a carrier's current rate and check the response against a user-supplied invoice rate, flagging discrepancies.

### `abc_license_compliance_check`

Instructs the agent to look up a specific license, verify it is ACTIVE and not expired, and return a pass/fail with the source evidence URL.

## How tools behave under error

* `UNAUTHORIZED` (401) — surface a clear "API key invalid" message; don't retry.
* `PRODUCT_NOT_ENABLED` (403) — tell the user they need to subscribe to the other RapidAPI listing.
* `NOT_FOUND` (404) — report the carrier/state/license as unsupported.
* `SOURCE_UNAVAILABLE` (503) — the upstream carrier or agency site failed. Retry after a delay, or report the outage.
* `CAPTCHA_SOLVER_NOT_CONFIGURED` (503) — only happens on self-hosted deployments missing a 2Captcha key; production never emits this.

## Gate on verifiability

Agents should **always** check `_verifiability.extraction_confidence` before using a returned value in a billing decision or compliance statement. The recommended threshold is `>= 0.90`. See the [Verifiability contract](/verifiability) for the full story.