simulator-charts

---
name: simulator-charts
description: >
  Simulator.Company chart and dashboard specialist. Use when the user wants to
  create, configure, or query charts (line, bar, area), dashboards, or financial
  time-series visualisations on a graph layer.

  Trigger on any of these intents:
  — Creating: "create chart", "add chart", "create dashboard", "add dashboard",
    "build visualisation", "chart на графе", "график с данными", "дашборд",
    "show metrics on graph", "visualise account data", "plot actor balances".
  — Configuring: "change chart type", "switch to bar chart", "update chart range",
    "use last day", "show turnover", "change time range", "filter chart actors".
  — Querying: "get chart data", "show dashboard", "what charts are on this layer",
    "fetch chart metrics", "dashboard data".
---

> **Curated tool names (v2 server).** Call tools by the exact names listed under "Curated tool set" in `/simulator`; a few examples below may still show older names.

# Simulator.Company Chart Builder

You are a specialist in creating financial chart dashboards on Simulator.Company
graph layers using the `simulator` MCP server.

---

## Core Concepts

| Term               | Description                                                                               |
|--------------------|-------------------------------------------------------------------------------------------|
| **Dashboard actor** | An actor with `formName="Dashboards"` — renders a time-series chart on the layer.         |
| **ActorFilters actor** | An actor with `formName="ActorFilters"` — filters source actors by form/account/currency. |
| **actorFilter mode** | Chart data comes dynamically from the top-N actors matched by the filter.                 |
| **direct accounts mode** | Chart data comes from an explicit list of actor+account pairs.                       |
| **laId**           | Layer Actor ID returned when a dashboard is placed on a layer (needed for settings).      |

---

## Primary Tool — `createChart`

One call creates the full chart pipeline:
1. Creates an `ActorFilters` actor (or reuses an existing one).
2. Creates a `Dashboards` actor with the chart config.
3. Places the dashboard on the layer at the given position.
4. Sets account inheritance so the chart can read financial data.
5. Sets `expandType=chart` so the node renders as a chart widget.

Returns: `{ dashboardActorId, filterActorId, laId }`

---

## Mode 1 — actorFilter (dynamic source)

Use when you want the chart to automatically show the **top-N** actors from a
given form, ranked by their account balance.

```
createChart(
  layerId       = "<layerUUID>",        // required
  title         = "MCP API Calls",      // required
  description   = "Requests per tool",  // optional
  chartType     = "line",               // "line" | "bar" | "area" (default "line")
  counterType   = "amount",             // "amount" | "turnover" (default "amount")
  range         = "lastHour",           // "lastHour" | "lastDay" | "lastWeek" | "lastMonth"
  sourceFormId  = 580365,               // numeric formId of the source actors
  accountNameId = "b37efbf5-...",       // UUID of the account name
  currencyId    = 68933782,             // numeric currency ID
  top           = 20,                   // number of top actors to show (default 20)
  positionX     = -100,                 // x on layer (default -100)
  positionY     = 0                     // y on layer (default 0)
)
```

**Reuse an existing ActorFilters actor:**

```
createChart(
  layerId       = "<layerUUID>",
  title         = "My Chart",
  filterActorId = "<existingFilterUUID>",   // skip filter creation
  // sourceFormId / accountNameId / currencyId auto-extracted from the filter actor
  chartType     = "bar"
)
```

---

## Mode 2 — direct accounts (explicit series)

Use when you want to chart **specific actors** instead of the top-N.
Provide the `accounts` array — each item is one chart series.

```
createChart(
  layerId     = "<layerUUID>",
  title       = "Key Actors",
  chartType   = "bar",
  accounts    = [
    { actorId: "<uuid1>", currencyId: 68933782, nameId: "<nameUUID>", color: "#499894", incomeType: "total" },
    { actorId: "<uuid2>", currencyId: 68933782, nameId: "<nameUUID>", color: "#59A14F" },
    { actorId: "<uuid3>", currencyId: 68933782, nameId: "<nameUUID>" }
  ]
)
```

`color` and `incomeType` are optional per item; defaults are auto-assigned from
the Tableau palette and `"total"` respectively.

---

## Before Calling `createChart` — What You Need

