> ## 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?"
```

## `get_workforce_contracts`

Get all contracts for a specific workforce employee. Each contract includes start/end dates. Use to inspect contract history — open-ended contracts have a `null` end date.

**Parameters:**

| Parameter          | Type   | Required | Default     | Description                                     |
| ------------------ | ------ | -------- | ----------- | ----------------------------------------------- |
| `own_workforce_id` | string | **Yes**  | —           | Workforce employee UUID (from `list_workforce`) |
| `organization_id`  | string | No       | default org | Organization UUID                               |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "e5f6a7b8-...",
    "start_date": "2024-01-15",
    "end_date": null
  },
  {
    "id": "f6a7b8c9-...",
    "start_date": "2022-06-01",
    "end_date": "2023-12-31"
  }
]
```

**Key response fields:**

| Field        | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `start_date` | Contract start date                                        |
| `end_date`   | Contract end date (`null` = open-ended / current contract) |

**Example prompts:**

```
"Show contracts for employee a1b2c3d4-..."
"Does this employee have an open-ended contract?"
"How many contract changes has this employee had?"
```

## `get_workforce_remunerations`

Get all remuneration records for a specific workforce contract. Each record includes the salary amount, currency, and period. Use to analyze compensation data for ESRS pay-gap and equal-pay disclosures.

**Parameters:**

| Parameter                   | Type   | Required | Default     | Description                                    |
| --------------------------- | ------ | -------- | ----------- | ---------------------------------------------- |
| `own_workforce_contract_id` | string | **Yes**  | —           | Contract UUID (from `get_workforce_contracts`) |
| `organization_id`           | string | No       | default org | Organization UUID                              |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "a7b8c9d0-...",
    "start_date": "2024-01-01",
    "end_date": null,
    "amount": "45000.00",
    "unit": "EUR"
  }
]
```

**Key response fields:**

| Field                     | Description                                |
| ------------------------- | ------------------------------------------ |
| `amount`                  | Remuneration amount (decimal string)       |
| `unit`                    | Currency code (e.g. `EUR`, `USD`)          |
| `start_date` / `end_date` | Remuneration period (`null` end = current) |

**Example prompts:**

```
"What is the current salary for this contract?"
"Show remuneration history for contract e5f6a7b8-..."
"Has the salary changed over time for this employee?"
```

## 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. **Inspect contracts** — `get_workforce_contracts` for contract history of a specific employee
5. **Check compensation** — `get_workforce_remunerations` for salary data per contract
6. **Filter by upload** — Use `file_id` to see records from a specific data import
7. **Cross-reference emissions** — Use `list_employees` for commuting data and `get_greenhouse_gas_emissions` for Scope 3 totals
8. **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>