Wallet balance and card allocations

# Instructions — Wallet balance and card allocations

## ⚠️ Inconsistent format: list_cards.availableBalance.amount

All MCP tools use the `{ amount: int, precision }` convention where value = `amount / 10^precision`.

**Exception: `list_cards`** — the `availableBalance.amount` field returns the decimal value directly:
```json
// list_cards — value ALREADY in EUR:
"availableBalance": { "amount": 91.38, "currency": "EUR", "precision": 2 }
→ balance = EUR 91.38 (DO NOT divide by 100)

// get_wallet_summary — standard integer coefficient:
"totalAmount": { "amount": 33224769, "currency": "EUR", "precision": 2 }
→ balance = 33,224,769 / 100 = EUR 332,247.69
```

→ For card balances, use `availableBalance.amount` directly (no division).

## ⚠️ Available wallet balance can be negative

`totalAvailableAmount` can be **negative** on demo accounts or in the event of scheduled transfers exceeding the balance. This is a valid state — interpret it as "allocations exceed the current balance."

## ⚠️ allocatedOnCards ≠ sum of availableBalance of active cards

These two metrics measure different things:
- `allocatedOnCards.totalAllocatedAmount` = amount reserved in the wallet for cards (reserved spending limits)
- `sum(card.availableBalance)` = remaining amount cardholders can still spend

The difference = amount already spent on the cards. This is **not** an inconsistency — it is expected.

## Step 1 — Wallet snapshot (get_wallet_summary)

```json
{ "companyId": "..." }
```

Key fields (all in functional currency):
- `totalAmount` → gross wallet balance (integer coefficient)
- `totalAvailableAmount` → available after all allocations (can be negative)
- `totalAllocatedAmount` = `allocatedOnCards.totalAllocatedAmount` + `scheduledTransfersAmount.totalScheduledTransferAmount`
- `allocatedOnCards.subscriptionAmount` → reserved on subscription cards
- `allocatedOnCards.physicalAmount` → reserved on physical cards
- `allocatedOnCards.singlePurchaseAmount` → reserved on single-purchase cards
- `scheduledTransfersAmount.scheduledInvoicesAmount` → scheduled supplier transfers

## Step 2 — Active cards (list_cards)

```json
{ "companyId": "...", "status": "ACT", "pageSize": 100 }
```

For each active card:
- `availableBalance.amount` → available balance IN EUROS DIRECTLY (no formula)
- `spendingLimit` → spending limit (can be null for subscriptions without a fixed limit)
- `type`: subscription | physical | single_purchase | multi_use
- `currency` → card currency (may differ from the functional currency)

⚠️ Do not sum cards in different currencies.

## Step 3 — Interpreting the results

Present as follows:

```
SPENDESK Wallet (EUR) as of 2026-07-06:
  Total balance      : EUR 332,247.69
  Available          : EUR -511,590.51  ⚠️ (allocations > balance)
  Allocated to cards  : EUR 491,808.95
    of which subscription : EUR 402,288.42
    of which physical     : EUR 28,872.30
    of which single-use   : EUR 4,601.63
  Scheduled transfers : EUR 352,029.25

Active cards (ACT): 2 cards
  Subscription #7071: EUR 91.38 available
  Subscription #5947: EUR 9.49 available
```

## Live example (real data)

| Metric | Value |
|----------|--------|
| Total balance | EUR 332,247.69 |
| Available | **EUR -511,590.51** (negative — test) |
| Allocated to cards | EUR 491,808.95 |
| Scheduled transfers | EUR 352,029.25 |
| Active cards | 2 (subscriptions only, ~EUR 101 available) |

## Example prompt

- "What is the wallet status?" → get_wallet_summary only
- "How much is left on active cards?" → list_cards status=ACT + sum availableBalance
- "Are there any pending scheduled transfers?" → wallet_summary.scheduledTransfersAmount