carta-grant-vesting

What this skill does

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

# Grant Vesting Data

Fetch the full vesting schedule for a grant — options, RSUs, SARs, or CBUs — and present it with useful context, not just the raw table.

## When to Use

Use this skill for vesting questions scoped to a **single grant or holder**:

- "What's the vesting schedule for this grant?"
- "When does the cliff hit?" / "When does Jane's cliff hit?"
- "How much has Jane vested?" / "How many shares are vested so far for Jane?"
- "Show vesting progress for Jane" / "How far along is Jane's grant?"
- "How many shares have vested so far?"
- "Show vesting progress for Jane's options"
- "Show the vesting schedule for Jane's RSU grant"
- "How many shares are eligible for settlement?"
- "How many unvested shares remain?"
- "When is this grant fully vested?"

**Wrong-vocab synonyms** (same intent, different words — all map to vesting for a single grant/holder):

- "What's Jane's stock payment schedule?" → vesting schedule
- "When does Jane actually own her stock?" / "When does this grant actually own out?" → vesting / when vested
- "How many shares does Jane have rights to so far?" → vested shares
- "How much of Jane's grant is still locked up?" → unvested shares

**Do NOT use for portfolio-level / all-employees aggregate vesting.** These triggers stay scoped to one grant or holder ("for [name]", "for this grant", "for grant #"). Questions like "how much of my employees' equity has vested" or "total vested across the whole option pool" are portfolio-level — defer to a stakeholder/portfolio/ownership skill instead. If a request spans more than one grant, see the "Multiple grants" branch under Workflow before fetching anything.

## Prerequisites

You need:
1. `corporation_id` — get from `list_accounts` if you don't have it
2. `grant_id` — identify via the list command for the relevant grant type (see below)
3. **Grant type** — required to pick the right list and detail commands. If unstated, infer from the user's wording ("options", "ISO", "NSO" → options; "RSU"; "SAR"; "CBU"). If still unclear, ask via `AskUserQuestion` before searching.

## Data Retrieval

> The gateway defaults to `detail=summary` for list commands. This skill needs individual records, so `"detail": "minimal"` is passed explicitly.

Two endpoints exist for vesting detail and they are **not interchangeable**:

| Grant type | List command | Vesting detail command |
|------------|--------------|------------------------|
| Options (ISO/NSO) | `cap_table:list:grants` | `cap_table:get:grant_vesting` |
| RSUs | `cap_table:list:rsus` | `cap_table:get:rsu_vesting` |
| SARs | `cap_table:list:sars` | *(none — see Caveats)* |
| CBUs | `cap_table:list:cbus` | *(none — see Caveats)* |

**Important:** `cap_table:get:grant_vesting` is options-only and returns 500 for RSU/SAR/CBU ids. Use the table above; do not reuse a command across types.

```
call_tool({"name": "<list tool>", "arguments": {"corporation_id": corporation_id, "search": "<holder name>", "detail": "minimal"}})
```

Then, for options or RSUs:

```
call_tool({"name": "<vesting detail tool>", "arguments": {"corporation_id": corporation_id, "grant_id": grant_id}})
```

For SARs and CBUs, the list-record `vested_shares_quantity` is the only available signal — there is no per-event detail endpoint yet.

## Key Fields

The vesting detail commands return slightly different shapes:

**`cap_table:get:grant_vesting` (options):**
- `total_shares`, `vested_shares`, `unvested_shares`
- `grant_date`, `cliff_summary`
- `vesting_events[]` — each with `date`, `amount`, `cumulative`, `has_vested`

**`cap_table:get:rsu_vesting` (RSUs):**
- `awarded`, `vested_shares`, `unvested_shares`, `settled`, `eligible_for_settlement`
- `vesting_start_date`, `vesting_type`, `primary_vesting_title`/`description`
- `has_additional_condition`, `additional_vesting_title`/`description`
- `acceleration_terms`, `termination_date`
- `tranches[]` — each with `vest_date`, `awarded`, `eligible_for_settlement`, `settled`, `status`, `vesting_status`, `milestone_name`, `additional_condition_*`, `vesting_type`

## Workflow

### Step 0 — Resolve the Corporation First

`cap_table:list:grants` (and the other list commands) require a real `corporation_id`. **Never pass a company name** (e.g. `"meetly"`) as `corporation_id` — it is not an ID and the call will fail.

If you only have a company name, resolve it to a `corporation_id` before any list/data call:

```
list_accounts({"search": "<company name>"})   # narrow to the matching account(s)
# Each account's `id` is shaped `corporation_pk:<numeric id>`. Extract that numeric
# id — it is the `corporation_id` every cap_table tool needs.
# If several accounts share a similar name, call AskUserQuestion to disambiguate
# before continuing — never guess which one the user meant.
set_context({...})     # set the active corporation context, if applicable
```

Calling `list_accounts` with no `search` returns the full account list; on a multi-company instance that risks matching the wrong account, so always pass the name. Carry the resolved `corporation_id` into every subsequent `cap_table__*` call. Only once it is resolved do you proceed to Step 1.

### Step 1 — Identify the Grant

**If `grant_id` is already known** from prior conversation context (e.g. the user just viewed a grants list), skip directly to Step 2.

Otherwise, pick the list command based on grant type and search:

- **Type stated by the user** (e.g. "Jane's RSU", "the SAR"): use the matching list command from the table above.
- **Type unknown**: try `cap_table:list:grants` first (options are most common). If the holder is not found, try `list:rsus`, then `list:sars`, then `list:cbus`. Do not conclude vesting data is unavailable until all four have been checked.

```
call_tool({"name": "<list tool>", "arguments": {"corporation_id": corporation_id, "search": "<holder name>", "detail": "minimal"}})
```

If multiple grants are returned, ask the user which one, or pick the most relevant based on context.

#### Branch — "All grants" / multiple grants

If the user asks about **"all grants"**, **"each grant"**, multiple grants, or every grant for a holder, **do NOT fan out to one `cap_table:get:grant_vesting` (or `rsu_vesting`) call per grant.** A holder or company can have dozens-to-hundreds of grants, and N detail fetches is slow and wasteful. Instead:

1. List the grants once (the summary list already includes `vested`/`unvested`/`quantity` signals) and present that summary table.
2. Either **ask the user to narrow** to a specific grant before pulling the full vesting detail, or **present the summary totals** (per grant, never summing across currencies) and **offer to drill into** a single grant's event-level schedule.

Only fetch the per-grant vesting detail (Step 2) once the user has narrowed to a specific grant.

### Step 2 — Fetch Vesting Data

Pick the detail command based on grant type:

- **Options (ISO/NSO)** → `call_tool({"name": "cap_table__get__grant_vesting", "arguments": {"corporation_id": ..., "grant_id": ...}})`
- **RSUs** → `call_tool({"name": "cap_table__get__rsu_vesting", "arguments": {"corporation_id": ..., "grant_id": ...}})`
- **SARs / CBUs** → no detail endpoint; use the list record's `vested_shares_quantity` and `quantity` fields and surface what's available.

### Step 3 — Present with Context

Lead with a one-sentence plain-English summary before showing the table (see Presentation section).

## Gates

**Required inputs**: `corporation_id`, `grant_id`, and grant type (options, RSU, SAR, or CBU).
If you only have a company name, resolve it to a `corporation_id` first (Step 0) — never pass a name string as `corporation_id`.
If grant type is missing or ambiguous, call `AskUserQuestion` before proceeding (see carta-interaction-reference §4.1).
If `grant_id` is unknown, use Step 1 of the Workflow to search by holder name.

**AI computation**: No — this skill presents Carta data directly.

## Presentation

**