> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Business Travel Tools
> MCP tools for managing business travel records and emissions (Scope 3) — list, create, and query travel data
# Business Travel Tools
Manage Scope 3 business travel records — flights, train journeys, bus trips, and car travel with origin/destination, distance, and CO₂e emissions.
Business travel records can be large (origin/destination details, geocodes). The default page size is **10** — keep `size` ≤ 20 and use pagination to avoid oversized responses.
## `list_business_travels`
List business travel records with optional filters.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ----------- | ----------------------------------------- |
| `organization_id` | string | No | default org | Organization UUID |
| `transport_type` | string | No | — | Filter by transport mode (see below) |
| `start_date` | string | No | — | Filter trips from this date (YYYY-MM-DD) |
| `end_date` | string | No | — | Filter trips until this date (YYYY-MM-DD) |
| `page` | integer | No | 1 | Page number |
| `size` | integer | No | 10 | Results per page (keep ≤ 20) |
### Transport Types
| Value | Description |
| ------- | ----------- |
| `plane` | Air travel |
| `train` | Rail travel |
| `bus` | Bus travel |
| `car` | Car travel |
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"items": [
{
"id": "5822a93c-...",
"transport_type": "train",
"distance_km": 25.0,
"fuel_type": "electric",
"travel_type": "round",
"travel_number": 1,
"start_date": "2025-11-01",
"end_date": "2025-11-26",
"co2e": 3.56,
"status": "active"
}
],
"total": 2349,
"page": 1,
"size": 10,
"pages": 235
}
```
**Key response fields:**
| Field | Description |
| ---------------- | -------------------------------------------------------- |
| `transport_type` | Mode of transport used |
| `distance_km` | Total distance in kilometers |
| `fuel_type` | Fuel/energy type (e.g. `electric`, `diesel`, `jet_fuel`) |
| `travel_type` | `one_way` or `round` trip |
| `travel_number` | Number of trips with this configuration |
| `co2e` | Calculated CO₂e emissions in kg |
**Example prompts:**
```
"Show all business travel by plane"
"What were the highest-emission trips last year?"
"Show train travel records for Q1 2025"
"List business trips from Q4 2024"
"How much CO₂ did our flights generate in 2024?"
```
***
## Write Operations
### `create_business_travel`
Create a business travel record for Scope 3 employee travel emissions. CO₂e is calculated asynchronously after creation — the response will initially show `co2e` as `null`.
**Distance can be specified in two ways:**
* Provide `origin` + `destination` (addresses or city names) — distance is calculated automatically via Google Maps (or geodesic for aircraft).
* Provide `distance_km` directly when the distance is already known.
At least one of these must be given.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transport_type` | string | **Yes** | — | Mode of transport: `car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry` |
| `start_date` | string | **Yes** | — | Travel start date (`YYYY-MM-DD`) |
| `end_date` | string | **Yes** | — | Travel end date (`YYYY-MM-DD`), must be on or after `start_date` |
| `origin` | string | No | — | Origin address or city (e.g. `"Madrid, Spain"`) |
| `destination` | string | No | — | Destination address or city (e.g. `"Barcelona, Spain"`) |
| `distance_km` | number | No | — | Distance in kilometers (use instead of origin/destination if known) |
| `vehicle_size` | string | No | — | Car size: `small`, `medium`, `large`. **Required when `transport_type=car`** |
| `fuel_type` | string | No | — | Car fuel: `diesel`, `natural_gas`, `petrol`, `lpg`, `electric`, `hybrid`, `not_fuel_based`, `do_not_know`. **Required when `transport_type=car`** |
| `renewable_energy` | string | No | — | Renewable energy used: `yes`, `no`, `do_not_know` |
| `travel_type` | string | No | `one_way` | `round` (round trip) or `one_way` |
| `travel_number` | integer | No | 1 | Number of trips in the period (max 10,000) |
| `passenger_number` | integer | No | 1 | Number of passengers |
| `name` | string | No | — | Traveler or trip name for identification |
| `organization_id` | string | No | default org | Organization UUID |
When `transport_type` is `car`, you **must** also provide `vehicle_size` and `fuel_type`. These fields are ignored for other transport types.
CO₂e emissions are calculated in the background after creation. The initial response will show `co2e: null`. Call `list_business_travels` after a few seconds to see the calculated value.
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "5822a93c-...",
"transport_type": "train",
"origin": "Madrid, Spain",
"destination": "Barcelona, Spain",
"distance_km": 621.0,
"start_date": "2025-03-01",
"end_date": "2025-03-01",
"travel_type": "one_way",
"travel_number": 1,
"passenger_number": 1,
"status": "active",
"co2e": null,
"created_at": "2025-03-01T10:30:00Z"
}
```
**Example prompts:**
```
"Log a train trip from Madrid to Barcelona on March 1st"
"Create a round-trip flight from London to New York, 2 passengers"
"Add a car trip, 150 km, diesel medium car"
"Record 5 daily bus commutes of 20 km each for January"
```
**Common errors:**
| Error | Cause |
| ----------------------------------------------------------------- | ------------------------------------------------ |
| 422: "Either distance\_km or origin+destination must be provided" | Neither distance nor locations were given |
| 422: "vehicle\_size is required for car transport" | Missing `vehicle_size` when `transport_type=car` |
| 422: "fuel\_type is required for car transport" | Missing `fuel_type` when `transport_type=car` |
| 422: "end\_date must be on or after start\_date" | `end_date` is before `start_date` |
### `update_business_travel`
Update an existing business travel record. Only the fields you provide are changed. CO₂e is recalculated after update.
The API requires either `distance_km` or `origin` + `destination` to remain valid after update. If changing the route, provide either a new origin/destination pair or a new `distance_km`.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------- | ------- | -------- | ----------- | ------------------------------------------------------------------------------ |
| `business_travel_id` | string | **Yes** | — | UUID of the record. Use `list_business_travels` to find it |
| `transport_type` | string | No | — | `car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry` |
| `start_date` | string | No | — | New start date (`YYYY-MM-DD`) |
| `end_date` | string | No | — | New end date (`YYYY-MM-DD`) |
| `origin` | string | No | — | New origin address |
| `destination` | string | No | — | New destination address |
| `distance_km` | number | No | — | New distance in km (> 0) |
| `vehicle_size` | string | No | — | `small`, `medium`, `large` (for cars) |
| `fuel_type` | string | No | — | `diesel`, `petrol`, `electric`, `hybrid`, etc. (for cars) |
| `renewable_energy` | string | No | — | `yes`, `no`, `do_not_know` |
| `travel_type` | string | No | — | `round` or `one_way` |
| `travel_number` | integer | No | — | Number of trips (1–10000) |
| `passenger_number` | integer | No | — | Number of passengers (>= 1) |
| `name` | string | No | — | Traveler or trip name |
| `organization_id` | string | No | default org | Organization UUID |
**Example prompts:**
```
"Change business travel abc-123 to 250 km"
"Update the trip to use aircraft instead of train"
"Fix the destination of travel xyz to 'Barcelona, Spain'"
```
**Common errors:**
| Error | Cause |
| ----------------------------------------------------------------- | ------------------------------------------------------ |
| 404: "Business travel not found" | Invalid business travel UUID |
| 422: "Either distance\_km or origin+destination must be provided" | Update would leave the record without a valid distance |
***
## Workflows
### Querying travel records
1. **List travel records** — `list_business_travels` filtered by transport type or date range
2. **View hotel stays** — `list_hotel_stays` for accommodation linked to business trips
3. **View emissions** — `get_greenhouse_gas_emissions` with `category=travels` for aggregated totals
### Logging a new business trip
1. **Create the travel record** — `create_business_travel` with transport type, dates, and origin/destination or distance
2. **Verify** — `list_business_travels` after a few seconds to confirm creation and CO₂e calculation
3. **Log accommodation** — if applicable, create a hotel stay record for the same trip
## Related
REST API endpoint for business travel creation
REST API equivalent with additional filters
Accommodation records for business trips
Aggregated Scope 3 travel emissions