Update to Ultralayer

{
  "description": "Structured market narratives — impact-scored, source-cited developments clustered into longer-lived events. Operations are search_developments, retrieve_development, search_events, and retrieve_event_developments.",
  "included_files": [],
  "name": "developments-and-events",
  "skill_md_contents": "---\nname: developments-and-events\ndescription: Structured market narratives — impact-scored, source-cited developments clustered into longer-lived events. Operations are search_developments, retrieve_development, search_events, and retrieve_event_developments.\n---\n\n# Developments and events\n\n**Developments** are structured narrative units (name, description, scores, stakeholders with signed impact, sources with quotes) versioned over time. **Events** are longer-lived story containers that group related developments into a lifecycle (earnings cycle, M&A process, regulatory campaign, geopolitical conflict).\n\n| Operation | Role |\n|-----------|------|\n| `search_developments` | Semantic or filter search over developments — returns packages |\n| `retrieve_development` | Package for one known `development_id` (optional as-of) |\n| `search_events` | Semantic or filter search over events; embeds recent development summaries |\n| `retrieve_event_developments` | Event metadata + developments timeline |\n\n---\n\n## When to use\n\n**Use this surface when you need to:**\n- Explain a market move with who wins/loses (signed `impact_score` per ticker) and cited sources\n- Track a storyline lifecycle via an `event_id`\n- Scan for surprising / important developments\n- Filter by public-company ticker involvement\n- Backtest “what was known as of T” with `end_timestamp`\n\n**Do not use when you need:**\n- Realtime novelty-clustered headlines → Wire\n- Open-web research (article body, quotes, filings, prices) → your native web search tool\n- A single-entity dossier → `retrieve_entity`\n- Entity-filtered headline monitoring → Wire\n\n---\n\n## Use cases\n\n**Ticker blast radius** — Find developments that hit a ticker hard in either direction, with signed impacts and quotes.\n```json\n{\n  \"symbols\": [\"TSLA\"],\n  \"min_impact_score\": 0.5,\n  \"max_impact_score\": -0.5,\n  \"limit\": 8\n}\n```\n\n**Negative for one ticker** — Isolate clearly negative impact on a single name.\n```json\n{\n  \"symbols\": [\"GOOGL\"],\n  \"max_impact_score\": -0.5,\n  \"limit\": 8\n}\n```\n\n**Portfolio watchlist** — One query for up to eight tickers instead of one call per name.\n```json\n{\n  \"symbols\": [\"AAPL\", \"MSFT\", \"NVDA\", \"AMZN\", \"GOOGL\", \"META\", \"TSLA\", \"AVGO\"],\n  \"min_importance_score\": 0.7,\n  \"limit\": 10\n}\n```\n\n**Surprising geopolitics** — Scan for high-surprise security developments, not every geopolitics mention.\n```json\n{\n  \"development_type\": \"geopolitical_security\",\n  \"min_surprise_score\": 0.6,\n  \"start_timestamp\": \"2026-07-20T00:00:00Z\",\n  \"limit\": 10\n}\n```\n\n**Theme → development evidence** — Ask in natural language and get structured impact packages back.\n```json\n{\n  \"query\": \"Strait of Hormuz shipping disruption oil\",\n  \"start_timestamp\": \"2026-07-01T00:00:00Z\",\n  \"limit\": 5\n}\n```\n\n**Theme → event clusters** — See how a theme groups into longer-lived stories, not just one-off updates.\n```json\n{\n  \"query\": \"Middle East oil\",\n  \"limit\": 5,\n  \"developments_per_event\": 2\n}\n```\n\n**M&A scan** — List active deal storylines without inventing your own type labels.\n```json\n{\n  \"event_type\": \"merger_acquisition\",\n  \"limit\": 5,\n  \"developments_per_event\": 1\n}\n```\n\n**Important prints** — Desk scan for high-importance developments without a theme query.\n```json\n{\n  \"min_importance_score\": 0.8,\n  \"limit\": 10\n}\n```\n\n**Lifecycle expand** — Once you have an event id, pull the full timeline (scheduled → print → follow-ons).\n```json\n{\n  \"event_id\": 125,\n  \"limit\": 20,\n  \"include_future_developments\": true\n}\n```\n\n**As-of / backtest search** — Ask what developments were known as of a past timestamp.\n```json\n{\n  \"query\": \"Tesla Q2 earnings margins\",\n  \"end_timestamp\": \"2026-07-22T21:00:00Z\",\n  \"limit\": 10\n}\n```\n\n**As-of single development** — Reconstruct one development’s package as it stood at a prior time.\n```json\n{\n  \"development_id\": 1793,\n  \"end_timestamp\": \"2026-07-22T21:00:00Z\"\n}\n```\n\n---\n\n## Mental model\n\n```text\nEvent (long-lived story)\n  └── Development (versioned fact/update in that story)\n        ├── scores: importance / surprise / confidence\n        ├── occurrence_*: real-world time + status\n        ├── stakeholders[]: PUBLIC_COMPANY + symbol + impact ∈ [-1,1]\n        └── sources[]: citations with quotes\n```\n\nA development can belong to **multiple events**. Always read `events` / `event_ids`.\n\nThree clocks (do not conflate):\n\n| Field | Meaning |\n|-------|---------|\n| `timestamp` | System/version time — used for backtest `start`/`end_timestamp` and “latest version” collapse |\n| `source_timestamp` | Latest source used for the development |\n| `occurrence_timestamp` | Estimated real-world when it happened (or will) — lifecycle ordering and `include_future_developments` |\n\n---\n\n## Response detail\n\nMost operations accept `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** (development packages are heavy).\n\n### search_developments / retrieve_development / retrieve_event_developments\n\nLevels: `full` | `standard` | `essential`.\n\n| Level | What you get | Rough token savings vs `full` |\n|-------|----------------|-------------------------------|\n| `essential` | Identity, timing, name/description, stakeholder impacts (no confidence/sources), thin event refs | ~75% (search/retrieve development); ~68% (`retrieve_event_developments`) |\n| `standard` | essential + type/status, heuristic scores, citable sources (title/url; no quotes), fuller event summaries | ~39% (search/retrieve development); ~38% (`retrieve_event_developments`) |\n| `full` | Every field including rationale and source quotes | — |\n\n**Prefer `detail: \"standard\"`** for normal agent calls. Use `essential` for scanning many packages; use `full` when you need rationale or quoted evidence in the payload.\n\n```json\n{\n  \"symbols\": [\"TSLA\"],\n  \"min_impact_score\": 0.5,\n  \"max_impact_score\": -0.5,\n  \"limit\": 8,\n  \"detail\": \"standard\"\n}\n```\n\n### search_events\n\nLevels: `full` | `essential` only (no `standard` — the middle tier barely saved tokens on this shape).\n\n| Level | What you get | Rough token savings vs `full` |\n|-------|----------------|-------------------------------|\n| `essential` | Event id/name/description + recent development summaries (id / occurrence / name / description) | ~33% |\n| `full` | Includes `event_type` and richer recent-development fields (scores, types, …) | — |\n\nPrefer `detail: \"essential\"` when scanning events; use `full` when you need event type or summary scores.\n\n---\n\n## search_developments\n\nOptional `query`: semantic over development descriptions, ranked by cosine (cosine not returned in the response). No query: latest version per `development_id` matching filters, ordered by `timestamp` DESC.\n\nReturns development packages shaped by `detail` (default `full`; prefer `standard` — see **detail** above). You do not need `retrieve_development` after a search hit unless you need as-of reconstruction for a known id.\n\n| Param | Notes |\n|-------|-------|\n| `query` | Optional. Max 2000 chars. |\n| `symbols` | Tickers, max 8. Match any. **Exact** as stored (`TSLA`, `GOOGL`, `SGRO.L`). `tsla` → `[]`. Not Ultralayer canonical names. |\n| `min_impact_score` / `max_impact_score` | Alone: threshold. **Together: directional OR** (`impact >= min OR impact <= max`) — requires `min >= max` (e.g. `0.5` + `-0.5`). |\n| `min_importance_score` / `min_surprise_score` / `min_confidence_score` | Importance ~0.8+ is a strong desk filter |\n| `development_type` | Exact free-form string (`financial_update`, `corporate_action`, `geopolitical_security`, …). Invented values silently return `[]`. Discover types from results. |\n| `start_timestamp` / `end_timestamp` | On development `timestamp`. Future start → 422. Future end → realtime. |\n| `start_occurrence_timestamp` / `end_occurrence_timestamp` | Real-world occurrence clock |\n| `limit` | Default 5, max 20 |\n| `detail` | Default `full`. Prefer `standard`. |\n\nPackages are large at `full` (rationale + per-stakeholder quotes). Prefer tight `limit` (3–10) and `detail: \"standard\"`; expand event context with `retrieve_event_developments` when you need the storyline.\n\n`occurrence_status` values seen: `occurred`, `scheduled`, `announced`, `ongoing`, `rumored` — no status filter param.\n\n---\n\n## retrieve_development\n\nRequired: `development_id`. Optional: `end_timestamp` for as-of (latest version with `timestamp <= end`). Optional: `detail` (default `full`; prefer `standard`).\n\nUse when you already have an id (from an alert, prior run, or citation) or need as-of reconstruction. Search results already include the package at the requested `detail` — do not re-fetch the same id after `search_developments` unless you need a different `detail` or as-of.\n\nMissing id → 404. As-of before the development existed → 404. Future `end_timestamp` → realtime.\n\n---\n\n## search_events\n\nOptional `query`: semantic over event descriptions. No query: ordered by most recent development activity.\n\nTimestamp filters gate on **development activity**: an older event still appears if it had a development recorded in-window. No activity → `[]`.\n\n| Param | Notes |\n|-------|-------|\n| `query` | Optional. Max 2000 chars. |\n| `symbols` | Tickers, max 8. Match any. Exact as stored. Gates events via development stakeholder involvement; does not filter embedded `recent_developments`. |\n| `event_type` | Exact free-form (`merger_acquisition`, `earnings`, `product_launch`, `executive_succession`, …) |\n| `limit` | Default 5, max 10 |\n| `developments_per_event` | Default 3, max 5, **0 allowed** (event cards only — cheap scanning) |\n| `include_future_developments` | Default true. Filters on `occurrence_timestamp` vs now/end — does not drop past-dated `scheduled` items |\n| `detail` | `full` \\| `essential` only (no `standard`). Prefer `essential` when scanning. |\n\nEmbedded `recent_developments` are summaries (no rationale/stakeholders/sources). Escalate with `retrieve_event_developments` or `search_developments` for development packages.\n\n---\n\n## retrieve_event_developments\n\nRequired: `event_id`. Returns event metadata + developments ordered by `occurrence_timestamp` DESC. Packages follow `detail` (default `full`; prefer `standard`).\n\n| Param | Notes |\n|-------|-------|\n| `limit` | Default 5, max 20 |\n| `start_timestamp` / `end_timestamp` | Filter on development **recording** time (useful for polling new packages) |\n| `include_future_developments` | Default true |\n| `detail` | Default `full`. Prefer `standard`. |\n\nMissing event → 404.\n\n---\n\n## Workflow\n\n| User intent | Approach |\n|-------------|----------|\n| “Who is affected by X?” | `search_developments` → read stakeholder impacts; cite quotes |\n| “What’s the Tesla earnings story this year?” | `search_developments` or `search_events` → take `event_id` → `retrieve_event_developments` |\n| “Any big M&A?” | `search_events` with `event_type: merger_acquisition` |\n| “Negative for GOOGL?” | `symbols: [\"GOOGL\"]`, `max_impact_score: -0.5` |\n| “What just printed that’s important?” | No-query search + `min_importance_score: 0.8` |\n| “Headline triage / first print” | Wire first; escalate here for structured impact |\n| “Reconstruct this development as of T” | `retrieve_development` with `end_timestamp` |\n\n1. Decide grain: atomic impact update (developments) vs storyline cluster (events).\n2. Prefer ticker + score filters for desk questions; prefer semantic query for themes.\n3. Keep `limit` small; set `detail: \"standard\"` (or `essential` on `search_events`); set `developments_per_event` low (or 0) when scanning events.\n4. `search_developments` already returns packages at your chosen `detail` — do not call `retrieve_development` on those ids unless you need as-of or a richer `detail`. Expand storylines with `retrieve_event_developments`.\n5. Collapse near-duplicate developments under the same event before briefing.\n6. Hand off to Wire for live novelty, your native web search tool for open-web research, `retrieve_entity` for identity packages.\n\n---\n\n## Limitations\n\n- Near-duplicate developments can exist as separate ids for the same real-world fact — dedupe by event + occurrence window + name similarity.\n- Stakeholders are **PUBLIC_COMPANY + ticker only** — no countries/commodities/people as stakeholders.\n- Ticker strings are exact and case-sensitive (`TSLA` ≠ `tsla`), max 8 chars.\n- `development_type` / `event_type` are not closed enums — inventing labels yields empty results.\n- Cosine not exposed for thresholding.\n- Packages are heavy at `full` — bad default for large scans without `detail: \"standard\"` / `essential`, tight limits, or `developments_per_event: 0`.\n- `scheduled` status can linger after occurrence time.\n- Not filterable by Ultralayer entity ids; use tickers or semantic query text.\n\n---\n\n## FAQ\n\n**Q: Wire already has Tesla headlines — why developments?**  \nA: Developments add multi-ticker impact scores, rationales, and event clustering. Wire tells you it printed; developments tell you who is in the blast radius and why.\n\n**Q: Why did `development_type: \"earnings\"` return nothing?**  \nA: Earnings prints are often typed `financial_update`; `earnings` appears more as an event_type. Discover types from hits.\n\n**Q: `include_future_developments: false` still showed “scheduled” items.**  \nA: Filter is on `occurrence_timestamp` vs now, not on status label. Past-dated schedules remain.\n\n**Q: Can I filter by Ultralayer entity name `Tesla, Inc.`?**  \nA: No. Use `symbols: [\"TSLA\"]` or semantic query text.\n\n**Q: search_events with a July window returned an older long-running event — bug?**  \nA: Timestamps gate development activity. Old events with new developments in-window correctly appear.\n\n**Q: retrieve_development as-of before the print 404s.**  \nA: Expected — no version existed yet.\n\n**Q: search_events vs search_developments?**  \nA: Events for clusters/lifecycles (summaries); developments for atomic updates + stakeholder math (full packages). Typical flow: search either → expand with `retrieve_event_developments` when you need the timeline; use `retrieve_development` only for a known id or as-of.\n"
}