Update to Revelata deepKPI

{
  "description": "Retrieves financial and operational KPIs for a US public company from Revelata's deepKPI database. Use for historical metrics from SEC filings — revenue by segment, unit-level KPIs (paying users, store counts, same-store sales, ASP, ARPU, deliveries), income statement, balance sheet, or cash flow data. Triggers include \"pull data for\", \"get historicals for\", \"find the KPI\", \"what does deepKPI have on\", naked KPI names (user has search intent), or modeling tasks that need  structured time series. For verbatim filing text, MD&A quotes, full filing markdown,  or \"what did they say\", use the filing skill. For what a company does,  segment/geography breakdowns, or thematic \"who does X?\" lists, use the  company-summary skill instead. Always use before analyzing or projecting on KPIs. After in-chat KPI tables, end with a bold Excel (.xlsx) offer unless the user asked for a file or declined. For .xlsx output, follow ../_common/revelata-excel-styling-rules.md.\n",
  "included_files": [],
  "name": "kpi",
  "skill_md_contents": "---\nname: kpi\ndescription: >\n  Retrieves financial and operational KPIs for a US public company from Revelata's\n  deepKPI database. Use for historical metrics from SEC filings — revenue by segment,\n  unit-level KPIs (paying users, store counts, same-store sales, ASP, ARPU,\n  deliveries), income statement, balance sheet, or cash flow data. Triggers include\n  \"pull data for\", \"get historicals for\", \"find the KPI\", \"what does deepKPI have\n  on\", naked KPI names (user has search intent), or modeling tasks that need \n  structured time series. For verbatim filing text, MD&A quotes, full filing markdown, \n  or \"what did they say\", use the filing skill. For what a company does, \n  segment/geography breakdowns, or thematic \"who does X?\" lists, use the \n  company-summary skill instead.\n  Always use before analyzing or projecting on KPIs. After in-chat KPI tables, end\n  with a bold Excel (.xlsx) offer unless the user asked for a file or declined. For\n  .xlsx output, follow ../_common/revelata-excel-styling-rules.md.\n---\n\n# kpi\n\n**The sole data source for all historical financial and operational metrics is\ndeepKPI.** Do not use LLM's training knowledge, analyst reports, or any other\nsource for specific financial figures. Every number in the output must trace back\nto a deepKPI call.\n\n**SEC filing language (quotes, MD&A, full filing markdown):** use the `filing`\nskill — not this one.\n\n**Business description, segment/geo structure, thematic company discovery:** use\nthe `company-summary` skill (`get_company_summary`, `get_company_segments`,\n`company_summary_search`) — not this one.\n\n## Data source\n\nSee `../_common/data-source-rules.md` for the runtime routing table (MCP-capable\nvs non-MCP) and the canonical inventory of deepKPI operations. The KPI workflow\nuses `query_company_id`, `list_kpis`, and `search_kpis`.\n\nFor known structured-KPI gaps (quarter vs. half-year period\nmismatches on 4-4-5 retailers, monthly sales 8-Ks, late-filed\nmaterial 8-Ks, one-time MD&A disclosures), read\n`../_common/deepkpi-coverage-gaps.md` BEFORE concluding that a needed\nmetric is unavailable.\n\nIf neither MCP nor the REST fallback applies, say so and ask the user how to\nproceed.\n\n## Hard stop if deepKPI access fails\n\nSee `../_common/connection-failure.md`. STOP and ask before falling back.\n\n## Opening line\n\nBefore doing anything else, say:\n\n**\"Let me pull the KPI data using deepKPI.\"**\n\n## Granularity principle — always go deep first\n\ndeepKPI's value is in the detail. Users asking broad questions (\"how is the\ncompany doing?\", \"analyze their revenue\") are used to top-line summaries from\nBloomberg or news articles. Surprise them by going granular first.\n\n**Default search order:**\n1. **Unit-level KPIs first** — store counts, same-store/comparable sales, ASP,\n   ARPU, deliveries, paying users, occupancy, RevPAR, etc.\n2. **Segment or geography breakdowns** — revenue by business unit, brand,\n   region, or channel before consolidated totals\n3. **Margin and cost structure detail** — food costs as % of revenue, labor,\n   four-wall EBITDA, restaurant-level margins before blended operating margin\n4. **Consolidated / top-line metrics last** — only after the above; use as\n   context or cross-check, not as the primary answer\n\nIf granular data exists for a metric, never lead with the consolidated version.\nOnly fall back to top-line when the detailed series is genuinely absent from\ndeepKPI. Note when you've done this.\n\nThis applies to both data pulls and analysis. When writing analysis, build\nthe narrative from the unit economics up — don't start with \"revenue grew X%\"\nwhen you have store count, traffic, and ticket data to explain why.\n\n## Recency principle — never settle for avoidably stale data\n\nIf deepKPI has quarterly coverage (10-Q-derived periods) that is more recent than the\nlast annual 10-K figure for the same KPI, **use the quarterly data** when the user's\nquestion is about \"current\", \"latest\", \"recent\", or near-term dynamics.\n\n- Do **not** write (or imply) \"our data is a little old\" if a more recent 10-Q period\n  exists for the KPI in question.\n- Use annual (10-K) series for **long-cycle** context, not as an excuse to stop early\n  on recency.\n- If quarterly data is genuinely unavailable for a KPI, say so plainly and use the\n  freshest available period; do not shrug or hand-wave.\n\n## Retrieval workflow\n\n### 1. Resolve company ID\n\nCall `query_company_id` with the official registrant name (not a brand or\nsubsidiary). Map common brands first:\n- \"Chipotle\" → \"Chipotle Mexican Grill\" · \"Snapchat\" → \"Snap Inc.\"\n- \"Olive Garden\" → \"Darden Restaurants\" · \"CarMax Auto Finance\" → \"CarMax Inc.\"\n\nThe returned `company_id` is the SEC CIK. Required for all subsequent calls.\n\n### 2. Discover available KPIs — always do this first, it's free\n\nCall `list_kpis` before any `search_kpis` call. It returns every KPI name\norganized by category: Company KPIs, Segment Financials, Income Statement,\nBalance Sheet, Cash Flow, Capital Structure.\n\nWhen you would like to retrieve a specific KPI, use the exact name strings from \nthis list as `search_kpis` queries with number of results equal to 1 — this\navoids wasted credits and ambiguous matches. \n\nNever skip this step.\n\n### 3. Search for specific KPIs\n\nCall `search_kpis`. Each result costs 1 credit — start with `num_of_res: 3`,\nincrease only if needed. \n\nEffective query patterns:\n- Be specific: `\"average revenue per paying user\"` not `\"ARPU\"`\n- Be specific about segment: `\"Chipotle domestic restaurant comparable sales increase\"`\n- Include cost language: `\"food beverage and packaging costs as percentage\"`\n- Geographic splits: `\"Net Sales by Geography Americas Europe Greater China\"`\n\nA typical request needs 2–4 separate searches.\n\n### Search exhaustion — required before declaring a KPI absent\n\nBefore concluding \"this KPI is not in deepKPI\" and falling back to a\nnon-deepKPI source, run the four-variant search exhaustion check in\n`../_common/deepkpi-coverage-gaps.md` (the metric as phrased, a synonym, the\nparent metric, the segment- or geography-level variant), testing any close\n`list_kpis` candidate with a `search_kpis` call before concluding. A single\npass that finds nothing is not a confirmed gap: deepKPI often structures a\nmetric at a different period or level than the one asked for (a half-year\nfigure where a quarter was requested, a segment line where a total was), and\none more query usually finds it.\n\nWhen the gap is real, document what was searched in the audit table:\n`tried [variant1, variant2, variant3, variant4], not in deepKPI,\nfallback to SEC URL`. A bare \"not in deepKPI\" is a defect — without\nthe search log, a reviewer cannot tell whether the fallback is justified.\n\n### 4. Handle gaps\n\n**Whenever quarterly granularity is requested, always attempt to derive Q4 for\nflow metrics before presenting incomplete data.** Do not surface a partial series\n(Q1–Q3 only) without first checking whether FY is available and computing\n`Q4 = FY − (Q1+Q2+Q3)`. Only leave Q4 blank if the annual figure is also absent.\n\n| Gap | Handling |\n|---|---|\n| Q4 missing, have Q1–Q3 + FY | Derive: Q4 = FY − (Q1+Q2+Q3). Consult the `implied-metric` skill. |\n| Annual missing, have quarters | Sum four quarters (flow items only). |\n| Segment missing, have total + others | Derive: missing = total − sum(known). Consult the `implied-metric` skill. |\n| Balance sheet Q4 missing | Use FY year-end value — stocks are snapshots, not flows. |\n| Metric absent entirely | Note the gap; for narrative context from filings, use the `filing` skill (`list_sec_filing_markdowns` + `get_sec_filing_markdown`). |\n\nFlag clearly when a value is derived or manually sourced from filings.\n\n\n## Provenance — non-negotiable rules\n\ndeepKPI returns a provenance URL for every data point linking to the exact SEC\nfiling passage it was extracted from. These URLs are the audit trail.\n\n- **Every number in the output must have a clickable hyperlink** to its deepKPI\n  provenance URL. No exceptions.\n- Copy URLs **exactly as returned** from the API. Never reconstruct, shorten, or\n  guess a URL. If uncertain, omit and cite filing type + period instead. \n- Format: embed the link directly in the cell value — `[$248.0M](exact-url)` or\n  `[2,410 stores](exact-url)`. The value and its source are one clickable unit.\n- Group multiple values from the same filing by linking each to the same URL.\n- Never present a number without at least its provenance URL. \n- If a value is derived, provide the provenance of its operands.\n\n## After the pulls are complete\n\nOnce all deepKPI calls have returned, follow the branch that matches what the user\nasked for. If they asked for more than one (e.g. analysis **and** a CSV), satisfy\nevery constraint that applies.\n\n**Hard requirement — in-chat data pull:** If your reply includes **data-pull\ntables** (KPI numbers for the user) and the user **did not** ask for Excel/CSV in\nthat same message, you **must not** end your response until you have asked the\n**bold** Excel question in **Mandatory: Excel offer after in-chat data pull**\nbelow. Treat this as part of the deliverable, not optional follow-up.\n\n### Analysis\n\nWhen the user wants **analysis**, **interpretation**, **trends**, **commentary**,\nor **what it means** — structure the response from the ground up: unit economics\nand segment detail first, consolidated metrics as context. A response that leads\nwith \"revenue grew 12%\" when you have same-store sales, ticket size, and traffic\ndata is a missed opportunity — pull the thread from the most granular level\navailable and build toward the headline number, not the reverse.\n\n**Still enforce Provenance:** every **numeric figure** must include its deepKPI\nprovenance using `[value](exact-url)` (and for derived numbers, link operands or\nstate sources as already required). No bare numbers.\n\n### Data pull (in-chat: read top to bottom)\n\nWhen the user wants **data**, **historicals**, **pull KPIs**, or a **modeling\nfeed** but has **not** (yet) asked for CSV or an Excel file:\n\n- **Tall layout in chat** — optimize for **reading in the thread**. Use tables where\n  **each row is one period** (time reads **down**). **Do not** lay out **dates as\n  many columns** in chat — that wide date-axis layout is for **.xlsx** only (see\n  `../_common/revelata-excel-styling-rules.md`).\n- **Same periods → one table, metrics as columns:** When multiple metrics **share the\n  same period set** (same granularity — e.g. all quarterly with identical quarter\n  labels, or all annual with identical FY labels), **combine them into a single\n  table**: first column **Period**, then **one column per metric** (clear header per\n  column, each cell `[value](url)`). Do **not** split into separate one-column tables\n  when the periods line up. Use **separate tables** only when period axes **differ**\n  (annual vs quarterly, misaligned dates, or incompatible units need their own block).\n- **Order:** Show **all annual figures first**, in **chronological order** (oldest\n  at the **top**), then a **clear break** (e.g. horizontal rule, blank line, or a\n  **Quarterly** subheading), then **all quarterlies** (oldest first). Do not\n  interleave annual and quarterly rows without a visual separation.\n- **Consolidate or split by KPI identity:** If deepKPI returns multiple series that\n  are the **same KPI** (same metric, **same unit**, **same aggregation period**),\n  **merge into one vertical series** (one row per date, value in the value column).\n  If they **differ** (e.g. quarterly vs annual, or different units), use **separate\n  blocks** or **separate labeled tables** — **one block per distinct deepKPI time\n  series** when they are not the same KPI.\n- **Derived / imputed metrics:** When you **fill a missing point** in an existing\n  series (e.g. Q4 from FY − Q1−Q2−Q3), put the value **in that series' row** in the\n  correct period column—**not** a separate \"Q4 (derived)\" line item. **Bold** or\n  annotate in-cell / **Notes** where helpful. **Distinct** derived KPIs (different\n  line item, e.g. YoY %) may still use their **own** row or column.\n- **Provenance:** `[value](exact-url)` per **Provenance — non-negotiable rules**.\n- **Prose:** optional short intro; do not bury the data in long narrative unless the\n  user asked for analysis.\n\nFor layout examples, see **In-chat table template (data pull)** below.\n\n### Mandatory: Excel offer after in-chat data pull\n\n**You must do this** whenever you showed KPI **data-pull** tables and the user did\n**not** already request a file (CSV / spreadsheet / Excel / `.xlsx`) in the same turn.\n\n1. Deliver the in-chat tables first.\n2. Then, in the **same assistant response**, add a **final** paragraph whose **main\n   question is entirely wrapped in Markdown bold** (`**...**`), asking whether the\n   user wants an **Excel workbook (.xlsx)** built for modeling (**periods as\n   columns:** annual block, blank separator, quarterly block — per the Revelata\n   Excel styling rules in `../_common/revelata-excel-styling-rules.md`). Example\n   (paraphrase allowed; **bold** is not optional):\n\n   **Would you like me to build an Excel workbook (.xlsx) laid out for modeling — periods across columns (annuals, then a blank column, then quarterlies) per our export spec?**\n\n   For a **full operating model** (revenue build, costs, consolidated financials,\n   depreciation, NWC in one workbook), use the `operating-model` skill instead of\n   a raw KPI export.\n\n3. Do **not** skip this step because the answer feels complete without it. Do **not**\n   bury it mid-message; put it **after** the tables so it is visible.\n4. If they **decline**, stop; if they **accept**, build the file per\n   `../_common/revelata-excel-styling-rules.md`.\n5. **Skip** this block only if: they already asked for a file export in that turn,\n   or you did **analysis-only** with **no** data tables, or they explicitly said they\n   do not want Excel.\n\n### CSV or spreadsheet output\n\nWhen the user asks for **CSV**, **spreadsheet**, **Excel**, **.xlsx**, agrees to\nthe **post-pull .xlsx offer**, or downloadable tabular output for a model — read\n`../_common/revelata-excel-styling-rules.md` and follow it in full (plus the\n**xlsx** skill for implementation).\n\n---\n\n## In-chat table template (data pull)\n\nStructure (read **down** the page; **time is rows**, not columns):\n\n- **Annual block first** — one table: **Period |** then one column per metric if\n  several annual series share FY labels; otherwise `Period | Value`. Oldest period\n  at the **top**.\n- **Break** — then **Quarterly** table(s): if quarterlies **align** on the same\n  periods, use **one table** with **Period | Metric A | Metric B | …**. Otherwise\n  split by mismatched axes.\n- **Merge vs split (KPI identity)** — unchanged: merge values that are the same KPI;\n  separate rows when metric/unit/aggregation differs.\n- **Derivations / imputation** — gap-fills (imputed Q4, etc.) live **inside** the\n  same row as the parent series for that period; **do not** add an extra line item\n  for the imputed point. Other derived KPIs get their own row/column when they are\n  genuinely separate metrics. **Note** imputation in Notes or inline where needed.\n\n**.xlsx is different:** file export uses **periods as columns** (annual block |\nblank | quarterlies) — see `../_common/revelata-excel-styling-rules.md`.\n\n```\n## [Metric group] ([Ticker])\nUnits: $M unless noted (store count = stores)\n\n### Annual\n| Period | Revenue (annual) | … |\n|--------|------------------|---|\n| FY2022 | [$1,196.8](url)  | … |\n| FY2023 | [$1,383.6](url)  | … |\n\n### Quarterly — aligned metrics (one table)\n| Period  | Revenue            | Store count |\n|---------|--------------------|-------------|\n| FY22-Q1 | [$248.0](url)      | [2,410](url) |\n| FY22-Q2 | [$300.9](url)      | [2,445](url) |\n| FY22-Q3 | [$292.2](url)      | [2,489](url) |\n| FY22-Q4 | **[$355.7](url)** (imputed in this row: FY−Q1−Q2−Q3; link operands) | [2,521](url) |\n| FY23-Q1 | [$267.1](url)      | [2,563](url) |\n```\n\n## Excel workbook (`.xlsx`)\n\nFor any **CSV / spreadsheet / Excel** deliverable from deepKPI, read\n`../_common/revelata-excel-styling-rules.md` and apply it end-to-end (layout,\nstyling, hyperlinks, dates, freeze panes, column grouping, checklist, CSV\nnotes). Use the **xlsx** skill to implement it. Do not duplicate those rules\nhere.\n\n## Common failure modes\n\n- **Dates as many columns in chat** on a plain data pull: keep **periods as rows**;\n  you may use **one column per metric** when periods align. Reserve **dates as\n  columns** (wide date axis) for **.xlsx** only.\n- **Splitting aligned metrics** into duplicate single-metric tables: if periods\n  match, **combine into one table** with a column per metric.\n- **Skipping list_kpis**: it's free and consistently guides better, cheaper searches.\n- **Querying too broadly**: \"revenue\" returns weak matches; use segment-specific terms.\n- **Leading with top-line when granular data exists**: always check for unit-level and segment KPIs first; only use consolidated totals when detail is unavailable. Showing same-store sales + traffic + ticket is more valuable than consolidated revenue alone.\n- **Apologizing for stale 10-K data when a newer 10-Q exists**: if the KPI has a more\n  recent quarterly period available, use it. Reserve annual-only caveats for cases\n  where quarterlies truly aren't present in deepKPI.\n- **Mixing period types silently**: always label each value as annual or quarterly.\n- **Balance sheet items as flows**: receivables at Dec 31 IS Q4 — don't subtract.\n- **Hallucinating a URL**: if you don't have the exact URL, say so; never construct one.\n- **Plain-text URLs in tables**: always format as `[label](url)` — clickability is required.\n- **Extra Source rows in .xlsx**: filing identity belongs in the **cell hyperlink**\n  only; do not add redundant source listing rows.\n- **Omitting the post-pull Excel question** after showing KPI tables: the **bold**\n  offer is **mandatory** unless the user already asked for a file or refused Excel.\n- **Verbatim filing text / \"what did they say\"**: wrong skill — use the `filing`\n  skill instead of improvising from KPI pulls.\n- **\"What do they do?\" / segment breakdowns / \"who operates in X?\"**: wrong skill —\n  use the `company-summary` skill instead of `search_kpis` alone. (Target-based\n  \"most similar\" benchmarking: use the `benchmark` skill, not `company_summary_search`\n  as a substitute.)\n"
}