### actorFilter mode prerequisites

1. **`layerId`** — the layer where the chart will appear. Use an existing layer
   or create one with `createActor(formName="Layers")`.

2. **`sourceFormId`** — the numeric formId of the actors you want to chart.
   Find it via `getForms()` or `getForm(formId=...)`.

3. **`accountNameId`** — UUID of the account name (e.g. "Requests", "Balance").
   Find it via `getAccountNames()`.

4. **`currencyId`** — numeric ID of the currency (e.g. "USD", "Requests").
   Find it via `getCurrencies()`.

### direct accounts mode prerequisites

1. **`layerId`** — same as above.
2. **`accounts`** array — each `actorId` must already exist; `nameId` and
   `currencyId` must correspond to accounts that actors actually have.

---

## Lookup Helpers

```
// Find formId for your source form
getForms()                          // list all user forms
getForm(formId="<formId>")          // get form details with fields

// Find accountNameId
getAccountNames()                   // list all account names in the workspace

// Find currencyId
getCurrencies()                     // list all currencies in the workspace

// Find layerId (if you have graph actor)
getLinkedActors(actorId="<graphId>") // find child Layers actor
```

---

## Complete Example: Build a Chart on an Existing Layer

```
// 1. Find required IDs
getAccountNames()  → locate "MCP API Calls" → nameId = "b37efbf5-..."
getCurrencies()    → locate "Requests"       → currencyId = 68933782

// 2. Create chart
createChart(
  layerId       = "01c447c3-9d15-4dda-9fd7-086b481c0465",
  title         = "MCP API Calls",
  description   = "Top tools by request count",
  chartType     = "line",
  range         = "lastHour",
  sourceFormId  = 580365,
  accountNameId = "b37efbf5-1b4876-9021-47639da2e093",
  currencyId    = 68933782,
  top           = 20,
  positionX     = -100,
  positionY     = 0
)
→ { dashboardActorId: "a643c9f1-...", filterActorId: "03f00f83-...", laId: 51944801 }
```

The chart appears immediately on the layer as a widget node.

---

## Parameter Reference

| Parameter       | Required | Default      | Description                                                  |
|-----------------|----------|--------------|--------------------------------------------------------------|
| `layerId`       | ✓        | —            | Layer actor UUID                                             |
| `title`         | ✓        | —            | Chart title                                                  |
| `description`   |          | `""`         | Chart description                                            |
| `chartType`     |          | `"line"`     | `"line"` \| `"bar"` \| `"area"`                              |
| `counterType`   |          | `"amount"`   | `"amount"` \| `"turnover"`                                   |
| `range`         |          | `"lastHour"` | `"lastHour"` \| `"lastDay"` \| `"lastWeek"` \| `"lastMonth"` |
| `positionX`     |          | `-100`       | X position on canvas                                         |
| `positionY`     |          | `0`          | Y position on canvas                                         |
| `filterActorId` |          | —            | Reuse existing ActorFilters actor                            |
| `filterTitle`   |          | = `title`    | Title for the new ActorFilters actor                         |
| `sourceFormId`  | *        | —            | Numeric formId of source actors (*required in actorFilter mode without `filterActorId`) |
| `accountNameId` | *        | —            | UUID of the account name (*same)                             |
| `currencyId`    | *        | —            | Numeric currency ID (*same)                                  |
| `top`           |          | `20`         | Top-N actors to show (actorFilter mode)                      |
| `accounts`      |          | —            | Explicit series array (direct accounts mode)                 |

---

## Key Rules

- **`createChart` is the only tool needed** — it handles filter creation, placement, inheritance, and expand-type in one call.
- **actorFilter mode** is the default when `accounts` is not provided. Needs `sourceFormId` + `accountNameId` + `currencyId` (unless reusing `filterActorId`).
- **direct accounts mode** activates automatically when `accounts` array is provided.
- If `filterActorId` is provided, the tool fetches the existing filter actor's data automatically — no need to re-specify `sourceFormId` / `accountNameId` / `currencyId`.
- Chart nodes appear as expanded widgets on the layer (`expandType=chart`).
- Reuse `filterActorId` to share a filter across multiple charts — avoids duplicating `ActorFilters` actors.