> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Available MCP Tools
> Catalog of tools exposed by the Alvys MCP server, grouped by domain (loads, drivers, trips, invoices) with tier, scope, and permission requirements.
This page lists every tool the Alvys [MCP server](/docs/mcp) exposes to AI agents. Each tool maps 1:1 to an Alvys Public API capability and requires a specific permission (scope). Your token must carry that scope for the call to succeed.
**Tool tiers**
* **Read** — retrieve data. Always available.
* **Write** — create or update data. Disabled during beta.
Scopes use the `{resource}:{action}` convention and match the [Public API scope catalog](/docs/authentication-1#available-scopes). Assign them to your application in **Admin → API Access**.
During beta, the server is **read-only**. Write tools (marked below) are disabled.
***
## Conventions
The MCP tool surface mirrors the Public API request/response shapes so calls port 1:1 between the two.
**Paging.** All search tools accept `page` (0-based, default `0`) and `pageSize` (default `25`, max `100`). Responses echo the request `page` back so agents can drive their own pager. `page=-1` (or any negative value) is rejected with `[invalid_params]`.
**Breaking (2026-07-23):** paging is now 0-based, matching the Public API. Callers that previously sent `page=1` to get the first page must now send `page=0`. See the [changelog](/changelog).
**Array filters.** Filters that map to `/search` array fields on the Public API (`statuses`, `status`, `loadNumbers`, `orderNumbers`, `mcNumbers`, `dotNumbers`, `tripNumbers`, `driverIds`, and so on) are declared as **arrays** on the tool. Pass one or many values in a single call.
**Date ranges.** Date-range filters are objects: `{ start, end }` in ISO-8601 (e.g. `{ "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" }`). The parameter names match the Public API — `createdDateRange`, `pickupDateRange`, `deliveryDateRange`, `invoicedDateRange`, `paidDateRange`, `transactionRange`. Legacy split-string parameters (`createdFrom` / `createdTo`, `pickupFrom` / `pickupTo`, etc.) are no longer accepted.
**Strict arguments.** Unknown keys — misspellings, unsupported filters, or parameters that no longer exist — are **rejected** with `[invalid_params]`. The error message names the rejected keys and the valid parameter list so an agent can self-correct in one round trip. Nested keys inside a date range or array element are validated too. Missing required arguments and wrong-type values (for example `page: "not-an-int"`) also return structured `[invalid_params]` errors naming the parameter — for both tools and prompts.
Why: previously, the MCP SDK bound arguments by name and silently discarded unknown ones. `customers_search name="Colortech"` returned the full unfiltered customer list because `name` isn't a valid filter on that tool. That silent-drop behavior is gone — you now get an actionable error instead of a confidently-wrong result.
**Tool annotations.** Each tool advertises MCP `annotations` safety hints that mirror the Read / Write / Destructive tiers on this page: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Your MCP client can use these hints to decide whether to ask a human before running a tool. During beta, every exposed tool is read-only and sets `readOnlyHint: true` (and `destructiveHint: false`).
Example rejection:
```json theme={null}
{
"isError": true,
"content": [
{
"type": "text",
"text": "[invalid_params] Unknown parameter(s) for customers_search: 'name'. Valid parameters: createdDateRange, page, pageSize, statuses. Unknown parameters are rejected instead of silently ignored so a misspelled filter cannot return unfiltered results."
}
]
}
```
***
## Loads
| Tool | Tier | Scope | Description |
| ----------------- | ---- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `loads_search` | Read | `load:read` | Search loads by `status`, `loadNumbers`, `orderNumbers`, and/or `customerId`. Provide at least one filter. |
| `loads_get_by_id` | Read | `load:read` | Fetch a single load including stops, charges, and assignment. |
## Trips
| Tool | Tier | Scope | Description |
| ------------------------------- | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trips_search` | Read | `trip:read` | Search trips by `status`, `loadNumbers`, `tripNumbers`, `pickupDateRange`, and/or `deliveryDateRange`. Provide at least one filter; a date range alone is sufficient. |
| `trips_get_by_id` | Read | `trip:read` | Fetch a single trip including its ordered stops. |
| `trips_record_arrival` | Write | `stop:update` | Record an arrival event on a trip stop. |
| `trips_record_departure` | Write | `stop:update` | Record a departure event on a trip stop. Server enforces that an arrival must exist first. |
| `trips_update_stop_appointment` | Write | `stop:update` | Update the appointment (or FCFS window) on a trip stop. |
| `trips_assign` | Write | `trip:update` | Assign a carrier, driver, and equipment to a trip. |
## Drivers
| Tool | Tier | Scope | Description |
| ----------------------- | ---- | ------------- | --------------------------------------------------------------------------------------------- |
| `drivers_search` | Read | `driver:read` | Search drivers by `name` and/or ELD duty `status` (array). Provide at least one filter. |
| `drivers_get_by_id` | Read | `driver:read` | Fetch a single driver record. |
| `drivers_events_search` | Read | `driver:read` | Fetch ELD / duty event history over a date range for one or more drivers (`driverIds` array). |
## Carriers
| Tool | Tier | Scope | Description |
| -------------------------- | ----- | ---------------- | ------------------------------------------------------------------------------------------- |
| `carriers_search` | Read | `carrier:read` | Search carriers by `status`, `mcNumbers`, and/or `dotNumbers`. Provide at least one filter. |
| `carriers_get_by_id` | Read | `carrier:read` | Fetch a single carrier including insurance and authority data. |
| `carriers_documents_get` | Read | `carrier:read` | List documents on file for a carrier. |
| `carriers_set_status` | Write | `carrier:update` | Change a carrier's status (e.g. activate after onboarding). |
| `carriers_document_upload` | Write | `carrier:update` | Upload a carrier onboarding document. |
## Customers
| Tool | Tier | Scope | Description |
| --------------------- | ----- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customers_search` | Read | `customer:read` | Search customers by `statuses` (array; defaults to Active, Inactive, Disabled) and/or `createdDateRange`. Results are ordered oldest-first by record-creation date. There is no `name` filter — page and match client-side. |
| `customers_get_by_id` | Read | `customer:read` | Fetch a single customer including contacts and billing address. |
| `customers_create` | Write | `customer:create` | Create a new customer. |
## Trucks & Trailers
| Tool | Tier | Scope | Description |
| ---------------------- | ---- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trucks_search` | Read | `truck:read` | Search trucks (power units) by `truckNumber` and/or `status` (array). Provide at least one filter. |
| `trucks_get_by_id` | Read | `truck:read` | Fetch a single truck by id. |
| `trucks_events_search` | Read | `truck:read` | Fetch truck events (maintenance, schedule, availability) for one or more trucks over a date range. Pass `truckIds` (array of Alvys truck ids, not unit numbers) and a `startDate`; `endDate` is optional. Returns a flat event list — an empty list means no events in the range. |
| `trailers_search` | Read | `trailer:read` | Search trailers by `trailerNumber` and/or `status` (array). Provide at least one filter. |
| `trailers_get_by_id` | Read | `trailer:read` | Fetch a single trailer by id. |
## Invoices, Fuel & Payments
| Tool | Tier | Scope | Description |
| ---------------------------------- | ----- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoices_search` | Read | `invoice:read` | Search invoices by `customerId`, `status`, `loadNumbers`, and/or `orderNumbers`, optionally narrowed by `invoicedDateRange` / `paidDateRange`. Provide at least one non-date filter — date ranges narrow results but do not count on their own. `invoicedDateRange` filters on invoice-record creation date (includes `Draft`), so pair it with a status filter for billed-amount questions. |
| `invoices_get_by_id` | Read | `invoice:read` | Fetch a single invoice including line items. |
| `fuel_transactions_search` | Read | `fuel:read` | Query fuel transactions by `truckNumber` and/or `transactionRange`. Provide at least one filter. |
| `invoices_record_carrier_payment` | Write | `invoice:update` | Record a payment to a carrier against a trip. When payments fully cover the carrier payable, the trip transitions to `Completed`. |
| `invoices_record_customer_payment` | Write | `invoice:update` | Record a payment received from a customer against a load. |
| `invoices_record_financing` | Write | `invoice:update` | Record a factoring / financing transaction. |
## Visibility & Tracking
| Tool | Tier | Scope | Description |
| ----------------------------- | ---- | ----------------- | ------------------------------------------ |
| `visibility_inbound_history` | Read | `visibility:read` | Fetch inbound tracking events for a load. |
| `visibility_outbound_history` | Read | `visibility:read` | Fetch outbound tracking events for a load. |
## Deductions
| Tool | Tier | Scope | Description |
| ---------------------- | ---- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deductions_search` | Read | `deduction:read` | Search deductions for a `driverId`, `truckId`, or `ownerOperatorId`. Provide at least one. Pass `includePaid=true` to also return paid deductions (default: open only). |
| `deductions_get_by_id` | Read | `deduction:read` | Fetch a single deduction by id. |
## Tenders
| Tool | Tier | Scope | Description |
| ------------------------ | ----- | --------------- | ------------------------------------------------------------------------------ |
| `tenders_search` | Read | `tender:read` | Search inbound tenders by `status` (array), `loadNumber`, and/or `shipmentId`. |
| `tenders_get_by_id` | Read | `tender:read` | Fetch a single inbound tender. |
| `tenders_create` | Write | `tender:create` | Create (ingest) a new inbound tender. |
| `tenders_accept` | Write | `tender:update` | Accept an inbound tender, linking each stop to a company. |
| `tenders_accept_updates` | Write | `tender:update` | Accept all pending updates on a tender. |
| `tenders_reject` | Write | `tender:update` | Reject an inbound tender. |
| `tenders_accept_cancel` | Write | `tender:update` | Accept a tender cancellation. |
***
## Error handling
Tool calls return a structured error when they cannot complete. Common cases:
| Condition | What it means |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`invalid_params`** | The call carries an unknown parameter key or an out-of-range value (e.g. `page=-1`). The message names the rejected keys and the tool's valid parameter list — read it and retry with a corrected argument shape. |
| **Missing scope** | Your token does not carry the tool's required permission. Add the scope in **Admin → API Access** and re-issue the token. |
| **Write tool disabled** | The tool is a write/destructive action disabled during beta. |
| **Rate limited** | You exceeded the per-token request limit. Back off and retry. |
| **Response too large** | The result exceeded the size cap. Narrow your search filters or paginate. |
## Related
Overview and connection setup for the Alvys MCP server.
Create credentials and issue access tokens with the right scopes.