Freight Right

View saved version →

---
name: booking-handoff
description: Freight Right booking preparation — turn a chosen offer into a confirmation link that the customer opens and submits themselves, then read what they decided. Use after an instant price check or a QUOTED quote request when the customer wants to book an offer, and to check the state of a booking already prepared. No tool here books anything.
---

# Freight Right: preparing a booking

**Nothing here books anything.** These tools write a pending record and return a link. Only the customer, signed in
to Freight Right in their own browser, can submit it on that page. Give them the link and say plainly what it will
book.

Say "I have prepared a booking for you to confirm", never "I booked it".

## Which prepare tool

| Came from | Tool | Needs |
|---|---|---|
| An instant price check | `freightright_prepare_instant_booking` | `pricing_id` (`pj_…`) + `offer_id` (`of_…`) |
| A quote request | `freightright_prepare_rate_request_booking` | `rate_request_id` (`rfq_…`) + `offer_id` (`of_…`) |

The quote-request path is refused unless the request's status is **`QUOTED`**. Check it first and tell the customer
what the status actually is. It is also refused when the request's `may_book` is `false` — this connection can read
it but not book it, because booking takes the account that created the request, a current member of the
organization it is billed to, or an address Freight Right shared its quote with (an administrator books only the
requests their own account created). Say who can
book it instead of preparing a link that would fail.

Both take an optional `reference` (up to 64 characters — the customer's own PO or job number) and `note` (up to
2,000). Offer these; a reference is what the customer will recognise the shipment by later. If a note is refused as
too long, say that the note is too long and ask the customer to shorten it — it is their input, not an outage.

The offer's identity and revision are what was shown to the customer. The server attaches them; you never pass a
revision. If the offer has changed or expired upstream, the booking is refused rather than silently repriced.

## Three different expiry times — keep them apart

| Time | What it is |
|---|---|
| The link's `expires_at` | Up to **30 minutes** from preparing, cut short if the offer stops being bookable sooner |
| `bookable_until` | When the offer stops being bookable at all |
| The offer's `valid_until` | A **date**, after which the price is no longer valid |

Show the link's deadline prominently, with its timezone. Never let "price valid until" imply the link still works.

**Preparing the same pending booking again returns the same link and does not extend it.** If the customer asks for
more time, the honest answer is that the deadline has not moved. Once an operation is decided — cancelled, expired
or failed — a fresh attempt can be prepared, and it gets a new link, provided the offer is still available.

## Reading what the customer decided

`freightright_get_booking_operation(operation_id)`.

| State | Means | Do |
|---|---|---|
| `PENDING_CONFIRMATION` | Waiting for the customer's click | Give them the link and the deadline |
| `SUBMITTING` | Being sent | Read again shortly |
| `DONE` | Freight Right has the request and is **reviewing** it | Say it is submitted and under review |
| `CANCELLED` | The customer declined on the page | Ask what they want instead |
| `EXPIRED` | The window passed unused | Offer to prepare it again if still bookable |
| `FAILED` | Freight Right refused it | Report the reason given |
| `UNKNOWN` | The outcome is not yet established | **Read it again shortly. Never prepare a second time** |

`UNKNOWN` is reconciled in the background using the same bytes and the same key. Preparing again in response to it
is how a customer ends up with two bookings — do not.

`DONE` is not a confirmed booking. It becomes `BOOKING_REQUESTED` at Freight Right, and **`BOOKED` is a separate
confirmation** that Freight R

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: connection-and-billing
description: Freight Right connection status, permissions and billing accounts. Use before the first price check, quote request or booking of a conversation; when a Freight Right call is refused for billing or permission reasons; when choosing which organization a price, quote or booking is billed to; or when a Freight Right capability appears to be missing.
---

# Freight Right: connection, permissions and billing

Three tools, all free to call and all read-only.

| Tool | Answers |
|---|---|
| `freightright_get_connection_status` | Who is signed in, which organizations they may **act for**, what the customer allowed, and whether access is `ok`, `paused` or `unavailable` |
| `freightright_get_account` | What this connection may do in the rates API, its rate limits, this month's usage, and how billing works |
| `freightright_list_billing_organizations` | The organizations this customer can be **billed through** |

