---
name: dock-optimizer
description: Answer questions about a warehouse, carrier, broker or shipper's dock schedule, detention, carrier reliability, inventory, loads and orders using the Dock Optimizer connector, and join those records to other systems (ERP, WMS, TMS) by PO, BOL, order number and carrier identity. Use when the Dock Optimizer connector is connected and the question is about docks, appointments, freight, carriers, inventory or what is owed.
---

# Dock Optimizer

Dock Optimizer runs dock scheduling, check-in and freight for the organization that connected it. The connector reads that one organization's records. It cannot see any other organization, and nothing it reads is shared with anyone.

## Start every conversation with `org_overview`

Call `org_overview` before anything else. It returns:

- `setupState`: `empty`, `configured_no_activity` or `active`.
- What is set up (facilities, doors, appointment types, connectors) and how much data exists in each area, with date ranges.
- `analyses`: which analysis tools have data, and which are closed to the organization's plan and why.
- `nextSteps`: what to tell the person when something is missing.

If `setupState` is `empty`, say so first. Every other read will come back empty, and an empty answer without that explanation looks like a broken connector. Help the person set up instead, using `nextSteps`.

An agent sees the facilities of the person who approved it. If that person is limited to some facilities, so is the agent: `dock://facilities` and `dock://organization` say so in `facilityAccess`, and appointments, doors, yard, inventory and reports at other facilities do not appear. Loads, orders, carriers, customers and users are organization-wide and always appear. When someone asks about a facility you cannot see, tell them it is outside this connection's access, not that it does not exist.

## Prefer the analysis tools to raw lists

Lists are capped at 200 rows, so adding up a list yourself is slow and easy to get wrong. The analysis tools compute on the server with the same code as the app's report pages, so their numbers match what the person sees in the app.

| Question | Tool | Things to say alongside the number |
| --- | --- | --- |
| What detention did we not bill? | `unbilled_detention` | Visits under `needsReview` are probably missed check-outs. They are left out of the dollar figure and should be checked on the appointment before anyone bills them. If `ratePerHour` is null there is no rate set, so report hours, not dollars. `alreadyBilled` means billed, not collected. |
| Which carriers are reliable? | `carrier_scorecard` | Two lenses. `awardedLoads` scores on-time pickup and delivery against the load's committed dates. `dockVisits` covers every carrier that books, with arrivals and no-shows. Dwell leaves out visits over 24 hours. Tender acceptance and fall-off are not recorded, so do not estimate them. |
| How did our appointments go? | `dock_performance` | On-time and no-show follow the org's own definitions, which the answer states; rates leave reschedules out. A slot's on-time % is of every appointment in it, cancelled ones included, so it reads lower than a carrier's on-time share of arrivals. |
| How full are the doors? | `door_utilization` | Lead with `readAs`. A facility that gives few visits a door (`doorAssignment.coveragePct` under 50) is unknown, not idle. Visits that never checked out count for at most a day and are counted in `dataQuality`. Blocked time is unavailable, not used. |
| Where is our margin thin? | `lane_margin` | Margin is customer rate minus carrier cost. Loads with a customer rate but no carrier cost are `unpricedLoads` and stay out of every dollar figure; say how many there are. Accessorials are not included. Never quote a shipper's rate to a carrier. |
| What stock is not moving? | `inventory_aging` | Age is days since the item last went out, not days since it arrived. Value is 0 where no purchase price is set, so check `itemsWithoutCost` before quoting a total. |

When a tool answers `{"available": false, "reason": ...}`, pass the reason on as written. It is a plan limit or a rule (a nonprofit is never billed detention), not an error.

Dates are `YYYY-MM-DD` and the end date is inclusive. Windows are capped at 92 days. The response echoes the window it actually used, so check it before quoting a period.

## Reading records

`list_resources` lists every `dock://` resource and its filters. Use `read_resource` for the detail behind an analysis, for example `dock://appointments/{id}` for one visit on the detention list, or `dock://loads/{id}` for one load.

Every list returns `totalCount`, `count`, `limit` and `offset`. When `totalCount` is larger than `count`, there is more to page through. Say so rather than presenting a page as the whole set.

Three reads that save a wrong answer:

- **`dock://closures`** before suggesting or booking a date. A closed day refuses the booking anyway, and it is better to say so first.
- **`dock://doors/status`** uses the same rule as the organization's Door Manager screen: a door is occupied until its truck is checked out. When `likelyMissedCheckout` is true, the door has been held for more than a day by a truck nobody checked out. Say that, rather than calling the door busy.
- **`dock://yard`** lists trucks on property, longest dwell first. `NotReported` means checked in without a door. `?stale=true` lists check-ins older than 30 days that never checked out; those are cleanup, not trucks on the lot.

A party view with nothing in it carries a `note` field that says whether it is empty by definition (for example, the organization is not a carrier) or simply has no matches.

## Joining Dock Optimizer to other systems

A question often needs this connector and another one, such as an ERP, a WMS or a TMS. These are the fields that line up:

| Dock Optimizer field | Where | Usually matches |
| --- | --- | --- |
| `poNumber` | `dock://appointments`, and in `search` | The purchase order in the ERP or WMS receiving record |
| `bolNumber` | `dock://appointments/{id}` | The bill of lading on the shipment |
| `orderNumber`, `customerPoNumber` | `dock://sales-orders` | The seller's order and the buyer's PO |
| `sourceSystem`, `externalOrderId` | `dock://sales-orders`, `dock://freight-orders` | The order's ID in the ERP it came from |
| `externalRefNumber` | `dock://loads`, `dock://freight-orders` | The shipment or load reference in a TMS |
| `mcNumber`, `dotNumber` | `dock://carriers`; `mcNumber` and `scac` on `carrier_scorecard` | The carrier in a TMS, broker system or FMCSA |
| `sku`, `lotNumber` | `dock://inventory/items` | The item and lot in the WMS |

Match on these fields, not on names. Carrier and customer names are typed by people and vary. When a join leaves records unmatched, say how many and which, rather than dropping them.

Useful combinations:

- Detention (`unbilled_detention`) against the carrier's invoices in an accounting system, to see what was charged and what was paid.
- Appointments by `poNumber` against the ERP's open purchase orders, to find freight booked with no PO and POs with no appointment.
- `carrier_scorecard` against rates from a TMS, to compare what a carrier costs with how reliably it shows up.

## Changing things

Depending on what the organization's admin allowed when connecting:

- **Propose** (a consent checkbox): tools named `propose_*` queue a change. A person approves or rejects it in Integration Hub, and nothing changes until they do. Tell the person that is what happened.
- **Memory** (a consent checkbox): `remember` stores a durable pattern about this organization for future conversations. Store rules and patterns, never live state. `forget` retracts one.
- **Stock** (a consent checkbox): `record_stock_change` records an item received (positive) or taken out (negative) where it is stored; `stock_at_location` puts a SKU at a location it is not in yet. Both save immediately, as the person, through the inventory scan page. Say exactly what you will record and get a yes first. A move is two steps: take it out of one place, then record it at the other.
- Apart from the checkboxes above, a connection made through Claude never writes directly.

## Writing about the numbers

- Quote the window, and the organization's own words for things (their facility and carrier names).
- Say what a number does not cover. The tools return notes for this reason.
- Do not state a cause the data does not show. "Swift had 11 hours of unbilled detention in September" is supported by the data. "Swift is slow to unload" is not.