---
name: grey-miles
description: Work in a Grey Miles freight dispatch workspace through the Grey Miles MCP server - loads, check calls, carriers, brokers, fleet, documents, invoices, payroll and FMCSA carrier lookups. Use when the user asks to check, update, book, track, bill or report on their dispatch operations in Grey Miles.
---

# Grey Miles

This skill needs the Grey Miles MCP server connected (server URL `https://api.greymiles.com/mcp`). Setup guide: https://greymiles.com/mcp

Grey Miles is the operations workspace of a US freight dispatch agency (and, for some workspaces, a brokerage or carrier): loads, carriers, brokers, drivers, trucks and trailers, documents, check calls, invoices, payments, payroll and analytics.

You act as one person in one workspace, with exactly their role. You can never see or do more than they can: dispatchers never receive fees, margins or other restricted money, and the API omits those fields rather than hiding them.

How to work:
1. Call get_workspace_context first: it names the workspace, the person's role, what you may change without asking, and today's fair-use allowance.
2. Find records with search_workspace or the list tools; use the IDs they return. Never guess IDs.
3. Read before you change: get the record, then change it. Commands are version-checked; pass expectedVersion from your read to refuse a stale change.
4. Changes may need the person's approval. If a tool answers "approval_required", tell the person what you asked to do and where to approve, then call run_approved_action with the approval ID once they say it is approved. Never claim a change happened until a tool confirms it.
5. Everything else the web app can do is reachable with find_actions then run_action.

Facts: times are ISO 8601; each stop has its own time zone. A load moves DRAFT → BOOKED → IN_TRANSIT → DELIVERED (or CANCELLED with a reason). "Sent" email means accepted by the email provider, never delivered or opened. Rate confirmation reading produces a proposal a person confirms; it never books a load. Read greymiles://guide/* resources for detail.

## Tools

- `get_workspace_context`: Start here. The workspace, the person's role, what you may change without asking (per kind of change), today's fair-use allowance and useful links.
- `search_workspace`: Search loads, carriers, brokers, drivers, trucks, trailers and invoices by reference, name, MC/DOT or unit number. Returns IDs to use with other tools.
- `list_loads`: Loads, newest first. Filter by status: DRAFT, BOOKED, IN_TRANSIT, DELIVERED or CANCELLED. Use a small limit and the returned cursor for more.
- `get_load`: One load: stops (with time zones and appointments), broker, carrier, equipment, freight, status and version. Money fields appear only for roles allowed to see them.
- `get_load_tracking`: A load's last known position (GPS, reported or planned, each with its age), route and ETA information.
- `list_check_calls`: Check calls on a load, newest first.
- `list_carriers`: Carriers the agency works with. q searches name, MC and DOT.
- `get_carrier`: One carrier: contacts, MC/DOT, defaults and status.
- `get_carrier_compliance`: One carrier's insurance, W-9, authority and agreement status (Missing, Being checked, Valid, Expiring, Expired, Rejected).
- `list_brokers`: Brokers (customers). q searches name and MC.
- `list_fleet`: Drivers, trucks or trailers, optionally for one carrier. q searches names, unit numbers, VIN and plates.
- `get_capacity_board`: Trucks with availability, empty location and date, and next load.
- `list_documents`: Documents, filterable by docType and loadId. Shows whether each file has been checked.
- `get_document_link`: A short-lived link to open or download a checked document. Share it only with people who should see the file.
- `list_invoices`: Invoices, filterable by carrierId and status (finance roles).
- `get_invoice`: One invoice with lines, totals, payments and balance (finance roles).
- `get_ready_to_bill`: Delivered loads ready to invoice (POD on file), grouped by carrier.
- `get_analytics`: Operations analytics for a period: loads, on-time, time to POD, miles, lanes, brokers, fleet. Money only for finance roles.
- `list_notifications`: Recent workspace notifications (status changes, documents, rate confirmations) and the read position.
- `search_fmcsa_carriers`: Search FMCSA records by USDOT, MC/FF/MX docket or company name.
- `get_fmcsa_profile`: A company's FMCSA profile by USDOT: authority, insurance, inspections, crashes, operating states and vetting flags, each with its source and check date.
- `create_load`: Create a draft load with stops (each with time zone, appointment type and local times), broker, carrier, freight and rate. Instants are ISO 8601 with whole seconds.
- `update_load`: Edit a load. Stops change only while it is a draft. Send only the fields to change.
- `change_load_status`: Move a load DRAFT → BOOKED → IN_TRANSIT → DELIVERED, or CANCELLED with a reason. Booking checks readiness and explains what is missing.
- `record_stop_event`: Record arrival at or departure from a stop of a load.
- `log_check_call`: Log a check call on a load: status, source, where the truck is, ETA and a note.
- `assign_equipment`: Assign a truck (with its seated driver and hooked trailer) to a load.
- `add_note`: Add a note to a load, carrier, broker, driver or truck.
- `create_carrier`: Add a carrier.
- `create_broker`: Add a broker (customer).
- `update_truck_availability`: Update a truck's availability, empty location and date on the capacity board.
- `create_invoice_drafts`: Create draft invoices for ready loads, one per carrier. Drafts are never issued automatically.
- `share_invoice_link`: Create a public, view-only link to an issued invoice for the customer. Returns the URL. Anyone with the link can view the invoice until it is withdrawn.
- `share_carrier_profile`: Create a public, view-only link to a company's FMCSA profile. Returns the URL.
- `send_email`: Send an email from the person's connected mailbox. Queued; SENT means accepted by the provider, never delivered or opened.
- `find_actions`: Search everything else Grey Miles can do (about 170 actions: invoices, payments, payroll, documents, team, settings, routes and more). Pass a few words, or an exact action id to get its input schema. Then call run_action.
- `run_action`: Run a Grey Miles action found with find_actions. Pass its id and arguments exactly as its input schema describes (path values and filters at the top level, request fields inside "body"). Changes follow the same approval rules as every other tool.
- `run_approved_action`: After the person approved a change in Grey Miles, run it. Runs exactly what they approved, once. Answers with the current state if it is still waiting, was declined or lapsed.

## Recipes

- **Daily dispatch brief**: Today's moving, late and at-risk loads with the calls to make.
- **Check-call sweep**: Find in-transit loads that need a check call.
- **Book a load**: Create and book a load from details or a rate confirmation.
- **Weekly billing**: Draft invoices for delivered loads that are ready to bill.
- **Vet a carrier**: Check a carrier's FMCSA record before working with them.

Full steps for each are in references/workflows.md.

## References

- [How Grey Miles works](references/overview.md): Records, IDs, versions and how tools map to the web app.
- [Load lifecycle](references/load-lifecycle.md): Statuses, booking readiness, stops and time zones, tracking and rate confirmations.
- [Roles and restricted money](references/roles-and-money.md): What each role can see and do.
- [Approvals and fair use](references/approvals-and-limits.md): Access modes, how approvals work, rate limits and errors.
- [Workflow recipes](references/workflows.md): Step-by-step recipes for common dispatch jobs.