> ## 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.
# Employee Tools
> MCP tools for querying employees and commuting data (Scope 3)
# Employee Tools
Query employees and their commuting periods — this is Scope 3 employee commuting data. Each employee can have multiple commuting periods with different transport modes, distances, and CO₂e calculations.
## `list_employees`
List employees with their commuting periods, including origin/destination data and CO₂e emissions.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ----------- | ------------------------------------------------------------- |
| `organization_id` | string | No | default org | Organization UUID |
| `situation` | string | No | — | Employment situation: `active`, `inactive` |
| `status` | string | No | — | Data processing status: `uploaded`, `loading` |
| `transport_type` | string | No | — | Filter by commuting transport mode (see below) |
| `response_medium` | string | No | — | How data was collected: `manual`, `qr`, `form`, `file_upload` |
| `file_id` | string | No | — | Filter by source file UUID (for bulk-uploaded employees) |
| `search` | string | No | — | Search by name or email |
| `created_at_from` | string | No | — | Filter employees created at/after this date (ISO datetime) |
| `created_at_to` | string | No | — | Filter employees created at/before this date (ISO datetime) |
| `co2e_status` | string | No | — | Calculation state: `calculated`, `not_calculated` |
| `page` | integer | No | 1 | Page number |
| `size` | integer | No | 50 | Results per page |
| Value | Description |
| ----------------------- | ---------------- |
| `car` | Private car |
| `bus` | Bus |
| `train` | Train |
| `metro` | Metro/subway |
| `tram` | Tram |
| `motorbike` | Motorbike |
| `bicycle` | Bicycle |
| `walking` | Walking |
| `telecommuting` | Remote work |
| `electric_kick_scooter` | Electric scooter |
| `trolleybus` | Trolleybus |
Employee responses include nested `periods` arrays with detailed commuting data. Each period has `total_km`, `transport_type`, `fuel_type`, `co2e`, and schedule fields. Large organizations can have thousands of employees — use `size` ≤ 20 and paginate to avoid oversized responses.
**Example response:**
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"items": [
{
"id": "d43aaf5b-...",
"name": "María García",
"email": "maria@company.com",
"situation": "active",
"status": "uploaded",
"periods": [
{
"id": "a1b2c3d4-...",
"transport_type": "car",
"fuel_type": "diesel",
"vehicle_size": "medium",
"total_km": 25.0,
"weekly_travels": [0, 1, 2, 3, 4],
"daily_trips": 2,
"carpool": false,
"commuting_type": "in_itinere",
"origin": "Calle Mayor 1, Madrid",
"destination": "Paseo de la Castellana 50, Madrid",
"co2e": 1820.5,
"start_date": "2025-01-01",
"end_date": null,
"response_medium": "form"
}
],
"created_at": "2024-11-24T10:30:00Z",
"updated_at": "2025-03-15T14:20:00Z"
}
],
"total": 99,
"page": 1,
"size": 50,
"pages": 2
}
```
**Key response fields:**
| Field | Description |
| -------------------------- | ------------------------------------------------------------------------ |
| `situation` | Employment situation (`active`, `inactive`) |
| `status` | Data processing status (`uploaded` = ready, `loading` = being processed) |
| `periods[].transport_type` | Mode of transport for this commuting period |
| `periods[].total_km` | One-way commute distance in km |
| `periods[].co2e` | Calculated CO₂e emissions in kg for this period |
| `periods[].commuting_type` | `in_itinere` (home→office) or `in_labore` (work-related travel) |
| `periods[].weekly_travels` | Days of the week (0=Mon, 4=Fri) the employee commutes |
**Example prompts:**
```
"How many active employees do we have?"
"Search for employees named García"
"List employees who commute by car"
"Show employees whose emissions haven't been calculated yet"
"Which employees were uploaded via the last CSV file?"
```
## `create_employee`
Create a new employee for commuting emissions tracking (Scope 3). At least one of `name` or `email` must be provided.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `situation` | string | Yes | Employee situation: `active`, `inactive`, or `terminated` |
| `name` | string | No | Employee name (required if no email) |
| `email` | string | No | Employee email (required if no name) |
| `organization_id` | string | No | Organization UUID (uses default if not set) |
After creating an employee, add commuting periods to calculate Scope 3 emissions.
**Example prompts:**
```
"Create a new active employee named María García"
"Add employee maria@company.com to the organization"
```
## `update_employee`
Update an existing employee. Only provided fields are changed (partial update).
**Parameters:**
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ---------------------------------------------------- |
| `employee_id` | string | Yes | UUID of the employee to update |
| `name` | string | No | New employee name |
| `email` | string | No | New employee email |
| `situation` | string | No | New situation: `active`, `inactive`, or `terminated` |
| `organization_id` | string | No | Organization UUID (uses default if not set) |
**Example prompts:**
```
"Set employee d43aaf5b-... to inactive"
"Update María García's email to maria.garcia@company.com"
```
## Workflow
1. **List employees** — `list_employees` to find employees by name, situation, or transport type
2. **Create employees** — `create_employee` to add new employees for commuting tracking
3. **Update employees** — `update_employee` to change situation, name, or email
4. **Analyze commuting patterns** — Use `transport_type` filter to see how employees commute
5. **Check data completeness** — Use `co2e_status=not_calculated` to find employees missing emission calculations
6. **View emissions** — `get_greenhouse_gas_emissions` with `category=employees_in_itinere` for aggregated commuting totals
## Related
REST API equivalent with additional filters
Aggregated Scope 3 commuting emissions
Manage employees from the command line