> ## 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.

# Workforce Tools

> MCP tools for querying own workforce data — the ESG social pillar

# Workforce Tools

Query own workforce records for ESG social reporting — employee demographics, employment categories, contract periods, and locations. This is the **social pillar** of ESG: headcount composition, diversity metrics, contract types, and geographic distribution.

<Note>
  Workforce data is distinct from **Employee commuting** data (Scope 3 emissions). Employees track commuting patterns and transport modes; workforce tracks contracts, demographics, and labor conditions for CSRD/ESRS social disclosures.
</Note>

## `list_workforce`

List own workforce records (employees) with pagination and filters. Each record represents one person with their demographic data and current contract summary.

**Parameters:**

| Parameter              | Type    | Required | Default     | Description                                               |
| ---------------------- | ------- | -------- | ----------- | --------------------------------------------------------- |
| `organization_id`      | string  | No       | default org | Organization UUID                                         |
| `external_employee_id` | string  | No       | —           | Search by external employee ID (exact match)              |
| `file_id`              | string  | No       | —           | Filter by source upload file UUID                         |
| `created_at_from`      | string  | No       | —           | Filter records created at/after this date (ISO datetime)  |
| `created_at_to`        | string  | No       | —           | Filter records created at/before this date (ISO datetime) |
| `page`                 | integer | No       | 1           | Page number                                               |
| `size`                 | integer | No       | 50          | Results per page (max 200)                                |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "external_employee_id": "EMP-2024-001",
      "employment_category": "full_time",
      "location_code": "ES",
      "nationality": "ES",
      "contract_start_date": "2023-06-01",
      "contract_end_date": null,
      "created_at": "2024-01-15T09:30:00",
      "file_id": "f5e6d7c8-...",
      "file_name": "workforce_2024.csv"
    }
  ],
  "total": 145,
  "page": 1,
  "size": 50
}
```

**Key response fields:**

| Field                                       | Description                                                    |
| ------------------------------------------- | -------------------------------------------------------------- |
| `external_employee_id`                      | Company's internal employee identifier                         |
| `employment_category`                       | Contract category (e.g. `full_time`, `part_time`, `temporary`) |
| `location_code`                             | ISO country code where the employee works                      |
| `nationality`                               | Employee's nationality (ISO country code)                      |
| `contract_start_date` / `contract_end_date` | Current contract period (null end = open-ended)                |
| `file_id` / `file_name`                     | Source file if the record was bulk-uploaded                    |

**Example prompts:**

```
"How many employees do we have in our workforce?"
"List all workforce records uploaded from the latest CSV"
"Show workforce records for employee EMP-2024-001"
"How many employees were added since January 2025?"
```

## `list_workforce_absenteeisms`

List absenteeism and workplace accident records linked to workforce employees. Each record is either an **absenteeism** (with start/end dates and hours lost) or an **accident** (with date and context description). Use for ESRS health & safety disclosures.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description                                               |
| ----------------- | ------- | -------- | ----------- | --------------------------------------------------------- |
| `organization_id` | string  | No       | default org | Organization UUID                                         |
| `search`          | string  | No       | —           | Search by external employee ID                            |
| `file_id`         | string  | No       | —           | Filter by source upload file UUID                         |
| `created_at_from` | string  | No       | —           | Filter records created at/after this date (ISO datetime)  |
| `created_at_to`   | string  | No       | —           | Filter records created at/before this date (ISO datetime) |
| `page`            | integer | No       | 1           | Page number                                               |
| `size`            | integer | No       | 50          | Results per page (max 200)                                |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "b2c3d4e5-...",
      "external_employee_id": "EMP-2024-001",
      "own_workforce_id": "a1b2c3d4-...",
      "type": "absenteeism",
      "absenteeism_start_date": "2025-03-10",
      "absenteeism_end_date": "2025-03-14",
      "absenteeism_hours": 40.0,
      "accident_date": null,
      "accident_context": null,
      "created_at": "2025-03-15T09:00:00",
      "file_name": "absenteeism_q1.csv"
    },
    {
      "id": "c3d4e5f6-...",
      "external_employee_id": "EMP-2024-042",
      "own_workforce_id": "d5e6f7a8-...",
      "type": "accident",
      "absenteeism_start_date": null,
      "absenteeism_end_date": null,
      "absenteeism_hours": null,
      "accident_date": "2025-02-20",
      "accident_context": "Fall from height during maintenance",
      "created_at": "2025-02-21T08:30:00",
      "file_name": null
    }
  ],
  "total": 23,
  "page": 1,
  "size": 50
}
```

