> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trebellar.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trebellar.app/_mcp/server.

# MCP tools reference

This page documents every tool available on the [Trebellar MCP server](/mcp-server).
You won't normally call these directly — your assistant chooses which tool(s) to call
and with which parameters based on your question — but this reference is useful for
understanding exactly what data is available and how it's scoped.

> **Tip**
>
> New to the MCP server? Start with [MCP Server](/mcp-server) for how to connect a
> client before working through the tools below.

## Shared concepts

A few parameters are shared across most tools.

### Scoping to assets

Almost every tool accepts a **`fromAssetIds`** array of asset IDs (buildings, floors,
or spaces — see [`list_assets`](#list_assets)). Leaving it empty, or omitting it
entirely, refers to your **entire portfolio**.

Some tools additionally accept an **`assetLocationGroup`**, for referring to a named
grouping instead of listing individual asset IDs:

| Field  | Description                                            |
| ------ | ------------------------------------------------------ |
| `id`   | The ID of the location group                           |
| `type` | The kind of grouping — e.g. campus, site, city, region |

When both `fromAssetIds` and `assetLocationGroup` are provided, the two sets of
buildings are combined.

### Selected business days

The prediction tools accept an optional **`selectedBusinessDays`** object that controls
which days of the week are included in the calculation. It's a union of three shapes:

| `type`   | Shape                                                                     | Meaning                                                                                                    |
| -------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `global` | `{ type: "global", businessDays: [...] }`                                 | Apply the same set of weekdays (e.g. `["monday", ..., "friday"]`) to every asset in scope                  |
| `anchor` | `{ type: "anchor" }`                                                      | Use each asset's own configured business days, with no override                                            |
| `assets` | `{ type: "assets", assetBusinessDays: [{ assetId, businessDays }, ...] }` | Set a different weekday list per asset. `assetId` defaults to `"root"`, a reference to the whole portfolio |

Omitting `selectedBusinessDays` entirely uses each asset's own configured business days
(equivalent to `anchor`).

### Timeframes

`timeframe` is always a two-element array of ISO dates (`YYYY-MM-DD`), e.g.
`["2026-01-01", "2026-12-31"]`.

## Portfolio & assets

### `get_portfolio_overview`

Returns a comprehensive overview of your organization's real estate portfolio:
buildings with their properties, the location group hierarchy, people groups, cost
categories, and other org-level context.

Call this first to understand the shape of your portfolio before querying specific
assets or data — it takes no parameters.

### `list_assets`

Lists the asset hierarchy: **Building → Floor → Space**.

| Parameter          | Type   | Required | Description                                                                                                                                                                           |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fromAssetId`      | string | No       | Asset ID to scope the tree from. Defaults to root-level assets (the whole portfolio)                                                                                                  |
| `lowestAssetLevel` | enum   | No       | How deep to expand the hierarchy: `ROOT` (default, the entire portfolio), `STRUCTURE`, `FLOOR` (buildings + floors), `SPACE` (buildings + floors + spaces), `DESK`, `SENSOR`, `OTHER` |

The result is a compact, line-oriented listing rather than nested JSON:

```text
B|<assetId>|<label>|<status>
F|<assetId>|<label>|<status>
S|<assetId>|<label>|leaf:{desk:N,sensor:M,other:K,unknown:J}
```

`B`/`F`/`S` mark a building, floor, or space respectively. Space rows include
aggregated counts of descendant leaf assets (desks, sensors, and other/unknown device
types) when present.

### `get_asset_details`

Returns detailed information for one or more assets: all properties (location,
capacity, lease info, status) plus immediate children — floors for a building, spaces
for a floor.

| Parameter      | Type      | Required | Description                                          |
| -------------- | --------- | -------- | ---------------------------------------------------- |
| `fromAssetIds` | string\[] | Yes      | The asset IDs to retrieve details for (at least one) |

Use this after `list_assets` or `get_portfolio_overview` to drill into specific
buildings, floors, or spaces.

## Attendance

### `get_monthly_building_attendance`

Returns monthly attendance data for one or more buildings over the past year: total
visits, unique visitors, and average daily attendance per month.

| Parameter      | Type              | Required | Description                                         |
| -------------- | ----------------- | -------- | --------------------------------------------------- |
| `fromAssetIds` | string\[]         | Yes      | The buildings to retrieve attendance data for       |
| `timeframe`    | \[string, string] | Yes      | ISO date range, e.g. `["2023-01-01", "2023-12-01"]` |

> **Note**
>
> This tool links a chart UI resource — see [Interactive results](/mcp-server#interactive-results-mcp-apps).
> In a client that supports MCP Apps, the result renders as a bar chart; other clients
> fall back to the underlying monthly figures.

## Predictions

The four tools below all forecast attendance rates, and share the `assetType`,
`fromAssetIds`, `timeframe`, and `selectedBusinessDays` parameters described in
[Shared concepts](#shared-concepts) above.

### `predictions_Predicted_Daily_Attendance_Rates`

Forecasted daily attendance rates for assets of the given type, one value per day over
the timeframe, with additional context (weekday, week, month, etc.) alongside each
value.

| Parameter              | Type                       | Required | Description                                                  |
| ---------------------- | -------------------------- | -------- | ------------------------------------------------------------ |
| `assetType`            | enum: `STRUCTURE`, `SPACE` | Yes      | Whether to forecast at the building or space level           |
| `fromAssetIds`         | string\[]                  | No       | Assets to forecast. Empty/omitted means the entire portfolio |
| `timeframe`            | \[string, string]          | Yes      | ISO date range to forecast over                              |
| `selectedBusinessDays` | object                     | No       | See [Selected business days](#selected-business-days)        |

### `predictions_Predicted_Daily_Attendance_Rates_by_People_Group`

The same forecast as above, scoped to a single people group.

| Parameter              | Type                       | Required | Description                                                          |
| ---------------------- | -------------------------- | -------- | -------------------------------------------------------------------- |
| `assetType`            | enum: `STRUCTURE`, `SPACE` | Yes      | Whether to forecast at the building or space level                   |
| `fromAssetIds`         | string\[]                  | No       | Assets to forecast. Empty/omitted means the entire portfolio         |
| `groupId`              | string                     | No       | The people group to forecast for. Defaults to `"root"` (every group) |
| `timeframe`            | \[string, string]          | Yes      | ISO date range to forecast over                                      |
| `selectedBusinessDays` | object                     | No       | See [Selected business days](#selected-business-days)                |

### `predictions_Predicted_Daily_Aggregate_Attendance_Rates`

Aggregates forecasted daily attendance rates across a set of grouping fields, rather
than returning one row per asset per day. For example, to get the monthly aggregate
attendance rate per asset, group by both the asset and the month.

| Parameter              | Type                       | Required | Description                                                                            |
| ---------------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `assetType`            | enum: `STRUCTURE`, `SPACE` | Yes      | Whether to forecast at the building or space level                                     |
| `aggFields`            | enum\[]                    | No       | Fields to aggregate on. Defaults to `["field__asset__id"]`. See below for the full set |
| `fromAssetIds`         | string\[]                  | No       | Assets to forecast. Empty/omitted means the entire portfolio                           |
| `timeframe`            | \[string, string]          | Yes      | ISO date range to forecast over                                                        |
| `selectedBusinessDays` | object                     | No       | See [Selected business days](#selected-business-days)                                  |

Available `aggFields` values: `field__interval__day`, `field__interval__week`,
`field__interval__weekday`, `field__interval__month`, `field__interval__year`,
`field__asset__id`, `field__asset_ds__floor_id`, `field__asset_ds__structure_id`,
`field__asset_ds__space_id`.

```json
{
  "assetType": "STRUCTURE",
  "timeframe": ["2026-01-01", "2026-12-31"],
  "aggFields": ["field__asset__id", "field__interval__month"]
}
```

### `predictions_Daily_Attendance_Rates_by_People_Group_aggregate`

The same aggregation as above, additionally grouped by people group.

| Parameter              | Type                       | Required | Description                                                  |
| ---------------------- | -------------------------- | -------- | ------------------------------------------------------------ |
| `assetType`            | enum: `STRUCTURE`, `SPACE` | Yes      | Whether to forecast at the building or space level           |
| `aggFields`            | enum\[]                    | No       | Fields to aggregate on. Defaults to `["field__asset__id"]`   |
| `fromAssetIds`         | string\[]                  | No       | Assets to forecast. Empty/omitted means the entire portfolio |
| `timeframe`            | \[string, string]          | Yes      | ISO date range to forecast over                              |
| `selectedBusinessDays` | object                     | No       | See [Selected business days](#selected-business-days)        |

`aggFields` accepts the same values as
[`predictions_Predicted_Daily_Aggregate_Attendance_Rates`](#predictions_predicted_daily_aggregate_attendance_rates)
plus `field__pg__id`, to aggregate by people group.

## Attrition

### `attrition_People_Attrition`

Returns headcount attrition metrics for people associated with buildings, over one or
more periods of a timeframe.

| Parameter               | Type                                     | Required | Description                                                                                                                                                                                                |
| ----------------------- | ---------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeframe`             | \[string, string]                        | Yes      | ISO date range to report over                                                                                                                                                                              |
| `fromAssetIds`          | string\[]                                | No       | Buildings to include. Empty/omitted means the entire portfolio                                                                                                                                             |
| `assetLocationGroup`    | object                                   | No       | A location grouping (campus, site, city, region, ...) — see [Scoping to assets](#scoping-to-assets). Combined with `fromAssetIds` if both are given                                                        |
| `cadence`               | enum: `days`, `weeks`, `months`, `years` | No       | Splits the timeframe into fixed-length periods. `months`/`years` are 30/365-day approximations, so period boundaries won't align to calendar months. Omit for a single period spanning the whole timeframe |
| `aggregateAssets`       | boolean                                  | No       | Combine all buildings in scope into a single row per period. Defaults to `true` when `assetLocationGroup` is provided                                                                                      |
| `includeGroupBreakdown` | boolean                                  | No       | Return one row per (asset, people group, period) instead of summing across people groups. Defaults to `false`                                                                                              |
| `propertiesFilter`      | object                                   | No       | Only consider people whose properties match **all** of the given key/value pairs at each point in time, e.g. `{ "employeeStatus": "employee" }`                                                            |

Each returned row covers one period (identified by `periodStart`) and reports:

| Field                              | Meaning                                                                                   |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `joined`                           | New hires placed in the asset during the period                                           |
| `left`                             | People in the asset at the period start who left the organization                         |
| `transferredOut` / `transferredIn` | People who moved between (building, people group) pairs while staying in the organization |
| `netTransfers`                     | `transferredIn` minus `transferredOut`                                                    |
| `netGrowth`                        | `joined` minus `left` plus `netTransfers` — the net headcount change for the row's scope  |

> **Warning**
>
> `transferredOut`/`transferredIn` are counted per **(building, people group)** pair, so
> at building level they include moves between people groups within the same building —
> not only people entering or leaving the building itself. When surfacing these gross
> counts, make that distinction clear, or prefer `netTransfers`/`netGrowth` when the
> question is about overall movement or headcount change.

Aggregated rows (`aggregateAssets: true`) omit the gross transfer counts and report
`netTransfers` only.