Call `freightright_get_account` before the first price check or quote request of a conversation. It costs nothing
and it tells you the billing policy, which you need before you can send anything.

## Two different sets of organizations

They are not the same list and the counts often differ.

- **Act for** — `freightright_get_connection_status.organizations`. Whose shipments and quotes may be read.
- **Billed through** — `freightright_list_billing_organizations.organizations`. Who pays.

A customer can see the shipments of an organization they cannot be billed through. Never substitute one list for
the other, and when you name a set, say which one you mean.

`freightright_get_connection_status.role` says who is connected. `USER` is a customer: the two lists above are
theirs. `ADMIN` is a **Freight Right administrator**: `organizations` is empty and means *every organization*, not
none — they read every organization's shipments and quotes, and there is no billing list of their own. They name the
client organization to bill on each price check or quote request, found with `freightright_list_billing_organizations`
and its `query` (part of the id or name the user said). When exactly one organization matches what they said, use it;
when several match, or none, ask — never pick a near miss, and never guess an id.

## The three billing policies

`freightright_get_account.billing.policy` says which applies.

| Policy | What to send |
|---|---|
| `LINKED_ORGANIZATION` | `billing_organization_id` from `freightright_list_billing_organizations` |
| `COMPANY_NAME` | `billing_company_name` — there is nothing to choose |
| `ANY_ORGANIZATION_OR_COMPANY_NAME` | Either one is accepted — a Freight Right administrator: `billing_organization_id` of a client organization found with `query`, or `billing_company_name` for a customer without one. Nothing is chosen by default |

Never send both — that is refused. If several organizations exist and none is the default, **ask the customer which
one** rather than picking. If a call is refused for billing, read the policy again before retrying: it can change,
and the refusal will tell you what applies now. Describe it as the policy that applies *now*, never as a policy that
"changed" — nothing here knows the earlier value.

## Three different reasons a capability is not there

Do not report these as the same thing. The customer's fix is different in each case.

| What you see | What it means | What to say |
|---|---|---|
| The tool is **not in the tool list at all** | The capability is switched off for this deployment or this assistant | Freight Right has not enabled it here. Reconnecting will not help |
| The call returns an **authorization challenge** | The connection exists but was not granted that permission | The customer needs to reconnect and approve the extra permission. Permissions are fixed for the life of a connection |
| The call says the connection is **paused**, or asks you to reconnect | The grant is paused or dead at Freight Right's end | Paused: t

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: instant-pricing
description: Freight Right instant freight prices — live carrier rates for FCL, LCL, AIR and LTL shipments. Use when a customer asks what a shipment will cost, wants to compare carriers on a lane, or when a price check that is still running needs collecting or its offers paging. Covers turning place names into port and airport codes, what each freight mode requires, the monthly price-check allowance, and reading an offer.
---

# Freight Right: instant prices

An instant price asks carriers live. **A new check spends one unit of the customer's monthly allowance**, so price
once per lane and cargo, when the customer wants prices — never to explore.

## Before you price

1. `freightright_get_account` — the billing policy and the remaining allowance. Free. A Freight Right
   administrator (`ANY_ORGANIZATION_OR_COMPANY_NAME`) bills a client organization they find with
   `freightright_list_billing_organizations` `query`, or a company name for a customer who has none; the allowance
   spent is the administrator's own.
2. **Resolve every place the customer named** with `freightright_find_locations`. A port or airport is a code
   (`CNSHA`, `USLAX`, `PVG`); a door is a postal code plus a two-letter country code, used exactly as given and
   needing no lookup. **No code is ever guessed** — a wrong one is `location_not_found` and nothing else.
3. Ask the customer for anything missing rather than assuming it. A guessed weight is a wrong price.

## What each mode needs

| Mode | Cargo | Also required | Refuses |
|---|---|---|---|
| **FCL** full container, ocean | `containers` (type + quantity, ≤4 entries) | `direction` | hazardous, temperature-controlled → quote request |
| **LCL** part container, ocean | `pieces` **or** `totals`, never both | `direction` | — |
| **AIR** | `pieces` **or** `totals`, never both | `direction` | — |
| **LTL** pallets by road | `pieces`, with a DOOR at both ends | — | `direction`, `incoterm`, port charges, customs, insurance |
| **FTL** full truck | — | — | never priced instantly — use a quote request |