**Key response fields:**

| Field                                             | Description                                                |
| ------------------------------------------------- | ---------------------------------------------------------- |
| `type`                                            | Record type: `absenteeism` or `accident`                   |
| `absenteeism_start_date` / `absenteeism_end_date` | Absence period (only for absenteeism records)              |
| `absenteeism_hours`                               | Total hours lost to absence                                |
| `accident_date`                                   | Date of the workplace accident (only for accident records) |
| `accident_context`                                | Description of the accident circumstances                  |
| `own_workforce_id`                                | Links back to the employee in `list_workforce`             |

**Example prompts:**

```
"Show all workplace accidents this year"
"How many absenteeism records do we have?"
"List absenteeisms for employee EMP-2024-001"
"What accidents were reported in Q1 2025?"
```

## `list_workforce_trainings`

List training records linked to workforce employees. Each record represents a training session with type, duration in hours, dates, and description. Use for ESRS social disclosures on employee training hours and skill development.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description                                               |
| ----------------- | ------- | -------- | ----------- | --------------------------------------------------------- |
| `organization_id` | string  | No       | default org | Organization UUID                                         |
| `search`          | string  | No       | —           | Search by external employee ID                            |
| `file_id`         | string  | No       | —           | Filter by source upload file UUID                         |
| `created_at_from` | string  | No       | —           | Filter records created at/after this date (ISO datetime)  |
| `created_at_to`   | string  | No       | —           | Filter records created at/before this date (ISO datetime) |
| `page`            | integer | No       | 1           | Page number                                               |
| `size`            | integer | No       | 50          | Results per page (max 200)                                |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "d4e5f6a7-...",
      "external_employee_id": "EMP-2024-001",
      "own_workforce_id": "a1b2c3d4-...",
      "type": "health_safety",
      "description": "Workplace safety certification",
      "hours": 8.0,
      "start_date": "2025-03-01",
      "end_date": "2025-03-01",
      "created_at": "2025-03-02T10:00:00",
      "file_name": "trainings_q1.csv"
    }
  ],
  "total": 58,
  "page": 1,
  "size": 50
}
```

**Key response fields:**

| Field                     | Description                                                         |
| ------------------------- | ------------------------------------------------------------------- |
| `type`                    | Training category (e.g. `health_safety`, `environmental`, `skills`) |
| `hours`                   | Duration of the training session in hours                           |
| `start_date` / `end_date` | Training period                                                     |
| `description`             | Free-text description of the training content                       |
| `own_workforce_id`        | Links back to the employee in `list_workforce`                      |

**Example prompts:**

```
"How many training hours were logged this year?"
"List all health and safety trainings"
"Show training records for employee EMP-2024-001"
"What trainings were uploaded in the latest batch?"
```

## Workflow

1. **List workforce** — `list_workforce` to get employee headcount and demographics
2. **Check health & safety** — `list_workforce_absenteeisms` for absenteeism and accident records
3. **Review training** — `list_workforce_trainings` for training hours and skill development
4. **Filter by upload** — Use `file_id` to see records from a specific data import
5. **Cross-reference emissions** — Use `list_employees` for commuting data and `get_greenhouse_gas_emissions` for Scope 3 totals
6. **Check facilities** — Use `list_facilities` to map `location_code` to specific sites

## Related

<CardGroup cols={2}>
  <Card title="Employees" icon="person-walking" href="/mcp/employees">
    Employee commuting data (Scope 3 emissions) — different from workforce demographics
  </Card>

  <Card title="Facilities" icon="building" href="/mcp/facilities">
    Facilities where workforce members are located
  </Card>

  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    GHG emissions including employee commuting
  </Card>

  <Card title="Organizations" icon="sitemap" href="/mcp/organizations">
    Organization hierarchy for group-level workforce analysis
  </Card>
</CardGroup>