Analyse spend by project or region

# Spend analysis by analytical field

## The central trap: `analyticalCode` mixes every field

`spendesk_analyze_spend` with `groupBy: ["analyticalCode"]` returns **the values of every analytical field in one list** — values of your custom fields, and expense categories too. A row does not say which field its value belongs to.

Verified live: over 12 months, the list mixed "France" (Region field), "IT & Technical fees" (an expense category) and "GM Budget" (Supplier Budget field). The rows added up to far more than the real total (EUR 113,720.26), because one payable carries one value per field and is therefore counted once per field. The `share` percentages are computed on that inflated sum.

**Rule: never add up or compare `analyticalCode` rows before restricting them to a single field.**

## Step 1 — Pick the field

```json
{ "tool": "get_analytical_fields", "params": {} }
```

Returns the fields with `id`, `name`, `type`. Archived fields are included: keep only those whose `archivedAt` is `null`. The expense categories field is not in this list (read it with `get_expense_categories`).

If the user did not name the field, list the active fields and ask which one to analyse.

## Step 2 — Get that field's values

```json
{ "tool": "get_analytical_field_values", "params": { "fieldId": "<field id>" } }
```

Keep the list of value `id`s: it is what isolates the field. Archived values are included (non-null `archivedAt`) — keep them for history, but flag them.

## Step 3 — Analyse, then keep only the field's rows

```json
{
  "tool": "spendesk_analyze_spend",
  "params": {
    "fromDate": "YYYY-MM-DD",
    "toDate": "YYYY-MM-DD",
    "groupBy": ["analyticalCode", "month"],
    "limit": 50
  }
}
```

- Put `analyticalCode` **first** in `groupBy`: it is the only position where rows carry only the amounts of that value.
- Raise `limit` to 50: with the default (10), the values of the field you want can end up buried in the "Others" row.
- In the response, **keep only the rows whose `id` is in the step 2 list**. Ignore the rest.
- Maximum period: 366 days. Beyond that, split and combine only once every call has succeeded.

## Step 4 — Work out the unallocated share

The field's total (sum of the rows kept) is lower than or equal to `summary.totalAmount`. The gap is spend **with no value on this field**: present it explicitly as "unallocated" — it is often the most useful figure for FP&A.

Recompute percentages yourself, on the field's total or on `summary.totalAmount` — do not reuse `share`.

## Variant — filter on one value

`filters.analyticalCodes: ["<value id>"]` restricts to payables carrying that value on at least one line. Careful: `summary.totalAmount` and every other dimension then count those payables **in full**, including their lines on other values. Only `analyticalCode` rows (placed first) are exact.

## Recommended output format

```
Spend by <field name> — from <date> to <date>
Company total: X EUR — allocated on this field: Y EUR (Z%) — unallocated: W EUR

| <Field> | Amount | Share | Of which outstanding | Highest month |
```

Amounts are in functional currency, including VAT, on the document date (not the accounting date). The MCP does not read budgets: for a variance against budget by project, the user supplies the figures.

## Example user prompts

- "What is the spend by region over the last 12 months, month by month?"
- "How much did we spend on the Tech project this quarter, and what share is not tied to any project?"
- "Compare spend by project between Q2 and Q3"