carta-compensation-scorecard

CTC Scorecard

Show how a corporation's compensation stacks up against market — at the corp level (band distribution rollup) or at the employee level (per-employee compa-ratio table) — using Carta Total Compensation data.

This skill calls compensation-service's scorecard endpoints (the same endpoints the CTC in-product UI uses) and renders the result in chat. By construction, the output matches what the customer sees in their CTC product surface.

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

Render CTC taxonomy values in Title Case display form, never the UPPER_SNAKE_CASE API enums. Matches the carta-compensation-rolematcher and carta-compensation-benchmarks convention so the plugin's voice is consistent across skills.

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
Band	Low, Mid, High	low, mid, high

The UPPER_SNAKE_CASE enums are only for machine handoff to MCP commands (the job_filters, leader parameters). Switch to Title Case before any value reaches the user.

Band enum — the API uses LOW / MID / HIGH, NOT BELOW_MARKET / AT_MARKET / ABOVE_MARKET. This is the single source of truth:

API value (filter + response)	Display	Maps to user phrasing
LOW	Low	"below market", "below P50"
MID	Mid	"at market"
HIGH	High	"above market", "above P50"

Pass LOW / MID / HIGH (not BELOW_MARKET) as the score filter value, and parse LOW / MID / HIGH from response score fields. Display the actual band value (Low / Mid / High) in tables — do not relabel it to "Below market". When the user asked for a band by market phrasing (e.g. "show me below-market employees"), echo their phrasing in the surrounding prose AND map it to the real enum, e.g. "Here are your below-market (Low) employees:" — but the per-row Band column still shows Low.

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. Do not shell out to the carta CLI — that bypasses the formatters, the 403 handler, and the attribution requirement.

⚠️ Two different invocation paths in this skill — do not conflate them.

Command	Invoke with	Why
subscription_status, plan	mcp__carta__call_tool({"name": "compensation__get__…", "arguments": {…}})	Registered as flat call_tool tools (the plugin-wide convention, same as the benchmarks skill).
employee-scorecard, corporation-scorecard	mcp__carta__fetch({"command": "compensation:get:…", "params": {…}})	Registered only as MCP commands. They are NOT flat call_tool tools — call_tool({"name": "compensation__get__employee_scorecard"}) returns "Unknown tool" and silently wastes calls.

The scorecard commands are the trap: an LLM carrying call_tool muscle memory from the benchmarks skill will call the wrong tool. In this skill, the call_tool(...) shorthand is used ONLY for subscription_status and plan. Every employee-scorecard / corporation-scorecard example below is written out in full as mcp__carta__fetch(...) — invoke it exactly as written, do not "translate" it back to call_tool.

For the fetch commands, note the shapes that trip agents up: the command name is hyphenated/colon (compensation:get:employee-scorecard), the argument key is params (not arguments), and page_size is snake_case.