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

# Intensity Metric Tools

> MCP tools for reading and loading production volumes behind emissions-per-unit metrics

# Intensity Metric Tools

Read and load **intensity metrics** — emissions per unit of activity (tCO₂e per litre bottled, per unit produced, per €M of revenue).

A **group** defines the denominator: a free-text `unit` and the emission `scopes` that make up the numerator. Each **record** inside the group holds one period's `quantity`, and the API returns the resulting `value` (emissions ÷ quantity) plus the `delta` against the previous period.

<Warning>
  The numerator is the **whole organization's** emissions. A single-site volume loaded onto a multi-site organization produces a misleading intensity — use the organization whose emissions match the volume.
</Warning>

<Note>
  Periods may not overlap inside a group, so a group holds **either** annual records **or** monthly ones — never both. Periods are immutable: delete and recreate a record to move it.
</Note>

## `list_intensity_metric_groups`

List the organization's intensity metric groups. Start here to find the `group_id` the other tools need.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description                                  |
| ----------------- | ------- | -------- | ----------- | -------------------------------------------- |
| `filter_by`       | string  | No       | —           | Free-text filter on the group's name or unit |
| `page`            | integer | No       | 1           | Page number                                  |
| `size`            | integer | No       | 50          | Results per page                             |
| `organization_id` | string  | No       | default org | Organization UUID                            |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "size": 50,
  "total": 2,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "a1b2c3d4-...",
      "name": "Millón Litros producidos",
      "unit": "Millón Litros producidos",
      "scopes": [1, 2, 3],
      "status": "active",
      "is_grouping": false
    },
    {
      "id": "661f9511-f3ac-52e5-b827-557766551111",
      "organization_id": "a1b2c3d4-...",
      "name": "Revenue (€M)",
      "unit": "Revenue (€M)",
      "scopes": [1, 2],
      "status": "active",
      "is_grouping": true
    }
  ]
}
```

**Key response fields:**

| Field         | Description                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `unit`        | The denominator, free text — this is what the app displays                                        |
| `scopes`      | Which emission scopes make up the numerator                                                       |
| `is_grouping` | `true` for a group that aggregates child organizations' groups instead of holding its own records |

## `get_intensity_metric_group`

Get one group by ID.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description       |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `group_id`        | string | **Yes**  | —           | UUID of the group |
| `organization_id` | string | No       | default org | Organization UUID |

## `list_intensity_metrics`

List the records in a group, each with its period, quantity, computed intensity and delta.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description       |
| ----------------- | ------- | -------- | ----------- | ----------------- |
| `group_id`        | string  | **Yes**  | —           | UUID of the group |
| `page`            | integer | No       | 1           | Page number       |
| `size`            | integer | No       | 50          | Results per page  |
| `organization_id` | string  | No       | default org | Organization UUID |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "size": 50,
  "total": 2,
  "items": [
    {
      "id": "a1b2c3d4-...",
      "intensity_metric_group_id": "550e8400-...",
      "start_date": "2025-01-01",
      "end_date": "2025-01-31",
      "quantity": 16.22,
      "value": 21.87,
      "delta": 0,
      "status": "active",
      "unit": "Millón Litros producidos",
      "scopes": [1, 2, 3]
    }
  ]
}
```

**Key response fields:**

| Field      | Description                                               |
| ---------- | --------------------------------------------------------- |
| `quantity` | The production volume for the period, in the group's unit |
| `value`    | The intensity: organization emissions ÷ quantity          |
| `delta`    | Change against the previous period                        |

## `get_intensity_metric`

Get one record by ID.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description        |
| ----------------- | ------ | -------- | ----------- | ------------------ |
| `metric_id`       | string | **Yes**  | —           | UUID of the record |
| `organization_id` | string | No       | default org | Organization UUID  |

## `get_organization_intensity_metrics`

Every intensity value across all of the organization's groups — the fastest way to see all intensities at once.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description                                                 |
| ----------------- | ------ | -------- | ----------- | ----------------------------------------------------------- |
| `start_date`      | string | No       | —           | Period start (`YYYY-MM-DD`), must be paired with `end_date` |
| `end_date`        | string | No       | —           | Period end (`YYYY-MM-DD`), must be paired with `start_date` |
| `organization_id` | string | No       | default org | Organization UUID                                           |

<Note>
  This summary returns `value` and `delta` but **not** the underlying quantities. Use `list_intensity_metrics` when you need the volumes.
</Note>

**Example prompts:**

```
"What are our intensity metrics for 2025?"
"Show me emissions per litre produced last year"
"Which of our intensity metrics got worse compared to the previous period?"
"List the intensity metric groups that have no data loaded yet"
```

## `create_intensity_metric_group`