A *piece group* is any number of **identical** pieces carrying the dimensions and weight of **one** of them. A
group can be hundreds of pallets, so the group limits are rarely a real constraint. `totals` (pieces, gross weight,
volume) is the fallback for LCL and AIR when dimensions are unknown.

Insurance is `insured_value_usd`, the commercial value of the goods in USD, and exists on **FCL, LCL and AIR only**.
For LTL and FTL, ask for insurance in a quote request note with the value.

For enum values, unit and decimal limits, packaging types, incoterms and freight classes, read
`freightright://reference/codes`. It is generated from the same table as the tool schemas, so it cannot fall behind
them. If you cannot read resources in this client, ask the customer or send the call and read the validation error —
never invent an enum value.

## What a call costs

`served_from` on the answer says it plainly:

- **`NEW_CHECK`** — this call started a check and **spent one unit**. It is not a promise the carriers were asked
  again; the API may answer a repeated request from its own cache and still charge.
- **`EXISTING_CHECK`** — an identical request for the same billing account joined a running check or was served a
  retained one. **This call spent nothing**, and the original pricing time is kept.

Reuse keys on the exact normalized request plus the billing context, not merely "the same lane and cargo". A result
is retained until `bookable_until` and can be dropped sooner, because only the five most recent results per customer
are kept. Never suggest altering shipment details to change this.

`freightright_find_locations` and `freightright_get_rate_offers` are free.

## A check that is still running

A slow answer comes back as `status: PRICING` with a `pricing_id` and a `retry_after_seconds`.

**Collect it with `freightright_get_rate_offers`.** Repeating an identical request joins the same c

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: quote-requests
description: Freight Right quote requests — ask Freight Right's pricing team for a price that instant rates cannot give. Use for full truckload, Mexico trucking, hazardous or temperature-controlled cargo on a mode that refuses it, oversized or unusual cargo, a lane with no instant offers, or a second opinion on an instant price. Covers previewing what would be sent, submitting it, polling the result, who may book it, listing quotes — a customer's own, or every organization's for a Freight Right administrator — and an administrator sharing a quote with e-mail addresses.
---

# Freight Right: quote requests

A quote request goes to Freight Right's pricing team, who answer with a quote the customer can book. It is the
route for everything instant prices cannot do.

## When a quote request, not an instant price

Check the mode before deciding — the rules are not uniform.

| Situation | Route |
|---|---|
| **FTL** (full truckload), any cargo | Quote request. FTL is never priced instantly |
| **FCL** with hazardous **or** temperature-controlled cargo | Quote request — FCL refuses both |
| **LTL** with temperature-controlled cargo | Quote request |
| **LTL** with hazardous cargo | **Instant price** — LTL takes the hazardous flag |
| **LCL** or **AIR** with hazardous or temperature-controlled cargo | **Instant price** — both are accepted |
| Insurance on LTL or FTL | Quote request, with the value in the note |
| Mexico trucking, oversized cargo, no instant offers, a second opinion | Quote request |

FTL equipment goes in `containers` as container sizes — the current API representation. Everything else about the
truck (trailer type, loading, weight) goes in the note.

## Preview, then submit

`freightright_preview_rate_request` shows exactly what would be sent. **It sends nothing, creates nothing and
stores nothing.** Show it to the customer before submitting.

**A preview is not authorization to send.** It is a draft for the customer to look at. Submit when the customer has
said to — and if the content changes after they agreed, preview again and ask again. Equally, do not re-ask for
authorization the customer has already given for the same request.

`freightright_submit_rate_request` takes **the same arguments you previewed**, unchanged. It creates the request,
notifies the pricing team and emails the customer.

Whether the customer's assistant asks them to confirm before this is sent depends on their assistant settings, not
on Freight Right. Say what you are about to send.

A Freight Right administrator submits a quote request **for** a client organization: `billing_organization_id`
of one found with `freightright_list_billing_organizations` `query`, or `billing_company_name` for a customer who has
no organization. Their request is an internal draft until Freight Right's team sends it; the organization's own
users do not see it before then.

## Who may book it

