carta-compensation-benchmarks

Benchmark Query

Look up Carta Total Compensation (CTC) market salary and equity benchmarks for a role at a specific corporation.

CRITICAL — Casing rule for ALL user-facing CTC values.

In every part of your response that the user reads — chat narration, status updates, table headers, table cells, chart titles, CSV column values, file summaries, follow-up suggestions — render CTC taxonomy values in Title Case display form, never the UPPER_SNAKE_CASE API enums. This matches the carta-compensation-rolematcher output convention so the plugin's voice is consistent.

Field	Use in user-facing text	Never
Job area	Engineering, Sales, Customer Success, Project Management, Human Resources	ENGINEER, SALES, CUSTOMER_SUCCESS, PROJECT_MANAGEMENT, HR
Focus	DevOps and Site Reliability, Account Executive, FP&A	devops and site reliability, account executive, fp&a
Level	Entry, Mid 1, Senior 1, Staff 2, VP 1, C-Level, CEO, Unknown	ENTRY, MID1, SENIOR1, STAFF2, VP1, C_LEVEL, UNKNOWN
Track	IC, Manager, Executive, Unknown	ic, manager, executive, UNKNOWN

The UPPER_SNAKE_CASE enums are only for machine handoff — i.e. the job, level, focus, is_leader parameters you pass to compensation:get:benchmark. Inside the JSON payload for the API call, keep the enum form. Outside the API call, switch to Title Case before any value reaches the user. Even in narration like "Engineering maps to ENGINEER", drop the API enum — say "Pulling Engineering benchmarks for corp 7" instead.

See carta-compensation-rolematcher → "Display → API enum tables" for the full mapping.

Use MCP, not CLI. Every API call in this skill goes through the carta MCP server's mcp__carta__call_tool tool, with compensation:* commands. Do NOT shell out to the carta CLI (carta compensation ..., carta web ..., etc.) — that bypasses the formatters, the 403 handler, and the attribution requirement. The Bash tool is allowed only for writing CSV/JSON files locally, never for calling Carta APIs.

Examples below use shorthand call_tool({"name": "compensation__get__plan", "arguments": {...}}) — read this as mcp__carta__call_tool({"name": "compensation__get__plan", "arguments": {...}}).

CRITICAL — Show only PERCENTILE columns (p25/p50/p75/p90) for all three rating types.

The compensation:get:benchmark response includes both low/mid/high bands AND p25/p50/p75/p90 percentiles. Surface only the percentiles — they are the raw market data. Skip the band fields entirely (they're a derived corp-specific target band that adds noise without adding information for benchmark queries).

Every output (chat reply, CSV, JSON) MUST include all three rating types: salary, equity, AND total cash. Don't stop at salary.

Cowork vs everywhere else — pick ONE chat surface, not both

Where the benchmark numbers actually appear depends on the client:

Client	Chat reply	Live artifact panel
Artifact callable	One-line acknowledgement + the data-source attribution line. NO markdown percentile tables.	✅ Renders the percentile tables
Claude Code, Claude Desktop, claude.ai	✅ Renders the markdown tables (the "Chat reply format" below) + the attribution line	Not available — skip the artifact path

Anti-patterns:

• ❌ In Cowork, rendering the markdown percentile tables AND the artifact panel — the data appears twice, the chat reply is noise.
• ❌ In Claude Code / Desktop / claude.ai, skipping the markdown tables on the assumption an artifact will pick up the slack — the artifact doesn't render there, so the user gets nothing.

The Excel / CSV export paths are unchanged — both clients can request a file export and it works the same way regardless.

Chat reply format (single role) — Claude Code / Desktop / claude.ai only

Skip this entire section when running in Cowork — the artifact panel renders the same percentile data and a markdown duplicate is noise. Use the one-line acknowledgement format from the "Live artifact" section below instead.

Three small tables, one per rating type. Each has 4 columns: P25, P50, P75, P90.

## Market Benchmark: [Role] at [Company]

**Salary**
| P25 | P50 | P75 | P90 |
|-----|-----|-----|-----|
| $145,000 | $164,000 | $186,000 | $210,000 |

**Total Cash Compensation (TCC)**
| P25 | P50 | P75 | P90 |
|-----|-----|-----|-----|
| $164,000 | $185,000 | $210,000 | $237,000 |

**Equity (4-Year Grant)**
| Metric | P25 | P50 | P75 | P90 |
|--------|-----|-----|-----|-----|
| FD % | 0.030% | 0.040% | 0.050% | 0.144% |
| Shares | 18,620 | 24,745 | 30,870 | 88,444 |
| Notional value | $100,000 | $133,000 | $165,000 | $474,000 |

(For peer groups ≥ $500M post money — `peer_group.notional_available: true` — put **Notional value** as the first row instead.)

**Geo Adjustment:** [location] (X.XX× salary, X.XX× equity)

---
*Data source: Companies with [peer_group_dimension_phrase] [peer_group_label]. Benchmarks released [Month YYYY].*

The [peer_group_dimension_phrase] varies by peer_group.dimension — see "Required attribution" below for the three exact phrasings. Do NOT hardcode post money valuations between.

CSV format (bulk)

One row per (job, ladder, level). Default column order (peer group < $500M post money):

job, ladder, level, currency,
salary_p25, salary_p50, salary_p75, salary_p90,
tcc_p25, tcc_p50, tcc_p75, tcc_p90,
equity_fd_pct_p25, equity_fd_pct_p50, equity_fd_pct_p75, equity_fd_pct_p90,
equity_shares_p25, equity_shares_p50, equity_shares_p75, equity_shares_p90,
equity_notional_p25, equity_notional_p50, equity_notional_p75, equity_notional_p90

For peer groups ≥ $500M post money (peer_group.notional_available: true), notional comes first:

..., equity_notional_p25..p90, equity_fd_pct_p25..p90, equity_shares_p25..p90

Field source map (from each benchmarks[i] entry):

• salary_p* → salary_benchmarks.percentiles.{p25,p50,p75,p90}
• tcc_p* → tcc_benchmarks.percentiles.{p25,p50,p75,p90}
• equity_shares_p* → equity_benchmarks.percentiles.{p25,p50,p75,p90}.as_shares
• equity_fd_pct_p* → equity_benchmarks.percentiles.{p25,p50,p75,p90}.as_fd_percentage
• equity_notional_p* → equity_benchmarks.percentiles.{p25,p50,p75,p90}.as_notional_value
• currency → salary_benchmarks.currency_code

Note: equity percentiles are nested objects (percentiles.p25.as_shares, etc.), not flat values like salary/tcc.

If a column's source field is missing for a particular row (e.g. some roles have no equity), leave that cell blank — do not invent zeros and do not drop the column.

Anti-patterns:

• ❌ Showing the user a low/mid/high table. Those are the corp's pay-band target, not market data — skip them.
• ❌ CSV with salary_low / salary_mid / salary_high columns instead of percentile columns.
• ❌ Salary-only output. The user asked for "benchmarks" — show all three rating types.
• ❌ Skipping TCC because "the user said sales benchmarks" — TCC IS a benchmark.