<!-- carta:plugin-version --> <carta-plugin>carta-cap-table:6.93.3</carta-plugin>

<!-- Part of the official Carta AI Agent Plugin -->

Waterfall Scenarios

Fetch saved exit scenario models and present them with meaningful context, not just the per-holder table.

Prerequisites

You need the corporation_id. Get it from list_accounts if you don't have it.

Data Retrieval

call_tool({"name": "cap_table__get__waterfall_scenarios", "arguments": {"corporation_id": corporation_id}})

One call returns every saved (non-draft) scenario. This is the only waterfall tool this skill uses — do not call fetch, waterfall_modeling__*, or any other tool to fill in what this one leaves out. Those serve investor-firm valuations, not a company's saved scenarios.

Response Shape

{
  "scenarios": [
    {
      "id": 12,
      "name": "Acquisition at $50M",
      "exit_value": "50000000.00",
      "exit_date": "2026-12-31",
      "status": "DONE",
      "holders": [
        {
          "organization_name": "Lead Investor",
          "cost_of_holdings": "5000000.00",
          "value_of_holdings": "18200000.00",
          "outstanding_shares": "3000000",
          "return_multiple": "3.64",
          "irr": "0.41"
        }
      ]
    }
  ],
  "holders_unavailable": "Per-holder payout breakdown is not available from this command for a company-owned scenario…"
}

Scenario fields: id, name, exit_value, exit_date, status.

Holder fields (inside holders[], sorted by payout, largest first):

• organization_name: the holder
• cost_of_holdings: what the holder paid
• value_of_holdings: what the holder receives at this exit
• outstanding_shares: shares held
• return_multiple: payout / cost (< 1.0x = loss)
• irr: internal rate of return

Amounts arrive as strings; cast before comparing or charting.

Workflow

Step 1 — Fetch Scenarios

Call cap_table__get__waterfall_scenarios once with the corporation ID.

Step 2 — Read Each Scenario by Its State

A scenario's content depends on its status and whether it has holders. Handle each one on its own terms:

What the scenario carries	What to present
status: "DONE" with holders	The full framing in Step 3, per-holder table, and bar chart.
status: "DONE" without holders, and the response carries holders_unavailable	The scenario is owned by the company, and this tool can't return its per-holder split. Report its name, exit value, and exit date. Say the per-holder breakdown isn't available here, and point the user to the scenario's Exit modeling page in Carta. Never describe holders as absent or payouts as zero.
status: "PREPARING" or "IN_PROGRESS"	Carta is still computing it. Report the name and exit value and say results appear once the run finishes.
status: "ERROR"	The model run failed in Carta. Report the name and suggest re-running it from Exit modeling.

If the response has message: "No saved waterfall scenarios found.", tell the user the company has no saved exit scenarios and offer the custom-exit guidance below.

Step 3 — Frame Each Completed Scenario

Don't just show the table — frame each scenario that has holders:

• Lead with the exit value and what it means: who gets paid out, at what multiple, and whether any holders are underwater
• Highlight the biggest winners and losers by return multiple — a 1.0x return means a holder barely breaks even; anything below that means a loss
• If there are multiple scenarios, compare them: how do payouts shift as exit value changes? At what exit value does the common stack start to see meaningful returns?
• Note liquidation preference effects: if preferred holders take a large share at lower exit values, say so plainly

Step 4 — Flag Notable Items

• Any holder with return multiple < 1.0x (loss scenario)
• Large gap between pref payout and common payout at a given exit value
• Scenarios that are very close in exit value but have very different common distributions

Gates

Required inputs: corporation_id. If missing, call AskUserQuestion before proceeding (see carta-interaction-reference §4.1).

AI computation: No — this skill presents Carta data directly. Framing and comparison are presentational, not modeled.

Presentation

Format: Per-holder table + ASCII bar chart for each scenario with holders; a one-line status for every other scenario.

BLUF lead: Lead with the exit value and a one-sentence summary of who benefits most and whether any holders are underwater. If no scenario has holders, lead with what is available (scenario names and exit values) and why the split isn't shown.

Sort order: By value_of_holdings descending (the order the tool returns).

Per-holder table columns: Holder, Cost Basis (cost_of_holdings), Payout (value_of_holdings), Return Multiple (return_multiple).

After the per-holder table, render an ASCII bar chart of payout by holder. Scale bars to max width 40 chars:

Payout Distribution — $50M Exit

Lead Investor      ████████████████████████████████████████ $18.2M  3.6x
Founder            ████████████████████                     $9.1M   1.8x
Common Holders     ██████████                               $4.5M   0.9x

Each bar width = (value_of_holdings / max value_of_holdings) * 40. Show return multiple after the dollar amount.

Error Handling

Situation	What to do
403 / access denied	Exit modeling isn't enabled for this company (a product entitlement, not a problem with the user's permissions). Say: "Exit modeling isn't enabled for this company in Carta, so there are no saved waterfall scenarios to show." Do not retry, and do not try other tools.
"Unknown tool"	Use the exact name cap_table__get__waterfall_scenarios through call_tool and retry once. Do not guess name variations.
Network/transport error	One retry. If it fails again, tell the user Carta couldn't be reached and to try again shortly.

Custom Exit Values

If the user asks to model a specific exit value not in the saved scenarios:

"There's no saved model at that exit value. To model a custom exit, create a new scenario in Carta's scenario modeling tool, then come back and I'll pull it up."

Caveats

• Waterfall models are read-only snapshots saved in Carta; this skill cannot create or modify scenarios.
• Return multiples are based on the scenario's modeled exit value, not a live valuation.
• Liquidation preference mechanics (participating vs. non-participating, caps) are baked into Carta's model — this skill does not re-derive them.
• Custom exit values cannot be modeled on the fly; they must be created in Carta first.