Tools Reference¶
Generated from the live tool registry — this page always matches the deployed server.
Twelve task-level tools. read-only tools are safe to call freely; write
tools carry the gates described in Write Safety.
get_build_context¶
read-only
Get everything needed to draft a load for a site or region, in one call.
Returns sites with live tank levels/runout/brand, the customer's product catalog, terminals with remaining allocation (+ Available/Low/Out), drivers on shift that day with their already-taken priority slots and busy windows, carriers (active external haulers — pass a carrier id as carrier_id with assigned_driver_type='external' for carrier-first loads), sensible defaults (timezone, suggested delivery window), and hints[] (e.g. "site doesn't carry diesel"). The ids returned here are what you feed into validate_load / create_load.
USE WHEN: starting to build/plan a load, or answering "what can I dispatch to
Provide at least one of site or region.
NOTE: a site's category here ("Fuel Station", "Cardlock", …) is its PHYSICAL type — NOT the value for a line item's metadata.site_category (that's the retail/wholesale mode: 'Site' or 'Wholesaler'). Don't copy it across; omit site_category for retail drops (it defaults to 'Site').
| Parameter | Type | Required | Description |
|---|---|---|---|
site |
string | null | no |
region |
string | null | no |
fuel_type |
string | null | no |
day |
string | null | no |
validate_load¶
read-only
Dry-run a draft load against the full backend validation layer (nothing is created).
Returns per-assignment errors[] (must fix — same checks create enforces: schema, cross-tenant refs, tank↔site/mode, priority uniqueness, window ordering) and warnings[] (dispatcher-overridable: tight/stale window, unusual quantity, driver PTO/schedule conflict, off-allowlist equipment, unusual tank↔product pairing). When everything is valid you get a validation_token — required by create_load.
USE WHEN: after drafting from get_build_context, before every create; or to answer "would this load be valid?". DO NOT USE WHEN: you haven't gathered ids yet (get_build_context first).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignments |
array | yes | Draft load assignments (same shape create_load takes). Each needs: timezone (IANA), line_items[] with product_type_id/supply_location_id/delivery_location_id (+ tank_id for retail fuel-station drops), quantity>0, metadata {branded, site_category}. To ASSIGN the load, set assigned_driver_type AND its identity — 'internal' needs assigned_driver_id (get_build_context.drivers), 'external' is carrier-first and needs carrier_id (get_build_context.carriers); declaring a type without its identity is rejected. OMIT assigned_driver_type to save an unassigned draft. Also: delivery_window_start/end, metadata.priority (required once assigned). NOTE metadata.site_category is the DISPATCH MODE, exactly 'Site' (retail) or 'Wholesaler' — it is NOT the site's physical category: do NOT copy get_build_context's site category ('Fuel Station'/'Cardlock'/…) here. Omit it for a retail drop and it defaults to 'Site'; use 'Wholesaler' only with a wholesaler_customer_name. Get every id from get_build_context — never construct one. |
create_load¶
write human-confirmed
Create (publish) load assignments. WRITE — requires a fresh validation_token and human confirmation.
Flow: get_build_context → validate_load → create_load. The call asks the user to confirm (elicitation) before anything is written, retries are safe (Idempotency-Key), and the response is PER-ITEM: always check errors[] — success_count < total_count means some loads were NOT created.
USE WHEN: the user has confirmed a validated draft should be published. DO NOT USE WHEN: validate_load hasn't passed on this exact payload, or the user hasn't seen the plan yet.
| Parameter | Type | Required | Description |
|---|---|---|---|
assignments |
array | yes | The EXACT assignments payload that validate_load approved — any change invalidates the token. |
validation_token |
string | yes | Token returned by a successful validate_load of this same payload. |
acknowledge_warnings |
boolean | no | Must be true when validation produced warnings, after surfacing them to the user. |
send_email |
boolean | no | Send the dispatcher a summary email for the published loads. |
find_loads¶
read-only
Search existing load assignments (the dispatch board / history).
USE WHEN: answering "what's assigned to
| Parameter | Type | Required | Description |
|---|---|---|---|
status |
string | null | no |
driver_id |
string | null | no |
date_from |
string | null | no |
date_to |
string | null | no |
search |
string | null | no |
limit |
integer | no | Max loads to return (1-100). |
include_details |
boolean | no | true = include each load's full line_items (products, quantities, locations). Default false keeps board listings light — set true when the question is about contents, or use get_load. |
get_load¶
read-only
Get one load assignment's full detail (line items, driver, window, status, BOL state).
USE WHEN: you have a specific load id and need its full contents — before editing, to answer a detailed question, or to confirm what was created. DO NOT USE WHEN: you're searching/listing (use find_loads) or don't yet have the id.
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Load assignment UUID (from find_loads or a create result). |
get_load_timeline¶
read-only
Get one load's full audit timeline — dispatcher actions and driver trip events, newest first.
Each entry carries a source discriminator; reassignments include resolved previous/new driver names; trip events include display names.
USE WHEN: "what happened to load ?", "who cancelled this?", "did the driver arrive?", or reconstructing an audit trail. DO NOT USE WHEN: you want the load's current contents (use get_load) or are searching across loads (use find_loads).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Load assignment UUID (from find_loads / get_load). |
source |
string | null | no |
limit |
integer | no | Max timeline entries to return (newest first). |
get_recommended_loads¶
read-only
Get the system's recommended loads — which tanks need fuel, with suggested gallons and ETA, ordered by priority.
This is the "what should I dispatch today?" feed: runout forecasts turned into concrete load suggestions. Feed a chosen recommendation into get_build_context → validate_load → create_load.
USE WHEN: "what needs fuel today?", "which sites are red?", "plan my morning dispatches". DO NOT USE WHEN: the user already knows the site (get_build_context) or wants raw tank levels (query_inventory).
| Parameter | Type | Required | Description |
|---|---|---|---|
site |
string | null | no |
fuel_type |
string | null | no |
level_status |
string | null | no |
limit |
integer | no | Max recommendations to return (1-100). |
query_inventory¶
read-only
Query live tank inventory (levels, % of max, forecasted runout) across sites.
USE WHEN: answering "which sites are running low?", "what's the level at
| Parameter | Type | Required | Description |
|---|---|---|---|
site |
string | null | no |
fuel_type |
string | null | no |
limit |
integer | no | Max tank rows to return (1-200). |
update_load_status¶
write human-confirmed mutates existing loads
Cancel, complete, or reschedule an existing load. WRITE — two-phase + human confirmation.
First call (no confirm_token) returns a preview of the load and a token; the second call executes. An illegal transition is refused UP FRONT (no token issued) with the load's allowed transitions in the message — relay them, don't guess. Completing a load emits soft warnings (early / no BOL) in the preview — surface them, but they don't block.
USE WHEN: the user asks to cancel a load ("delete" it), mark it completed, or apply a reschedule. DO NOT USE WHEN: changing the driver (reassign_load), editing window/PO (update_load), or creating loads (create_load).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
status |
string | yes | Target status. Only dispatcher-writable targets: cancelled (this IS 'delete' — dispatch never hard-deletes), completed, rescheduled. NOTE: completed requires the load to be in_progress first (ruling 2026-07-09: completion must pass through the driver/trip-event flow — an assigned load cannot jump straight to completed; relay allowed_transitions and explain the driver must start the trip). Other statuses move via create/reassign/driver flows. |
reason |
string | null | no |
confirm_token |
string | null | no |
reassign_load¶
write human-confirmed mutates existing loads
Reassign an existing load to a different driver or carrier. WRITE — two-phase + human confirmation.
Reassignment updates the load IN PLACE — same assignment id, same reference_code, line items preserved — and resets its status to 'assigned'. Priority-slot, roster, and PTO rules re-apply to the new driver: an off-roster or non-reassignable load is refused up front (no token issued).
USE WHEN: the user says "give this load to
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
reason |
string | yes | Why (required — audited recovery action). |
new_driver_id |
string | null | no |
driver_type |
string | no | internal = own driver; external = carrier. |
carrier_id |
string | null | no |
confirm_token |
string | null | no |
update_load¶
write human-confirmed mutates existing loads
Edit fields of an existing load (window, PO number, truck/trailer). WRITE — two-phase + human confirmation.
Only the fields you pass change; status-based edit permissions apply backend-side. The response may carry PTO warnings for the new window — surface them.
USE WHEN: "push the window to 2-4pm", "set PO 12345", "swap the trailer". DO NOT USE WHEN: changing status (update_load_status), the driver (reassign_load), or line items/quantities (not editable here — if the user needs that, say so and call report_missing_capability).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
delivery_window_start |
string | null | no |
delivery_window_end |
string | null | no |
po_number |
string | null | no |
truck_id |
string | null | no |
trailer_id |
string | null | no |
confirm_token |
string | null | no |
check_allocation¶
read-only
Check terminal fuel allocations (DTN): remaining gallons by terminal/fuel/brand, or whether a specific load amount fits.
Two modes: - Breakdown (no amount): remaining allocation + Available/Low/Out status per terminal × fuel type × brand bucket, optionally filtered. - Availability check (amount set): would a load of this size fit — returns is_available, remaining_after_load, and a warning when the allocation would run low (loads stay allowed until <50 gal remains).
USE WHEN: "how much contract regular is left at
| Parameter | Type | Required | Description |
|---|---|---|---|
terminal_id |
string | null | no |
fuel_type |
string | null | no |
brand_type |
string | null | no |
product_type_id |
string | null | no |
amount |
number | null | no |
allocation_type |
string | no | Availability-check mode: which allocation bucket the load draws from. |
delete_load¶
write human-confirmed mutates existing loads
Remove a mistakenly-created / duplicate load from the board. WRITE — two-phase + human confirmation.
Soft-delete: sets deleted_at (+ cancelled status) so the load DISAPPEARS from all lists and boards. Nothing is hard-deleted; the audit rows remain.
USE WHEN: the load was created by mistake or is a duplicate — "remove / delete this, it shouldn't exist". DO NOT USE WHEN: a REAL load is being called off — use update_load_status(cancelled) so it stays visible in history/reports.
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
confirm_token |
string | null | no |
get_bol_report¶
read-only
List terminal BOL (bill of lading) rows matching the filters — state the total first, then the rows shown.
USE WHEN: 'show me / list BOLs …', finding a specific BOL, checking what's unmatched. DO NOT USE WHEN: counting only (get_bol_stats) or summing gallons by category (get_bol_volume_summary).
Filters (all optional, AND'd): date_from/date_to or lift_date (ISO dates, lift-date based); terminal/carrier/driver_name (substring); fuel_grade (PRODUCT code substring — 'ULSD' for diesel, '87'/'E10' for gasoline blends; the words 'diesel'/'gasoline' match NOTHING); site_number (exact store number); match_status ('matched'=reconciled, 'unmatched'=no load yet); q (free text).
| Parameter | Type | Required | Description |
|---|---|---|---|
terminal |
string | null | no |
carrier |
string | null | no |
customer |
string | null | no |
fuel_grade |
string | null | no |
date_from |
string | null | no |
date_to |
string | null | no |
lift_date |
string | null | no |
match_status |
string | null | no |
driver_name |
string | null | no |
site_number |
string | null | no |
q |
string | null | no |
include_fuel_detail |
boolean | no | Include per-grade fuel breakdown per BOL row. |
limit |
integer | no | Max rows (keep ≤25 for readability). |
get_bol_stats¶
read-only
Count terminal BOLs (bills of lading) matching the filters — cheap, no row data. Returns {total, matched, unmatched} (matched = reconciled to a load; unmatched = terminal BOL with no load yet).
USE WHEN: 'how many BOLs …' / reconciliation-count questions. DO NOT USE WHEN: you need rows (get_bol_report) or gallons (get_bol_volume_summary).
Filters (all optional, AND'd): date_from/date_to or lift_date (ISO dates, lift-date based); terminal/carrier/driver_name (substring); fuel_grade (PRODUCT code substring — 'ULSD' for diesel, '87'/'E10' for gasoline blends; the words 'diesel'/'gasoline' match NOTHING); site_number (exact store number); match_status ('matched'=reconciled, 'unmatched'=no load yet); q (free text).
| Parameter | Type | Required | Description |
|---|---|---|---|
terminal |
string | null | no |
carrier |
string | null | no |
fuel_grade |
string | null | no |
date_from |
string | null | no |
date_to |
string | null | no |
lift_date |
string | null | no |
match_status |
string | null | no |
driver_name |
string | null | no |
site_number |
string | null | no |
q |
string | null | no |
get_bol_volume_summary¶
read-only
Aggregate gallons for terminal BOLs: net/gross totals plus by_fuel_category and by_terminal breakdowns.
THE tool for 'how many gallons of diesel/gasoline/DEF …' — categories are computed correctly here; never approximate them with fuel_grade filters. Prefer a date range and/or terminal: unfiltered calls span thousands of BOLs and get capped (truncated=true → figures cover only the most recent bols_aggregated — say so and narrow).
Filters (all optional, AND'd): date_from/date_to or lift_date (ISO dates, lift-date based); terminal/carrier/driver_name (substring); fuel_grade (PRODUCT code substring — 'ULSD' for diesel, '87'/'E10' for gasoline blends; the words 'diesel'/'gasoline' match NOTHING); site_number (exact store number); match_status ('matched'=reconciled, 'unmatched'=no load yet); q (free text).
| Parameter | Type | Required | Description |
|---|---|---|---|
terminal |
string | null | no |
carrier |
string | null | no |
customer |
string | null | no |
fuel_grade |
string | null | no |
date_from |
string | null | no |
date_to |
string | null | no |
lift_date |
string | null | no |
match_status |
string | null | no |
driver_name |
string | null | no |
site_number |
string | null | no |
q |
string | null | no |
get_driver_board¶
read-only
Get the full driver board for a day: who's on shift (with truck/trailer), each driver's loads, taken priority slots, and unassigned loads.
Composes the shift roster with that day's load assignments so one call answers board questions across ALL sites (get_build_context's drivers section is scoped to one site/region query).
USE WHEN: "who's working tomorrow?", "how loaded is each driver?", "which loads have no driver?", planning the day's assignments. DO NOT USE WHEN: you're already building a load for a known site (get_build_context includes drivers) or want one driver's loads only (find_loads with driver_id).
| Parameter | Type | Required | Description |
|---|---|---|---|
day |
string | yes | The board day, YYYY-MM-DD in the customer's timezone. |
get_load_bol¶
read-only
Get one load's BOLs (bills of lading): driver captures paired with matched terminal records.
Each entry carries the driver side (bol_number, net/gross volumes, has_image, submitted_at) plus the terminal side (terminal_payload, matched_at, matched_by) once matching succeeds. match_status is matched / pending_match / failed / no_match; needs_manual_matching=true means automatic matching gave up on at least one BOL and a dispatcher must reconcile it by hand.
USE WHEN: "did the BOL come through for this load?", "what volume was on the ticket?", checking reconciliation before invoicing. DO NOT USE WHEN: searching terminal BOLs across loads (get_bol_report / get_bol_stats) or reconstructing the trip (get_load_timeline).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Load assignment UUID (from find_loads / get_load). |
get_tank_trends¶
read-only
Get a tank's inventory history (and optionally its runout forecast) — levels over time, consumption, thresholds.
History points carry level, consumption rate, and rolling averages; the forecast (include_forecast=true) adds predicted levels with confidence bounds. Points are downsampled evenly to stay readable.
USE WHEN: "how fast is this tank draining?", "show the level trend at
| Parameter | Type | Required | Description |
|---|---|---|---|
tank_id |
string | yes | Tank UUID (from query_inventory or get_build_context tanks). |
time_range |
string | no | History window: 24h, 7d, 30d, or 90d. |
include_forecast |
boolean | no | Also return the runout forecast (predicted levels + confidence bounds). |
max_points |
integer | no | Downsample history to at most this many points. |
record_deviation¶
write human-confirmed
Record a deviation on a line item — what differed from plan (short drop, product swap, …). WRITE — two-phase + human confirmation.
Appends an audited deviation record to the line item; for numeric quantity deviations the backend computes variance, variance_percent, and whether industry tolerance was exceeded.
USE WHEN: "we only dropped 6,800 of the 7,500", "the driver pulled from a different terminal", "the site was rebranded" — any planned-vs-actual mismatch to put on record. DO NOT USE WHEN: changing the plan itself (update_load), logging trip progress (record_trip_event), or cancelling (update_load_status).
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
line_item_id |
string | yes | Line item UUID the deviation is on (from get_load). |
deviation_type |
string | yes | What kind of thing deviated: quantity, product, site, branding, service_number, or other. |
field |
string | yes | The field that deviated (e.g. 'quantity', 'supply_location'). |
planned_value |
string | number | yes |
actual_value |
string | number | yes |
reason |
string | yes | Why it deviated (audited). |
confirm_token |
string | null | no |
record_trip_event¶
write human-confirmed mutates existing loads
Record a driver trip event on a load (enroute, arrived, drop done, …). WRITE — two-phase + human confirmation.
Trip events drive the status ladder: recording ENROUTE_TO_SUPPLY_LOCATION (the start/enroute event) moves an assigned load to in_progress — and in_progress is the ONLY path to completed (ruling 2026-07-09: an assigned load can never jump straight to completed; the trip must be started first). ASSIGNMENT_COMPLETED / TRIP_CANCELLED close the load out.
USE WHEN: logging trip progress on the driver's behalf ("mark him enroute", "she arrived at the rack"), or un-sticking an assigned load that needs to reach completed — record the enroute event first. DO NOT USE WHEN: capturing a BOL (BOL_CAPTURED needs the driver app's image + bolNumber flow), setting a status directly (update_load_status), or recording a planned-vs-actual discrepancy (record_deviation).
HUMAN-ONLY (founder ruling 2026-07-10): trip progress is attributed to real people — this works in OAuth (user) sessions only. API-key (machine) callers are rejected by the backend; relay that the driver or a dispatcher must record progress, do NOT retry.
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
event_type |
string | yes | Event code. Standard ladder: ENROUTE_TO_SUPPLY_LOCATION (start — moves an assigned load to in_progress), ARRIVED_SUPPLY_LOCATION, DEPARTED_SUPPLY_LOCATION, ARRIVED_DELIVERY_LOCATION, TANK_READINGS_RECORDED, LINE_ITEM_COMPLETED (both per-drop — need line_item_id), ASSIGNMENT_COMPLETED, TRIP_CANCELLED. Customer-configured codes also exist (get_load_timeline shows what this customer's drivers record). |
occurred_at |
string | null | no |
line_item_id |
string | null | no |
latitude |
number | null | no |
longitude |
number | null | no |
notes |
string | null | no |
confirm_token |
string | null | no |
resend_notification¶
write human-confirmed
Resend the push notification for a load to its assigned driver. WRITE — two-phase + human confirmation.
Fires the same FCM alert the driver got at assignment time — each execute sends again, so don't spam.
USE WHEN: the driver says they never got the load / dismissed the alert — "ping Sukhpal about FLXT-123 again". DO NOT USE WHEN: the load has no driver yet (reassign_load first), or the driver needs a different load — resending doesn't change anything.
| Parameter | Type | Required | Description |
|---|---|---|---|
assignment_id |
string | yes | Assignment UUID (from find_loads / get_load). |
confirm_token |
string | null | no |
report_missing_capability¶
write human-confirmed
Report a capability this server is missing, so the FolioX team can build it.
USE WHEN: the user asked for something none of the available tools can do (or can only do awkwardly), AFTER you've told the user — this records the gap, it does not solve it. DO NOT USE WHEN: a tool exists but returned an error (fix the call instead), or the request is outside dispatch entirely.
Reports are reviewed to prioritize new tools. Do not include customer data, names, or numbers — describe the capability, not the payload.
| Parameter | Type | Required | Description |
|---|---|---|---|
capability |
string | yes | The tool or capability you needed but don't have, phrased as an action (e.g. 'cancel an existing load', 'see a driver's full day board'). |
user_goal |
string | null | no |
workaround_used |
string | null | no |