Update to Ultralayer

{
  "description": "Map a market situation to ranked public-company winners and losers with verified tickers, signed impact scores, cited quotes, and a factor comparison matrix. Operation is identify_stakeholders.",
  "included_files": [],
  "name": "stakeholder-identification",
  "skill_md_contents": "---\nname: stakeholder-identification\ndescription: Map a market situation to ranked public-company winners and losers with verified tickers, signed impact scores, cited quotes, and a factor comparison matrix. Operation is identify_stakeholders.\n---\n\n# Stakeholder identification\n\n`identify_stakeholders` answers “who matters for this situation, and why?” It retrieves finance-specific evidence, returns structured public-company impacts with cited quotes, verifies tickers, and ships a factor comparison matrix.\n\n| Operation | Role |\n|-----------|------|\n| `identify_stakeholders` | Situation → ranked stakeholders + factor matrix |\n\n**Latency:** commonly ~2 minutes. Budget for that. Do not treat timeouts as “empty universe.” Do not spam parallel calls.\n\n**Approval for Agents:** If a user is waiting on this turn (chat), tell them it takes ~2 minutes and get explicit approval before calling. If no one is waiting (one-shot / autonomous / unattended), call and wait.\n\n---\n\n## When to use\n\n**Use when you need:**\n- Ranked public-company winners/losers for a market situation, with direction + magnitude\n- Why each name is exposed (rationale) plus auditable quotes\n- A factor matrix to compare the returned names at a glance\n- Backtest-safe identification as-of a historical `end_timestamp`\n\n**Do not use when you need:**\n- Fast headline triage → Wire\n- Open-web research (article body, quotes, filings, prices) → your native web search tool\n- One company’s live dossier → `retrieve_entity`\n- Already-stored development packages → `search_developments` (SI creates fresh assessments; developments store prior ones)\n- Non-company stakeholders (countries, commodities, people, private cos) → out of scope (`PUBLIC_COMPANY` only)\n\nGeneric LLMs invent tickers; this endpoint retrieves evidence, cites exact quotes, verifies symbols, and returns a reusable factor table — with optional point-in-time mode.\n\n---\n\n## Use cases\n\n**Realtime supply shock** — Map who wins and loses if a concrete market shock hits, with verified tickers and cited reasons.\n```json\n{\n  \"query\": \"Strait of Hormuz near-total closure and oil supply shock\"\n}\n```\n\n**Realtime with steering** — Same exposure map, but steer coverage toward second-order names and keep the list tight.\n```json\n{\n  \"query\": \"Tesla Q2 2026 earnings miss and margin compression\",\n  \"context\": \"EPS well below consensus; operating margin ~1.4%; negative FCF; energy storage strong.\",\n  \"instructions\": \"Prioritize clear second-order exposures (EV peers, suppliers, AI compute). Prefer fewer high-confidence names.\"\n}\n```\n\n**Historical / backtest** — Ask who mattered as of a past date, without live-web leakage after that cutoff.\n```json\n{\n  \"query\": \"Apple CEO succession Tim Cook to John Ternus\",\n  \"end_timestamp\": \"2026-04-25T00:00:00Z\"\n}\n```\n\n**Constrained universe** — Force a short, sector-balanced list instead of a long undifferentiated dump.\n```json\n{\n  \"query\": \"who benefits from rising oil prices\",\n  \"instructions\": \"Return at most 6 public companies spanning upstream, midstream, and airlines as losers.\"\n}\n```\n\n**Regulation / tariffs** — Identify listed companies with clear regulatory exposure for a policy action.\n```json\n{\n  \"query\": \"EU Digital Markets Act fines on Big Tech self-preferencing\",\n  \"instructions\": \"Focus on listed platforms and ad-tech peers with clear regulatory exposure.\"\n}\n```\n\n---\n\n## Response detail\n\n`identify_stakeholders` accepts `detail`. **Default is `full`.** Reduced levels **drop keys** only — surviving fields keep the same names and paths as `full`. Pricing does not change with `detail`; this is about **response token cost** in the agent context (especially valuable here — SI payloads are large).\n\n| Level | What you get | Rough token savings vs `full` |\n|-------|----------------|-------------------------------|\n| `essential` | Stakeholders with impact + rationale; factor matrix with name/description/value/rationale (no sources, no confidence, no rubrics/scale) | ~80% |\n| `standard` | essential + confidence, factor scale/rubric, and citable sources (no quotes) | ~31% |\n| `full` | Every field including source quotes and full factor definitions | — |\n\n**Prefer `detail: \"standard\"`** for normal agent calls. Use `essential` for a cheap ranked map; use `full` when you need auditable quotes in the payload.\n\n```json\n{\n  \"query\": \"Strait of Hormuz near-total closure and oil supply shock\",\n  \"detail\": \"standard\"\n}\n```\n\n---\n\n## Params\n\n| Param | Role |\n|-------|------|\n| `query` (required) | The situation. Non-empty after strip; blank → 422. Max **2000** characters. |\n| `context` | Extra facts about the situation (what happened, numbers, constraints). Max **12000** characters. |\n| `instructions` | How to shape the answer (coverage, count, sectors to prefer/avoid) — not treated as the search subject. Max **2000** characters. |\n| `end_timestamp` | Omit/null = **realtime**. Past = **backfill**. Future → realtime. No `start_timestamp`. |\n| `detail` | Default `full`. Prefer `standard` (see **detail** above). |\n\nPrefer a concrete situation over a vague theme. Put hard facts in `context`; put process prefs in `instructions` (`\"Prefer fewer high-confidence names\"`, `\"At most 6 names\"`). Instructions work — they change count and composition.\n\nOnly verified public tickers are returned as stakeholders.\n\n---\n\n## Realtime vs backfill\n\n| Mode | Trigger | Behavior |\n|------|---------|----------|\n| **Realtime** | `end_timestamp` null/future | Uses live web retrieval plus historical structured SI context |\n| **Backfill** | past `end_timestamp` | No live web. Evidence from indexed corpus and historical SI context clamped to `end_timestamp` — backtest-safe |\n\nUse backfill for “what would an analyst have concluded knowing only info ≤ T?” Use realtime for “given the live tape, who is in the blast radius?”\n\nReturned tickers are verified; unverified names are dropped.\n\n---\n\n## What you get back\n\n### `stakeholder_impacts[]`\n- `stakeholder`: `{ name, stakeholder_type: \"PUBLIC_COMPANY\", symbol }`\n- `impact_score` ∈ [-1, 1]\n- `confidence_score` ∈ [0, 1]\n- `rationale`\n- `sources_with_quotes[]` — exact quotes with source metadata\n\nScan strongest positives and strongest negatives first.\n\n### `factor_matrix[]`\nRows = situation-specific factors. Each has `name` (snake_case), `description`, `factor_scale`, `rubric`, optional `allowed_values`, and `stakeholder_assessments` keyed by **symbol**.\n\nScales: `BINARY` | `CATEGORICAL` | `CONTINUOUS` [0,1] | `SIGNED_CONTINUOUS` [-1,1].\n\nUse the matrix for “who is more exposed on dimension X?” Factor names are meant to be reusable across similar situations. A factor row may occasionally omit a symbol — treat missing cells as unknown, not zero.\n\n---\n\n## Workflow\n\n| User intent | Approach |\n|-------------|----------|\n| “Who wins/loses if X?” | Realtime SI on a precise query; brief from impact extremes + factor matrix |\n| “As of date D, who mattered?” | Same query + past `end_timestamp` |\n| “Keep it short / sector-focused” | Put constraints in `instructions` |\n| “Drill one ticker after SI” | `retrieve_entity`, Wire, or developments with `symbols` |\n| “Just give me headlines” | Wire — do not pay SI latency for firehose |\n\n1. Confirm the user wants situation → public-company exposure.\n2. Craft a specific `query`; add `context` / `instructions` only when they sharpen the job.\n3. Get approval if applicable: If you are an interactive chat agent, and there is a user waiting, get approval for the ~2 min wait before calling.\n4. Call once; wait. On timeout, retry once — do not fan out parallel SI calls.\n5. Brief: top ± impacts → factor matrix highlights → cite 1–2 quotes per key name.\n6. Offer follow-ups via Wire / developments / `retrieve_entity` / your native web search tool using returned symbols.\n\n---\n\n## Limitations\n\n- Slow — plan for ~2 minutes; avoid speculative retries and fan-out.\n- Public companies only; listing suffixes vary (`SMSN.IL`, `BYDDF`, `AMKBY`).\n- Verification can drop proposed names — final list ⊆ verified survivors.\n- Not a price target or trading signal — impact scores are reasoned exposures with citations.\n- Backfill quality depends on indexed corpus ≤ T.\n- Factor matrix is built per call — read names/rubrics; don’t assume identical every time.\n- Does not return countries/commodities as stakeholders even when they dominate the narrative.\n\n---\n\n## FAQ\n\n**Q: Why is this better than asking a normal agent?**  \nA: Retrieval + quote binding + ticker verification + factor matrix + backtest mode.\n\n**Q: Future `end_timestamp` — historical or live?**  \nA: Treated as realtime.\n\n**Q: Can I get private cos / OPEC / Brent as stakeholders?**  \nA: Not as structured stakeholders. They may appear in rationales/sources only.\n\n**Q: How do I continue after SI?**  \nA: Take symbols → Wire filters, `search_developments(symbols=…)`, `retrieve_entity`, or your native web search tool.\n\n**Q: Empty / whitespace query?**  \nA: 422 `query must be a non-empty string.`\n\n**Q: Query / context / instructions too long?**  \nA: 422. Caps are 2000 chars (`query` / `instructions`) and 12000 chars (`context`).\n"
}