---
name: s41-multi-entity-org-token
scenario: S41
description: Utiliser list_companies et les tools multi-entités — gestion du token org-level vs company-scoped et du champ name=null
tags: [multi-entity, list-companies, org-token, company-scoped, gotcha]
when_to_use: Quand on opère avec un token org-level donnant accès à plusieurs entités juridiques, ou quand companyId est requis sur les tools
risk: P1 — Avec un token company-scoped, list_companies retourne uniquement l'id (name=null). Un skill qui affiche company.name plantera silencieusement (affichage "null").
---

# Instructions — Multi-entités et gestion du token

## ⚠️ Comportement de list_companies selon le type de token

| Token type | Nb entités | id | name |
|------------|-----------|-----|------|
| **org-level** | Toutes les entités actives | ✅ présent | ✅ présent |
| **company-scoped** | 1 seule entité | ✅ présent | **❌ null** |

Si `company.name=null` : ne pas afficher "null" — indiquer "entité courante" ou utiliser l'id.

## Étape 1 — Lister les entités disponibles

Appelle `list_companies` (sans paramètre).

**Avec token org-level** : retourne toutes les entités actives avec id + name.
**Avec token company-scoped** : retourne 1 entité avec id uniquement.

Inspecte la réponse :
- Si 1 entité et `name=null` → token company-scoped → continuer avec cet id
- Si plusieurs entités avec name → token org-level → sélectionner selon le besoin

## Étape 2 — Sélectionner la ou les entités cibles

**Pour une analyse mono-entité** : choisir l'entité par nom ou par devise selon le besoin.

**Pour une analyse consolidée multi-entités** :
- Itérer sur chaque companyId
- Appeler le tool souhaité pour chaque entité
- Combiner les résultats **après avoir tous les résultats** (ne pas présenter partiel)

⚠️ Les devises fonctionnelles varient par entité — **ne jamais sommer cross-devises**.
Utiliser `functionalAmount` propre à chaque entité et les afficher séparément ou convertir explicitement.

## Étape 3 — Données disponibles (exemple réel token org-level)

11 entités sur ce compte, dont :
```
B1stUp83     → SPENDESK (EUR)
Hx1N5m87M   → Spendesk Limited (GBP)
pD0gYhOK75T → Spendesk Inc. (USD)
RRbRgeIB7X  → Spendesk GmbH (EUR)
vvdk2xwqvktsjl → Spendesk USD Test (USD)
```

## Étape 4 — Analyse consolidée multi-entités (pattern)

```
Pour chaque companyId dans list_companies.data :
  1. Appeler spendesk_analyze_spend(companyId, fromDate, toDate, groupBy)
  2. Extraire summary.totalAmount (devise fonctionnelle de l'entité)
  3. Stocker résultat + devise

Afficher :
  Entité A : X EUR (N payables)
  Entité B : Y GBP (N payables)
  Entité C : Z USD (N payables)
  ⚠️ Total consolidé en EUR = conversion nécessaire (non fournie par le MCP)
```

## Cas edge : token company-scoped avec companyId déjà connu

Si le token est company-scoped, les tools acceptent `companyId` optionnel (auto-rempli).
Passer explicitement le companyId est inutile mais inoffensif — le token n'accède qu'à son entité de toute façon.

## Exemple de prompt

- "Montre les dépenses de chaque entité du groupe" → itérer sur list_companies + analyze_spend
- "Quel est le wallet de toutes nos filiales ?" → itérer sur list_companies + get_wallet_summary
- "Compare les dépenses France vs UK" → 2 appels analyze_spend sur B1stUp83 et Hx1N5m87M