`freightright_get_rate_request.may_book` says whether **this connection** may book the request: the account that
created it, a current member of the organization it is billed to, or an address Freight Right shared its quote with.
Reading is not booking. When it is `false`,
say who can book it and do not offer to — `freightright_prepare_rate_request_booking` refuses it anyway. An
administrator reads every organization's requests and books only the ones their own account created.

## Sharing a quote (Freight Right administrators)

`freightright_share_quote` shares a quote with e-mail addresses: the `quote_number` (an integer from
`freightright_list_quotes`) and 1 to 20 addresses. Each address then sees the quote once it signs in to Shipment
Manager with that address — with or without an organization — and can use its approval, booking-request and
cancellation actions. An administrator's draft stays hidden until it is sent.

- **Only an administrator's connection shares.** On a customer's connection the tool refuses; say that Freight Right
  shares quote

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: shipment-tracking
description: Freight Right shipment tracking — find a shipment by any reference, list what is arriving, departing or delivering in a date window, and read one shipment in full with its legs, milestones and containers. Use for "where is my shipment", "what arrives this week", "what is overdue", or when a customer gives a container number, house or master bill of lading, purchase order or forwarder reference.
---

# Freight Right: finding and reading shipments

Start from what the customer said, not from a list.

| The customer gives you | Use |
|---|---|
| A reference of any kind — forwarder reference, house or master bill, container number, purchase order | `freightright_find_shipments` — it searches all of them at once and says which one matched |
| A time or status question: "arriving this week", "still on the water" | `freightright_list_shipments` with a date window |
| One shipment, in full | `freightright_get_shipment` with its **forwarder reference** |

`freightright_get_shipment` takes a forwarder reference and nothing else. To go from any other identifier, find it
first.

Several shipments can share an identifier — a purchase order often covers many. **Show them all and let the
customer choose; never pick one silently.**

## Filters are applied by Freight Right, never by you

Every answer reports `applied_filters`. If a filter you asked for is not there, the results were **withheld rather
than shown unfiltered** — say so. Never filter, sort or trim the results by hand: you would be presenting a subset
as if it were the answer.

The filters worth knowing:

- `traffic` — international (sea or air, crossing a border) or domestic (road within one country).
- `transport_mode` — `SEA`, `AIR`, `ROA`, `RAI`, `TRK`. **This is how it moves, not a pricing mode.**
- `shipment_status` — free text matched exactly, often empty. Never invent one.
- `archived` — false by default.
- `arriving_from` / `arriving_to` — estimated arrival at the **final port**.
- `delivering_from` / `delivering_to` — estimated **final delivery to the address**, a different event, often days
  later.
- `departing_from` / `departing_to` — estimated departure.
- `arrival_recorded` / `delivery_recorded` — whether an **actual** timestamp exists.
- `updated_since` — an RFC 3339 timestamp, for syncing.

"Possibly overdue" is `arriving_to` set to a past date with `arrival_recorded=false`.

When `has_more` is true, call again with `cursor` set to `next_cursor` **and the same filters**. Never invent a
cursor. A shipment nobody can see is not an error — a customer's account sees the shipments of its own organizations.
A Freight Right administrator's connection (`freightright_get_connection_status.role` = `ADMIN`) sees every
organization's; `organization` — an organization id, as `freightright_list_billing_organizations` or a quote's
billing shows it — narrows a list or a search to one of them, and is applied only when `applied_filters` confirms it.

## Estimated is not actual

A date with an `actual` happened. A date with only an `estimated` has **no actual event recorded** — which is
not the same as the event not having happened. The estimate is a plan that moves; the silence is just silence.

- **departure** — left the origin port or facility.
- **arrival** — reached the final air or ocean port of the main leg. **Not delivery.**
- **delivery** — reached the final destination address. An `appointment` is a booked delivery slot.

**Never tell a customer something has happened because an estimate has passed.** An estimated arrival in the past
with no actual recorded means **potentially overdue** — not late, not delayed. It is not a confirmed delay; suggest
checking with Freight Right.

That restriction is about the *inference*. If a carrier milestone explicitly reports a delay, a roll or an
exception, report what the carrier said — quote it rather than softening it.

## Milestones

Milestones are recorded events, newest last, from carriers, t

Preview of the first 4,000 characters. Read full instructions →