Create a group — the denominator definition. Create it once, then add one record per period.

**Parameters:**

| Parameter         | Type       | Required | Default         | Description                                                           |
| ----------------- | ---------- | -------- | --------------- | --------------------------------------------------------------------- |
| `unit`            | string     | **Yes**  | —               | Denominator unit shown in the app (e.g. `"Millón Litros producidos"`) |
| `scopes`          | integer\[] | **Yes**  | —               | Scopes in the numerator                                               |
| `name`            | string     | No       | value of `unit` | Internal name                                                         |
| `is_grouping`     | boolean    | No       | `false`         | Aggregate child organizations' groups instead of holding records      |
| `organization_id` | string     | No       | default org     | Organization UUID                                                     |

<Note>
  `scopes` accepts only the combinations the API allows: `[1]`, `[2]`, `[3]`, `[1,2]`, `[2,3]`, `[1,2,3]`. Anything else (e.g. `[1,3]`) is rejected before the request is sent.
</Note>

## `update_intensity_metric_group`

Update a group. Only provided fields are changed.

**Parameters:**

| Parameter         | Type       | Required | Default     | Description       |
| ----------------- | ---------- | -------- | ----------- | ----------------- |
| `group_id`        | string     | **Yes**  | —           | UUID of the group |
| `unit`            | string     | No       | —           | New unit          |
| `name`            | string     | No       | —           | New internal name |
| `scopes`          | integer\[] | No       | —           | New scopes        |
| `organization_id` | string     | No       | default org | Organization UUID |

## `delete_intensity_metric_group`

Delete a group **and every record inside it**.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description       |
| ----------------- | ------ | -------- | ----------- | ----------------- |
| `group_id`        | string | **Yes**  | —           | UUID of the group |
| `organization_id` | string | No       | default org | Organization UUID |

<Warning>
  The periods the group held stop contributing to dashboards and reports. Confirm with the user before calling this.
</Warning>

## `create_intensity_metric`

Add a production volume for one period to a group.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description                                |
| ----------------- | ------ | -------- | ----------- | ------------------------------------------ |
| `group_id`        | string | **Yes**  | —           | UUID of the group the record belongs to    |
| `start_date`      | string | **Yes**  | —           | Period start, `YYYY-MM-DD` (inclusive)     |
| `end_date`        | string | **Yes**  | —           | Period end, `YYYY-MM-DD` (inclusive)       |
| `quantity`        | number | **Yes**  | —           | Volume in the group's unit, greater than 0 |
| `organization_id` | string | No       | default org | Organization UUID                          |

Returns the created record including the computed intensity value. An overlapping period is rejected with `INTENSITY_METRICS_ALEADY_EXISTS_IN_THIS_PERIOD`.

## `update_intensity_metric`

Update a record's quantity. Periods are immutable.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description                |
| ----------------- | ------ | -------- | ----------- | -------------------------- |
| `metric_id`       | string | **Yes**  | —           | UUID of the record         |
| `quantity`        | number | **Yes**  | —           | New volume, greater than 0 |
| `organization_id` | string | No       | default org | Organization UUID          |

## `delete_intensity_metric`

Delete a record.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description        |
| ----------------- | ------ | -------- | ----------- | ------------------ |
| `metric_id`       | string | **Yes**  | —           | UUID of the record |
| `organization_id` | string | No       | default org | Organization UUID  |

**Example prompts:**

```
"Create an intensity metric for millions of litres produced, all three scopes"
"Load 224.058 million litres for 2025 into the litres-produced metric"
"Load these monthly production volumes for 2025: [pasted table]"
"Correct the March quantity to 17.51"
```

## Workflow

1. **Find the group** — `list_intensity_metric_groups`, or `create_intensity_metric_group` if the denominator doesn't exist yet
2. **Check what's loaded** — `list_intensity_metrics` to see existing periods and avoid an overlap
3. **Load periods** — `create_intensity_metric` once per period, all with the same granularity
4. **Verify** — `list_intensity_metrics` for the group, or `get_organization_intensity_metrics` for everything at once

## Limitations

Parent-level roll-up cannot be configured through these tools: a group can be created with `is_grouping`, but linking a parent grouping to its children's groups is not exposed by the API yet.

## Related

<CardGroup cols={2}>
  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    The numerator — GHG emissions these metrics divide
  </Card>

  <Card title="Organizations" icon="sitemap" href="/mcp/organizations">
    The org tree, to pick the organization matching a volume
  </Card>

  <Card title="Custom KPIs" icon="chart-simple" href="/mcp/custom-kpis">
    User-defined indicators collected through campaigns
  </Card>

  <Card title="CLI Intensity Metrics" icon="terminal" href="/cli/intensity">
    The same operations from the command line
  </Card>
</CardGroup>