Update to Ultralayer

{
  "description": "Official company outlooks, how they revised, how they compared to the reported actual, and the aggregate score of that. Operations are list_guidance, list_guidance_outcomes, and guidance_bias.",
  "included_files": [],
  "name": "guidance",
  "skill_md_contents": "---\nname: guidance\ndescription: Official company outlooks, how they revised, how they compared to the reported actual, and the aggregate score of that. Operations are list_guidance, list_guidance_outcomes, and guidance_bias.\n---\n\n# Guidance\n\n`list_guidance` is the official outlook tape: what the company said it expects, when it said it, and how that number moved vs the last observation of the same series.\n\n`list_guidance_outcomes` is company guidance versus the reported actual. One pair per series after that period reported.\n\n`guidance_bias` is the aggregate score of those results. One point per report period.\n\n| Operation | Role |\n|-----------|------|\n| `list_guidance` | Current and past outlooks, with revision history |\n| `list_guidance_outcomes` | Company guidance versus the reported actual |\n| `guidance_bias` | Average of those results, one score per report |\n\nEvery filter works **without a ticker list**, so these are cross-sectional screens as much as single-name lookups: who moved an outlook today, which peers guide the same period, who missed their own guide this cycle. `end_timestamp` rebuilds any of it as of a past day, so a screen can be backtested.\n\n---\n\n## When to use\n\n**`list_guidance`** — What they expect now, who just guided, who raised or cut, the history of one line, guidance for the same metric across companies, or the book as of a past day.\n\n**`list_guidance_outcomes`** — What they guided versus what they reported. Empty until that period reports; the live outlook stays on `list_guidance`.\n\n**`guidance_bias`** — Whether a name habitually guides below what it prints, which is a prior on the next guide.\n\n**Not these tools:** sell-side consensus, rumor, or reaction → Wire / developments / your own web search. Wording changes in the release → `list_changes`. A company dossier → `retrieve_entity`.\n\n---\n\n## Detail\n\nAPI default is `full`. **Set `standard` unless you need ranges, revision deltas, `observation_count`, or `cik`.** `detail` does not change price. `guidance_bias` has no `detail`.\n\n**`list_guidance`**\n\n| Level | What you get |\n|-------|----------------|\n| `standard` | Quote, cite, `revision_direction`, `value_midpoint`, `unit`, `yoy_value_midpoint`, `yoy_unit`. What an LLM should read. |\n| `full` | Ranges, `revision_midpoint_delta_pct`, `observation_count`, `cik`, `source_metadata` |\n| `essential` | Quote, identity, `source_type`, `revision_direction`. No company name, ingest timestamp, URL, or numbers. |\n\n**`list_guidance_outcomes`**\n\n| Level | What you get |\n|-------|----------------|\n| `standard` | Quotes, labels, cites |\n| `full` | Guided range, actual, deltas, `rationale`, `cik` |\n| `essential` | Identity and outcome label |\n\n---\n\n## Clocks and shared filters\n\nTime filters use when **we recorded** the row, not publication time. `end_timestamp: null` = now. A future end is treated as now.\n\n| Tool | `start_timestamp` / `end_timestamp` |\n|------|--------------------------------------|\n| `list_guidance` | When the outlook was recorded. `start` only picks which series appear; history inside a series goes up to `end` |\n| `list_guidance_outcomes` / `guidance_bias` | When the **result** was recorded, not when they guided |\n\nFor “that quarter,” use `guided_period_end_from` / `_to` or `guided_fiscal_year` / `guided_fiscal_quarter`. A May print of Q1 is not an Apr–Jun window. `guided_fiscal_quarter=4` is the Q4 outlook, not every pair that printed in Q4.\n\nAND across fields; OR inside a list. Same names on `list_guidance` and `list_guidance_outcomes` where the field exists.\n\n| Param | Notes |\n|-------|-------|\n| `symbols` | Tickers, max 8 |\n| `metric_keys` | Substring, case does not matter. `revenue` also matches `revenue_growth`. Pin `metric_key_exact_match: true` for one key |\n| `metric_basis` | `gaap` / `non_gaap` / `unspecified`. One sentence is often two series (GAAP and non-GAAP) — do not double-count |\n| `segments` | Named cuts, or `\"null\"` for company-wide. `\"consolidated\"` will miss |\n| `guided_period_end_*` | Calendar day the outlook period ends — use this to line up companies |\n\n`guidance_bias` is one `symbol` and an optional window. No metric filter, no `limit`, no `detail`.\n\n---\n\n## list_guidance\n\nOne object per series: ticker × metric × GAAP/non-GAAP × segment × period. `values[]` is that line’s history, newest first.\n\nDefault `limit` is 10 (max 100). Default `values_mode` is `all`. Pin a metric or raise `limit` so one name does not fill the page.\n\n`latest` is the newest observation **per series** (often the call), not “current slide only.” For the **printed number**, use `values_mode: \"all\"` and take the latest `earnings_release` row in `values[]`. If the call and an 8-K disagree, still use that release row. Keep the call for color.\n\n### Use cases\n\n**Realtime guidance tape** — Every series that just moved, market-wide, minutes after the print. No tickers. This is the desk feed.\n```json\n{\n  \"values_mode\": \"latest\",\n  \"sort\": \"timestamp\",\n  \"detail\": \"standard\",\n  \"limit\": 40\n}\n```\n\n**Who raised or cut, market-wide** — Cross-sectional revision screen, no ticker list. `revision_delta` puts the biggest midpoint moves first. Read `metric_key` before calling a raise good: OpEx, tax, and cost guides go up on bad news. Sanity-check the top rows against the quote — an enormous `revision_midpoint_delta_pct` usually means the two observations were stated at different scales, not that the outlook moved that much.\n```json\n{\n  \"revision_direction\": [\"raised\", \"lowered\"],\n  \"values_mode\": \"latest\",\n  \"sort\": \"revision_delta\",\n  \"detail\": \"full\",\n  \"limit\": 40\n}\n```\n\n**Peer cohort on one metric** — Same metric, same calendar period-end, ranked like-for-like. Fiscal labels do not align across companies; `guided_period_end_*` does. `comparable` ranks on the more common comparison in the match set (growth % vs rate level); rows without that number sort last.\n```json\n{\n  \"metric_keys\": [\"revenue\"],\n  \"metric_key_exact_match\": true,\n  \"guided_period_end_from\": \"2026-12-01\",\n  \"guided_period_end_to\": \"2027-01-31\",\n  \"values_mode\": \"latest\",\n  \"sort\": \"comparable\",\n  \"detail\": \"full\",\n  \"limit\": 40\n}\n```\n\n**One company’s outlook pack** — Every open line. Split rows by quarter vs year on `guided_period_type` / `guided_period_end_date`.\n```json\n{\n  \"symbols\": [\"NVDA\"],\n  \"values_mode\": \"latest\",\n  \"detail\": \"standard\",\n  \"limit\": 40\n}\n```\n\n**The number they printed** — `latest` can be the call; the release row is the citable figure. History keeps both.\n```json\n{\n  \"symbols\": [\"NVDA\"],\n  \"metric_keys\": [\"revenue\"],\n  \"metric_key_exact_match\": true,\n  \"values_mode\": \"all\",\n  \"detail\": \"full\"\n}\n```\n\n**Off-cycle revisions** — An 8-K that moves the outlook away from an earnings date. Rare and high-signal. `values[]` still holds the release it changed; pick rows by `values[].source_type`.\n```json\n{\n  \"source_types\": [\"guidance_update\"],\n  \"values_mode\": \"all\",\n  \"sort\": \"timestamp\",\n  \"detail\": \"standard\",\n  \"limit\": 20\n}\n```\n\n**The book as of a past day** — PIT. What the outlook was on date D, no later leakage. This is how a guidance signal gets backtested.\n```json\n{\n  \"end_timestamp\": \"2026-06-30T20:00:00Z\",\n  \"values_mode\": \"latest\",\n  \"sort\": \"timestamp\",\n  \"detail\": \"standard\",\n  \"limit\": 40\n}\n```\n\n### What you get back\n\n| Field | Notes |\n|-------|-------|\n| `values[]` | Newest first |\n| `guided_period_end_date` | Use this to line up peers |\n\n**At `standard`, each value:** `quote`, `timestamp`, `source_type`, `value_midpoint`, `unit`, `yoy_value_midpoint`, `yoy_unit`, `revision_direction`, `source`. Trust the quote if a label disagrees. A floor/ceiling midpoint is the stated bound, not a range center.\n\n`revision_direction` is vs the last observation of **this** series (`new` / `raised` / `lowered` / `maintained` / `withdrawn`), not good/bad. It can be `null` — that is not `new`.\n\n**Full only:** `revision_midpoint_delta_pct` (percent of the prior midpoint: 4.0 → 4.5 is +12.5, not +0.5), ranges (`value_low`/`value_high`), `observation_count` (length as of `end_timestamp`, not always `len(values)`), `cik`, `source_metadata`.\n\n**Source:** `earnings_release` / `guidance_update` / `earnings_call`. At `standard`, `source_metadata` is null; the URL is still on the source. At `full`, `source_metadata.fiscal_year` / `fiscal_quarter` are the **document’s** completed period (a Q2 release guiding Q3 has Q2 here). To join `list_changes`, bump this call to `full` and use those fields — not `guided_*`.\n\n### Filters and sort\n\n`revision_direction` matches the **latest** observation only.\n\n`source_types` includes a series if **any** observation has that class. `values[]` stays the full history. `earnings_release` + `latest` can still return a later **call**. Read `values[].source_type`.\n\n| `sort` | Order |\n|-------|--------|\n| `timestamp` (default) | Most recently updated series first |\n| `guided_period_end` | Period-end, oldest first |\n| `comparable` | Strongest like-for-like number in the match set (growth % or rate level, whichever is more common). Pin period-end dates for a fair cohort |\n| `revision_delta` | Largest latest midpoint move |\n\n---\n\n## list_guidance_outcomes\n\nCompany guidance versus the reported actual. One pair per series after that period reported.\n\nThis is an estimate-vs-actual record where the estimate is **the company’s own**, not the street’s — scored, quoted, and cited. Run it without tickers for a market-wide beat/miss screen.\n\nIf the same outlook is on the press release and the next-day call, the release is kept. Then the newest remaining guide against that actual is kept. A preannouncement and a later full release stay two rows.\n\nDefault `outcomes` is the scored results only. Pass `indeterminate` to see rows that could not be scored. Omit does not mean all rows.\n\nDefault `limit` is 10. Raise it — 10 is a page, not the whole print.\n\n### Use cases\n\n**One name’s track record** — Every guide they set and what printed against it. The company’s own estimate table.\n```json\n{\n  \"symbols\": [\"AMZN\"],\n  \"detail\": \"standard\",\n  \"limit\": 40\n}\n```\n\n**Market-wide beat/miss screen** — No tickers. Who blew through or fell short of their own guide this cycle. `outcome_abs` puts the extremes first.\n```json\n{\n  \"outcomes\": [\"significantly_exceeded\", \"significantly_missed\"],\n  \"sort\": \"outcome_abs\",\n  \"detail\": \"standard\",\n  \"limit\": 40\n}\n```\n\n**Read-across cohort** — One metric, one calendar period-end, across peers. Names that already reported give the base rate for names that have not. Reporting dates are staggered, so this window is where the lag lives.\n```json\n{\n  \"metric_keys\": [\"revenue\"],\n  \"metric_key_exact_match\": true,\n  \"guided_period_end_from\": \"2026-06-01\",\n  \"guided_period_end_to\": \"2026-07-31\",\n  \"detail\": \"full\",\n  \"limit\": 40\n}\n```\n\n**That period for one name** — Pin the outlook period, not `start_timestamp`.\n```json\n{\n  \"symbols\": [\"NVDA\"],\n  \"guided_period_end_from\": \"2026-07-01\",\n  \"guided_period_end_to\": \"2026-08-31\",\n  \"detail\": \"standard\"\n}\n```\n\n**Why a label looks wrong** — `indeterminate` rows are guides with no comparable actual (a segment cost call, a capacity target). `full` carries the `rationale`.\n```json\n{\n  \"symbols\": [\"AMZN\"],\n  \"outcomes\": [\"indeterminate\"],\n  \"detail\": \"full\",\n  \"limit\": 20\n}\n```\n\n### What you get back\n\n| Field | Notes |\n|-------|-------|\n| `outcome` | Vs **this** guide, not good/bad for the stock. Read the metric and the quotes |\n| `guidance_quote` / `actual_quote` | Ground truth. Trust these over `outcome` and over `rationale`, which can disagree with each other |\n| `actual_source_type` | `earnings_release` or `earnings_preannouncement` |\n\n`standard` has the quotes and links. `full` adds the guided range, the actual, the deltas, and `rationale` (why that label).\n\nMatch to `list_guidance` on ticker + metric + GAAP/non-GAAP + segment + period. There is no shared id.\n\n| `sort` | Order |\n|-------|--------|\n| `timestamp` (default) | Newest result first |\n| `outcome_abs` | Largest miss or beat first (by label, not by dollars) |\n\n---\n\n## guidance_bias\n\nOne name. Oldest report first. The whole series in the window.\n\nThe pattern is the point, and it is **forward-looking**: a company that scores positive report after report guides low and beats, so its next guide is probably a floor. Persistently negative means the guide runs optimistic and should be discounted. A single point is a scorecard; the run is a prior on the next print.\n\n```\nsignificantly_exceeded = +2\nexceeded               = +1\nin_line                =  0\nmissed                 = -1\nsignificantly_missed   = -2\n```\n\nAverage of those scores. Unscored rows are left out.\n\nEach point: `bias_score`, `resolved_count`, `label_counts`, and `fiscal_year` / `fiscal_quarter` of the **report that printed the actual**, not the guided period. Several lines can land in one report (revenue and operating income, GAAP and non-GAAP, a quarter guide and a year guide). They share one point. `resolved_count` of 2 is normal. The latest point is the last report, not the next print.\n\nThe outcomes list keeps only the newest guide per line. Bias averages every guide that closed that night, so `resolved_count` will not always match the outcomes list.\n\nDo not rank many names from this tool (one symbol per call). Do not treat a single vote as a pattern.\n\n### Use cases\n\n**Sandbagger or over-promiser** — Read the run of `bias_score`, then pull the pairs behind it with `list_guidance_outcomes` on the same ticker.\n```json\n{\n  \"symbol\": \"AMZN\"\n}\n```\n\n**As of a past day** — PIT the score so a backtest only sees reports that had already printed.\n```json\n{\n  \"symbol\": \"AAPL\",\n  \"end_timestamp\": \"2026-08-01T00:00:00Z\"\n}\n```\n\n---\n\n## Workflow\n\nChains worth more than a single call.\n\n**Earnings-night brief on one name**\n1. `list_guidance` — ticker, `values_mode: \"all\"`, `full`. Printed figures come from the latest `earnings_release` row per series; the call row is color.\n2. `list_guidance_outcomes` — same ticker. The period that just closed is now scored against the guide they gave a quarter ago.\n3. `list_changes` — ticker + the fiscal year/quarter from step 1’s `source_metadata`. This is how the wording moved around those numbers: non-GAAP definitions, segment cuts, outlook assumptions.\n4. Wire (legal name, `Nvidia Corporation`) for how the tape read it; your own web search for sell-side reaction.\n\n**Read-across before the laggard prints**\n1. `list_guidance_outcomes` — one metric + a `guided_period_end_*` window covering the cohort. Peers that already reported show whether guides for that period ran hot or cold.\n2. `list_guidance` — same metric and window, `values_mode: \"latest\"`. The names still open, with the guide they are about to be measured against.\n3. `guidance_bias` — on each open name. A habitual sandbagger into a hot cohort is a different setup than an over-promiser into a cold one.\n4. `identify_stakeholders` or `search_developments` — when the driver is a shared shock (tariffs, memory pricing, freight rates) rather than a company story.\n\n**Cross-sectional revision screen**\n1. `list_guidance` — no tickers, `revision_direction: [\"raised\",\"lowered\"]`, `sort: \"revision_delta\"`, `full`. The largest outlook moves in the market.\n2. Split the results yourself on `metric_key` and `metric_basis`. A raised cost guide is not a raised revenue guide, and one sentence can be both GAAP and non-GAAP.\n3. `list_changes` — `guidance_basis` on the same names, to separate real demand from a re-based outlook (a deal folded in, a tariff assumption added).\n4. `market_signal` or Wire — whether the tape has already priced it.\n\n**Backtest a guidance signal**\n1. `list_guidance` — `end_timestamp` = decision date, `values_mode: \"latest\"`. The book as it stood, with no leakage.\n2. `list_guidance_outcomes` — a later window, same filters. What those guides turned into.\n3. `guidance_bias` — with `end_timestamp` at each decision date, so the score only knows prior reports.\n\n**Leave it running**\n`create_alert` on `list_guidance` (revisions) or `list_guidance_outcomes` (beats and misses), arguments minus timestamps — the alert owns the window. Keep `values_mode: \"all\"` so each delivery carries the prior print to compare against.\n\n---\n\n## Combine with\n\n- **Wire / developments** — Why it matters. Wire wants the legal name (`Nvidia Corporation`), not `NVDA`.\n- **`list_changes`** — How they wrote the release. Same ticker; match the document’s fiscal period from `source_metadata` (`list_guidance` at `full`).\n- **Alerts** — `list_guidance` and `list_guidance_outcomes` only; `guidance_bias` is not alertable. See **Workflow**.\n\n---\n\n## Limitations\n\n- Not every listed company is in the data. Empty is not “no outlook” and not “they always hit.”\n- `latest` can still show an old child series next to a current print. Assemble the pack; don’t treat the first N rows as the slide.\n- Empty `revenue` after a substring search ≠ no outlook. Read the pack.\n- `source_types` does not filter `values[]`.\n- Transcripts use an Ultralayer URL; press releases use the SEC URL.\n\n---\n\n## FAQ\n\n**Why did `source_types: [\"earnings_release\"]` return a call?**  \nThe series once had a release. The newest row can still be the call. Read `values[].source_type`.\n\n**Why is WMT `revenue` empty?**  \nThey may not guide a revenue-like line. Substring is the default (`revenue` also matches `revenue_growth`). Do not say they have no outlook. Pin `metric_key_exact_match: true` if you only want the level.\n\n**Why doesn’t `resolved_count` match the outcomes list?**  \nThe list keeps the newest guide per line. Bias averages every guide that closed that night.\n"
}