{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Free-text search over company name and ticker. Case-insensitive. E.g. 'Apple', 'AAPL', 'Microsoft', 'semiconductor'."
    },
    "cik": {
      "type": "string",
      "pattern": "^\\d{1,10}$",
      "description": "SEC CIK identifier (exact match). E.g. '0000320193' for Apple."
    },
    "sic_code": {
      "type": "string",
      "pattern": "^\\d{4}$",
      "description": "4-digit SIC industry code. E.g. '7372' for Prepackaged Software."
    },
    "is_active": {
      "type": "boolean",
      "description": "Filter on whether the LISTING is current. true = currently trading; false = superseded listings only (delisted, or a ticker that moved to a new registrant). Omit to return both."
    },
    "is_sp500": {
      "type": "boolean",
      "description": "Filter to current S&P 500 members only."
    },
    "include_inactive": {
      "type": "boolean",
      "default": true,
      "description": "Whether delisted / superseded listings may appear in results. Defaults to true — this is a survivorship-free product, so a search must not silently hide dead companies by default. Set to false to restrict to currently-active listings only (equivalent to `is_active: true`, but as a search-scope toggle rather than a hard filter). If `is_active` is also supplied, `is_active` wins."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 25,
      "description": "Maximum number of results to return (1–50). Defaults to 25."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "fiscal_year": {
      "type": "integer",
      "minimum": 1993,
      "maximum": 2030,
      "description": "Fiscal year (YYYY). Omit to return the most recent available years."
    },
    "period": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly"
      ],
      "default": "annual",
      "description": "Filing period granularity. Annual uses 10-K; quarterly uses 10-Q."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias for backtesting. Omit for the full dataset."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "default": 5,
      "description": "Maximum number of periods to return (1–40). Defaults to 5."
    },
    "strict": {
      "type": "boolean",
      "default": false,
      "description": "When true, fail with PLAN_LIMIT_EXCEEDED if the plan cannot satisfy the requested limit. Default false: return what's available and explain the gap in _meta.truncation."
    },
    "lineage_detail": {
      "type": "string",
      "enum": [
        "off",
        "compact",
        "full"
      ],
      "default": "compact",
      "description": "Per-period provenance envelope + per-metric availability/provenance sidecars. 'compact' (default) returns source_filing + source_url (the SEC Inline-XBRL viewer with every tagged fact highlighted when the filing is iXBRL, else the rendered document, else the filing index) + sec_url/document_url/inline_viewer_url + restated flag, plus lean per-metric availability + fact_id + source_filing. 'full' adds first_filed_at + accepted_at + per-metric source_url + computed inputs[]. 'off' omits all provenance."
    },
    "response_format": {
      "type": "string",
      "enum": [
        "flat",
        "envelope"
      ],
      "default": "flat",
      "description": "Output shape. 'flat' (default) returns the legacy `metrics` object plus the additive `metrics_availability`/`metrics_provenance`/`metrics_display` sidecars — `metrics_display` holds each figure already rendered for prose (\"$402.83B\"), and you should quote it verbatim rather than reformatting `metrics` yourself. 'envelope' additionally attaches `metric_envelopes` — one canonical {metric,value,unit,scale,period,availability,provenance,display} object per metric. Both shapes carry the same display strings."
    },
    "min_confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Withhold any metric whose backing fact scores below this confidence [0, 1]. The score is a PENALTY FROM EVIDENCE — every fact starts at 1.0 and is docked only for something checkable: a failed accounting identity (-0.40), a later filing that revised the number (-0.20), an unaudited filing (-0.05). It is NOT a function of age: a clean 1995 fact scores the same as a clean 2026 one. Guide: 0.95 = 'no evidence against this number' (the normal case — ~99.9% of facts, every year); 0.80 = tolerate a fact a later filing revised; 0.60 = tolerate a filing whose accounting identities failed. A withheld metric is reported as availability:'suppressed' — never dropped silently, and never as 'not_reported', which would claim the company did not file it. Facts with no confidence score are withheld too (fail closed)."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "fiscal_year": {
      "type": "integer",
      "minimum": 1993,
      "maximum": 2030,
      "description": "Fiscal year (YYYY). Omit to return most recent periods."
    },
    "period": {
      "type": "string",
      "enum": [
        "annual",
        "quarterly"
      ],
      "default": "annual",
      "description": "Filing period granularity. Annual uses 10-K; quarterly uses 10-Q."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time date (YYYY-MM-DD). Only returns data with accepted_at on or before this date. Eliminates look-ahead bias for backtesting."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "default": 5,
      "description": "Maximum number of periods to return (1–40). Defaults to 5."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "profitability",
          "liquidity",
          "leverage",
          "efficiency",
          "per_share",
          "owner_earnings",
          "forensic",
          "growth",
          "rank",
          "valuation"
        ]
      },
      "maxItems": 10,
      "description": "Ratio categories to include (see the enum). Omit to return every category this ticker has. `valuation` (pe_ratio, pb_ratio, ev_ebitda, market_cap, dividend_yield) is LIVE since schema 2.18.0 — price-derived, period-end-aligned, not strictly PIT. Availability is per-ticker (the envelope lists this ticker's available_categories)."
    },
    "fiscal_period": {
      "type": "string",
      "enum": [
        "FY",
        "TTM",
        "Q1",
        "Q2",
        "Q3",
        "Q4"
      ],
      "description": "Filter to a specific fiscal period type. Use 'TTM' for trailing twelve months. Omit to return both annual (FY) and TTM rows."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Historical cutoff (canonical cross-tool date param). PIT by SEC accepted_at when the ratio data carries it (latest value knowable on/before the date, zero look-ahead, _meta.pit_safe=true), else by ratio.period_end (pit_safe=false). For guaranteed accepted_at PIT use get_company_fundamentals."
    },
    "period_end_before": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Alias of as_of_date (as_of_date preferred — the canonical name). Returns ratios with period_end on or before this date."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 5,
      "description": "Number of distinct period_end dates to return (1–20). Defaults to 5. Within each period, all matching ratio_names are included."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "form_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "10-K",
          "10-Q",
          "8-K",
          "20-F",
          "40-F",
          "10-K/A",
          "10-Q/A",
          "20-F/A",
          "40-F/A"
        ]
      },
      "maxItems": 9,
      "default": [
        "10-K",
        "10-Q"
      ],
      "description": "Filing form types to include. Defaults to 10-K and 10-Q."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Inclusive lower bound on filing_date (YYYY-MM-DD). E.g. '2023-01-01'."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Inclusive upper bound on filing_date (YYYY-MM-DD). E.g. '2023-12-31'."
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20
      },
      "maxItems": 30,
      "description": "8-K item codes to filter by. E.g. ['1.01'] for material agreements, ['2.01'] for asset acquisitions, ['5.02'] for director/officer changes. Only relevant when form_types includes '8-K'."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10,
      "description": "Maximum number of filings to return (1–50). Defaults to 10."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "lookback_years": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 5,
      "description": "Number of fiscal years to look back from the most recent filing (1–20). Defaults to 5 years for a full capital allocation cycle."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Subject company ticker or CIK, e.g. AAPL or '0000320193'. Peers are auto-selected by SIC code."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "profitability",
          "liquidity",
          "leverage",
          "efficiency",
          "per_share",
          "owner_earnings",
          "valuation"
        ]
      },
      "maxItems": 7,
      "default": [
        "profitability",
        "valuation",
        "leverage"
      ],
      "description": "Ratio categories to include in the comparison. Defaults to profitability, valuation, and leverage."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Historical date (canonical cross-tool date param). Peers are the companies listed on this date, including ones delisted since, ranked by S&P 500 membership on this date. Figures are point-in-time by SEC acceptance time when the ratio data carries it (_meta.pit_safe=true), else limited to periods ending on or before this date (_meta.pit_safe=false)."
    },
    "period_end_before": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Alias of as_of_date (as_of_date preferred — the canonical name). Only include ratios with period_end on or before this date."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5,
      "description": "Maximum number of peers to return alongside the subject company (1–10). Defaults to 5."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "index": {
      "type": "string",
      "enum": [
        "sp500",
        "russell1000",
        "russell2000",
        "russell3000"
      ],
      "description": "Index filter. 'sp500' (~500 large caps, curated history back to 1996), 'russell1000' (~1000 large/mid), 'russell2000' (~2000 small caps), 'russell3000' (~3000 broad market) — the three Russell indices carry fund-derived history back to 2000-09-30 at medium confidence, with observation spacing that widens before 2007. Omit for no index filter (sector-only or full universe queries)."
    },
    "sector": {
      "type": "string",
      "maxLength": 100,
      "description": "Sector filter (case-insensitive substring) over the SIC-derived, GICS-aligned label (not licensed GICS — see tool description). E.g. 'Technology', 'Energy'."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Historical date (YYYY-MM-DD) for survivorship-free construction. Index queries use index_membership join/leave dates (entrants after the date excluded, later-removed members kept); sector queries use security valid_from/valid_to. Omit for the current universe."
    },
    "is_active": {
      "type": "boolean",
      "description": "Filter to active (currently trading) companies only. Omit to include all. WARNING: setting this to true on a HISTORICAL query reintroduces survivorship bias — companies that were active on as_of_date but later went bankrupt or got acquired will be filtered out.  Leave unset for true PIT backtests."
    },
    "include_share_classes": {
      "type": "boolean",
      "default": false,
      "description": "false (default) collapses to one row per CIK (index-provider convention — BRK counts once, not BRK-A + BRK-B). true returns every share-class row (GOOG and GOOGL separately) — for security-level analysis only."
    },
    "as_of_basis": {
      "type": "string",
      "enum": [
        "effective",
        "announcement"
      ],
      "default": "effective",
      "description": "Which date column drives historical construction. 'effective' (default) = effective_date/removal_date (first trading day; passive replication). 'announcement' = announcement_date/removal_announcement_date (S&P's public-announcement day; for inclusion-arb backtests) — rows with NULL announcement_date (mostly pre-2015) are skipped."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3500,
      "default": 100,
      "description": "Maximum companies to return (1–3500). Defaults to 100 — which is SMALLER THAN EVERY INDEX, so the default call returns a slice, reports `limit_truncated: true` and withholds `survivorship_free`. `universe_size` always states the full matched count whatever you set here. Raising it is NOT sufficient on its own: at most 250 rows are inlined per call, so a large limit still returns a page (`complete: false`) until you walk it with `offset`. Universe is deduped to one row per CIK, so for a usable backtest universe set this near the index size (SP500 ~505, Russell 3000 ~3050) and page with `offset`."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Zero-based row offset for paging a large universe. At most 250 rows are inlined per call; when more match, the response carries a `truncation` envelope — pass its `next_offset` here (keeping the same `limit`) to fetch the next page. Defaults to 0."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "dataset_type": {
      "type": "string",
      "enum": [
        "fact",
        "ratio",
        "filing",
        "references",
        "index_membership"
      ],
      "description": "Dataset to access. 'fact' requires ticker (per-entity partition). All others are full-universe tables."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^([A-Za-z][A-Za-z0-9.\\-]{0,9}|\\d{1,10})$",
      "description": "Required when dataset_type is 'fact'. Resolves to the per-entity fact/{CIK}.parquet partition for that company."
    }
  },
  "required": [
    "dataset_type"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "table": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z][a-z0-9_]*$",
      "description": "Filter to a single table name (e.g. 'fact', 'entity', 'references'). Omit to return the full schema for all tables."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "Case-insensitive substring matched against each playbook's name, title, and description — e.g. 'smart money', 'thesis', 'backtest'. Omit to list all."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "SOP slug from list_sops, e.g. 'equity_research_brief'."
    },
    "args": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Playbook arguments as string values, e.g. { ticker: 'AAPL', depth: 'full' }. Omit to read the generic template with {{ARG}} placeholders."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "fact_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "Deterministic fact identity hash: SHA-256(entity_id|accession_id|concept|period_end|unit). 64-char lowercase hex. Use this when you already have the hash from a previous query. Provide either fact_id OR concept (not both required, but at least one must be set)."
    },
    "concept": {
      "type": "string",
      "enum": [
        "TotalRevenue",
        "CostOfRevenue",
        "GrossProfit",
        "OperatingIncome",
        "OperatingExpenses",
        "ResearchAndDevelopment",
        "NetIncome",
        "EPSDiluted",
        "TotalAssets",
        "TotalLiabilities",
        "StockholdersEquity",
        "StockholdersEquityIncludingNCI",
        "CashAndEquivalents",
        "TotalDebt",
        "OperatingCashFlow",
        "CAPEX",
        "Dividends",
        "ShareBuyback",
        "DebtIssuance",
        "DebtRepayment",
        "Acquisitions",
        "Divestitures"
      ],
      "description": "Standard concept to look up the most recently known fact for (see the enum for the full fundamentals + capital-allocation set). Use this when you don't have a fact_id. Provide either concept OR fact_id."
    },
    "period_end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "[DEPRECATED — pass `as_of_date` instead.] Filing-acceptance cutoff (YYYY-MM-DD) used with `concept`; despite the name it filters on filing accepted_at, not the returned fact's period_end. Kept one release for back-compat."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) used with `concept` — returns the latest fact whose 10-K/10-Q was accepted by SEC on or before this date (true PIT, no lookahead; any calendar date works). Canonical name across the suite; supersedes the legacy `period_end`."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "facts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10,
            "pattern": "^[A-Za-z0-9.\\-]+$",
            "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'. The company the fact belongs to; a fact_id is only resolvable against its own filer."
          },
          "fact_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "Deterministic fact identity hash: SHA-256(entity_id|accession_id|concept|period_end|unit), 64-char lowercase hex, exactly as a previous tool result gave it to you. Never invent one."
          }
        },
        "required": [
          "ticker",
          "fact_id"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "The facts to verify, 1–50 of them. Group a report's whole citation list here rather than calling once per figure. Duplicate (ticker, fact_id) pairs are resolved once and returned once, in first-seen order."
    }
  },
  "required": [
    "facts"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "period_a": {
      "type": "string",
      "minLength": 2,
      "maxLength": 10,
      "description": "Earlier fiscal period. Format: 'FY2023' for annual or 'Q1-2023' for quarterly."
    },
    "period_b": {
      "type": "string",
      "minLength": 2,
      "maxLength": 10,
      "description": "Later fiscal period. Format: 'FY2024' for annual or 'Q1-2024' for quarterly."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias for backtesting."
    }
  },
  "required": [
    "ticker",
    "period_a",
    "period_b"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "If provided, show only this ticker's factor scores (single-entity mode). Omit to screen the full universe."
    },
    "sector": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Filter to a specific sector (case-insensitive partial match). E.g. 'Technology', 'Healthcare'."
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "roe_rank",
        "gross_margin_rank",
        "operating_margin_rank",
        "net_profit_margin_rank",
        "revenue_growth_yoy_rank",
        "fcf_to_assets_rank",
        "debt_to_equity_rank",
        "asset_turnover_rank",
        "current_ratio_rank",
        "piotroski_f_score_rank",
        "composite_rank"
      ],
      "default": "composite_rank",
      "description": "Which factor rank to sort by (see the enum). Defaults to composite_rank. An unrecognized column is rejected with INVALID_ARGUMENT (no silent fallback)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Number of results to return (1-100). Defaults to 25."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Zero-based row offset for paging within the requested `limit` window. At most 250 rows are inlined per call; if the response carries a `truncation` envelope, pass its `next_offset` here. Defaults to 0."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD). When set, the screen is reconstructed as of this date via factor_scores.accepted_at — each entity ranked at its latest-knowable period, zero look-ahead, survivorship-free. Omit for the latest snapshot."
    },
    "exclude_outliers": {
      "type": "boolean",
      "default": false,
      "description": "Optional data-quality guard (default false). When true, additionally drops rows with implausible raw factor values (non-finite, or e.g. asset_turnover > 50x, |FCF/assets| > 10) from shell companies with near-zero denominators. Rows that do not join to a company (null symbol) are ALWAYS omitted in full-universe mode, regardless of this flag."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time filter: only return signals with accepted_at on or before this date. Use for backtesting to avoid look-ahead bias."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 40,
      "default": 8,
      "description": "Maximum number of periods to return (1–40), most recent first. Defaults to 8 — covers 2 years of quarterly signals plus their TTM equivalents. earnings_signals.parquet currently emits one row per (entity, period_end); older rows surface here as more historical periods are published."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-f0-9]+$",
      "description": "Fetch exactly one event by its id (from a prior response)."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Restrict to one company — ticker (e.g. 'AAPL') or CIK (e.g. '0000320193')."
    },
    "sector": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Restrict to one GICS-style sector (e.g. 'Technology')."
    },
    "severity": {
      "type": "string",
      "enum": [
        "high",
        "medium",
        "low"
      ],
      "description": "high = |Δ|≥10%, medium = ≥2%, low = ≥0.5%."
    },
    "min_abs_delta_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Only events whose absolute restatement is at least this percent (e.g. 5 = ≥5% swings)."
    },
    "max_importance": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Only lines at or above this importance tier: 1 = headline only (revenue, net income, EPS, total assets, operating cash flow), 2 = + primary statement lines, 3 = everything incl. footnotes. Severity says how far a number moved; importance says whether anyone cares."
    },
    "amendments_only": {
      "type": "boolean",
      "description": "Only restatements that arrived in an AMENDED filing (10-K/A, 10-Q/A) — the company formally telling the SEC it got a number wrong. The sharpest cut there is: it separates real restatements from routine re-files (a next-year 10-K carrying a revised comparative)."
    },
    "disclosure": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "non_reliance",
          "amended",
          "undisclosed"
        ]
      },
      "minItems": 1,
      "maxItems": 3,
      "description": "Filter by HOW the company told the market. 'non_reliance' = it filed an 8-K Item 4.02 ('Non-Reliance on Previously Issued Financial Statements') — formally telling the SEC not to rely on what it already reported. The loudest signal in US disclosure, and rare. 'amended' = corrected in a 10-K/A or 10-Q/A. 'undisclosed' = the value changed inside a ROUTINE 10-Q or 10-K: no amendment, no 4.02, the old number is simply gone. ~94% of events. Anyone can parse an 8-K, so anyone can list what companies ANNOUNCED; finding what they didn't requires every vintage back to 1993."
    },
    "filed_since": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Only restatements FILED on or after this date — the 'what changed recently' window."
    },
    "sort": {
      "type": "string",
      "enum": [
        "recent",
        "significance"
      ],
      "default": "recent",
      "description": "'recent' = newest restating filing first (a market-wide radar). 'significance' = importance tier, then swing size (one company's history)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Page size (1-100, default 25)."
    },
    "cursor": {
      "type": "string",
      "maxLength": 20,
      "pattern": "^\\d+$",
      "description": "Opaque pagination cursor from a prior response's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "bug",
        "feature_request",
        "experience",
        "data_quality",
        "other"
      ],
      "description": "What kind of feedback this is: 'bug' (something broke), 'feature_request' (something missing), 'experience' (UX / clarity / docs), 'data_quality' (a wrong/missing/stale figure), or 'other'."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "The feedback body (1–4000 chars). Be specific: what you expected, what happened, and any reproduction steps. May contain the user's own words — it is stored for triage and never used for arithmetic."
    },
    "subject": {
      "type": "string",
      "maxLength": 140,
      "description": "Optional short title (≤140 chars) summarizing the feedback."
    },
    "severity": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "description": "Optional impact classification: 'low', 'medium', or 'high'."
    },
    "surface": {
      "type": "string",
      "enum": [
        "mcp",
        "workspace",
        "sdk",
        "dashboard",
        "api"
      ],
      "description": "Optional product surface the feedback concerns: 'mcp', 'workspace', 'sdk', 'dashboard', or 'api'."
    },
    "context": {
      "type": "object",
      "additionalProperties": {},
      "description": "Optional free-form context object (stored as JSON), e.g. { tool: 'get_company_fundamentals', ticker: 'AAPL', request_id: 'abc123' }. Avoid secrets."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional client-supplied key (1–64 chars). For authenticated callers, reusing the same key files the feedback exactly once — safe to retry on a network error. Ignored for guest/sample callers (no account to scope dedup to)."
    },
    "sentiment": {
      "type": "string",
      "enum": [
        "positive",
        "negative",
        "correction"
      ],
      "description": "Optional sentiment of this feedback: 'positive' (worked well), 'negative' (something was wrong), or 'correction' (you are supplying the right value)."
    },
    "reason": {
      "type": "string",
      "enum": [
        "wrong_number",
        "bad_citation",
        "missing_data",
        "wrong_company",
        "formatting",
        "hallucinated_fact",
        "tool_error",
        "coverage_gap",
        "other"
      ],
      "description": "Optional structured error-mode reason: 'wrong_number', 'bad_citation', 'missing_data', 'wrong_company', 'formatting', 'hallucinated_fact', 'tool_error', 'coverage_gap', or 'other'."
    },
    "target_type": {
      "type": "string",
      "enum": [
        "chat_message",
        "report",
        "thesis",
        "claim",
        "tool_call",
        "schema",
        "other"
      ],
      "description": "Optional kind of artifact the feedback targets: 'chat_message', 'report', 'thesis', 'claim', 'tool_call', 'schema', or 'other'."
    },
    "target_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional id of the artifact this feedback targets (e.g. a report or thesis id)."
    },
    "request_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional `_meta` request id of the turn that produced the artifact, for correlation."
    },
    "fact_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional disputed `fact_id` (for wrong_number / bad_citation feedback)."
    },
    "expected_value": {
      "type": "string",
      "maxLength": 4000,
      "description": "Optional caller-asserted correct value, in your own words. Stored verbatim for triage — NEVER computed or trusted as data."
    }
  },
  "required": [
    "category",
    "message"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "target_type": {
      "type": "string",
      "enum": [
        "chat_message",
        "report",
        "thesis",
        "claim",
        "tool_call",
        "schema",
        "other"
      ],
      "description": "REQUIRED. The kind of artifact this feedback is about: 'chat_message', 'report', 'thesis', 'claim', 'tool_call', 'schema', or 'other'."
    },
    "target_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "REQUIRED. The id of the artifact this feedback targets (a report id, thesis id, claim id, message id, tool-call id, or table/schema name)."
    },
    "sentiment": {
      "type": "string",
      "enum": [
        "positive",
        "negative",
        "correction"
      ],
      "description": "REQUIRED. How you judge the artifact: 'positive' (it was right/useful), 'negative' (it was wrong/unhelpful), or 'correction' (you are supplying the right value via `expected_value`)."
    },
    "reason": {
      "type": "string",
      "enum": [
        "wrong_number",
        "bad_citation",
        "missing_data",
        "wrong_company",
        "formatting",
        "hallucinated_fact",
        "tool_error",
        "coverage_gap",
        "other"
      ],
      "description": "Optional structured error-mode: 'wrong_number', 'bad_citation', 'missing_data', 'wrong_company', 'formatting', 'hallucinated_fact', 'tool_error', 'coverage_gap', or 'other'."
    },
    "request_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional `_meta` request id of the turn that produced the artifact. Folded into the idempotency key so a retried submission of the same judgement files once."
    },
    "fact_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional disputed `fact_id` (most useful for wrong_number / bad_citation)."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z][A-Za-z0-9.\\-]{0,9}$",
      "description": "Optional ticker the disputed figure belongs to (e.g. 'AAPL', 'BRK.B'). ALWAYS send this alongside `fact_id` — a `fact_id` is a one-way hash that does not contain the symbol, so without it nobody can locate the filing and your report cannot be checked against the source. Supplying it is what turns a complaint into a verifiable one."
    },
    "expected_value": {
      "type": "string",
      "maxLength": 4000,
      "description": "Optional: what the value SHOULD have been, in your own words. Stored verbatim for triage — NEVER computed, restated, or trusted as data by Valuein."
    },
    "message": {
      "type": "string",
      "maxLength": 4000,
      "description": "Optional free-text detail (≤4000 chars). What you expected and what happened."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional explicit dedupe key (1–64 chars). Used to dedupe when no `request_id` is supplied; safe to retry on a network error."
    }
  },
  "required": [
    "target_type",
    "target_id",
    "sentiment"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "lookback_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650,
      "default": 90,
      "description": "How many days back from today to scan transactions for. Ignored when as_of_date is set."
    },
    "transaction_codes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "P",
          "S",
          "A",
          "M",
          "F",
          "G",
          "J"
        ]
      },
      "description": "SEC transaction codes to keep (uppercase, single-letter):  P=purchase, S=sale, A=grant, M=option exercise, F=tax withholding, G=gift, J=other.  Unknown codes are rejected.  Omit to include all codes."
    },
    "roles_in": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Officer",
          "Director",
          "TenPercentOwner",
          "Other"
        ]
      },
      "description": "Insider roles to keep. Omit to include any role."
    },
    "min_shares": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum |shares| per transaction. Omit for no floor."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time date (YYYY-MM-DD).  Only returns transactions with accepted_at <= this date — eliminates look-ahead bias.  When set, lookback_days is ignored."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "default": 100,
      "description": "Maximum rows to return. Default 100, max 500."
    },
    "lineage_detail": {
      "type": "string",
      "enum": [
        "off",
        "compact",
        "full"
      ],
      "default": "compact",
      "description": "Per-row provenance envelope. 'compact' (default) returns source_filing + source_url. 'full' adds accepted_at. 'off' omits lineage."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol of the issuer — or a CIK (SEC identifier)."
    },
    "period_end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Quarter-end of the 13F reporting period (YYYY-MM-DD). Omit to use the latest period available. This is a REPORTING period, NOT a point-in-time cutoff — use as_of_date for that."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD): only 13F filings ACCEPTED by SEC on or before this date are considered, applied BEFORE the latest period is resolved. A 13F/A amendment or late filing accepted after this date is excluded (zero look-ahead) — use this for survivorship-free backtests. Omit for the latest knowable book."
    },
    "top_n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 25,
      "description": "Maximum holders to return, ranked by market_value_usd. Default 25, max 200."
    },
    "lineage_detail": {
      "type": "string",
      "enum": [
        "off",
        "compact",
        "full"
      ],
      "default": "compact",
      "description": "Per-row provenance envelope. compact / full / off."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "filer_cik": {
      "type": "string",
      "pattern": "^\\d{1,10}$",
      "description": "CIK of the 13F filer (1-10 digits; will be zero-padded to 10).  Preferred over filer_name when known."
    },
    "filer_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Filer name to fuzzy-match against entity.name.  Case-insensitive substring match.  Multiple matches raise INVALID_ARGUMENT — use filer_cik in that case."
    },
    "period_end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Quarter-end (YYYY-MM-DD).  Omit to use latest available.  This is a REPORTING period, NOT a point-in-time cutoff — use as_of_date for that."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD): only 13F filings ACCEPTED by SEC on or before this date are considered, applied BEFORE the latest + prior periods (and the QoQ basis) are resolved. A 13F/A amendment or late filing accepted after this date is excluded (zero look-ahead). Omit for the latest knowable portfolio."
    },
    "top_n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 25,
      "description": "Maximum positions to return, ranked by market_value_usd. Default 25."
    },
    "lineage_detail": {
      "type": "string",
      "enum": [
        "off",
        "compact",
        "full"
      ],
      "default": "compact",
      "description": "Per-row provenance envelope."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol of the issuer — or a CIK (SEC identifier)."
    },
    "schedule_filter": {
      "type": "string",
      "enum": [
        "13D",
        "13G",
        "both"
      ],
      "default": "both",
      "description": "Which schedule(s) to return.  '13D' = activist (intent to influence). '13G' = passive.  'both' = no filter."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "PIT filter on accepted_at — only filings on or before this date."
    },
    "latest_only": {
      "type": "boolean",
      "default": true,
      "description": "When true (default), keep only the most recent filing per (filer, schedule prefix) — typically what analysts want.  Set false to see the full filing history."
    },
    "collapse_groups": {
      "type": "boolean",
      "default": false,
      "description": "When true, fold multi-reporting-person filings into a single row, with secondary persons in the ``persons[]`` field.  Default false: each person stays as its own row."
    },
    "lookback_days": {
      "type": "integer",
      "minimum": 7,
      "maximum": 3650,
      "default": 365,
      "description": "Window for the going_active (13G → 13D) detection. Default 365 days."
    },
    "lineage_detail": {
      "type": "string",
      "enum": [
        "off",
        "compact",
        "full"
      ],
      "default": "compact",
      "description": "Per-row provenance envelope."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Issuer ticker symbol — or a CIK (SEC identifier)."
    },
    "lookback_days": {
      "type": "integer",
      "minimum": 7,
      "maximum": 3650,
      "default": 180,
      "description": "Days back from today to scan transactions for. Default 180."
    },
    "cluster_window_days": {
      "type": "integer",
      "minimum": 7,
      "maximum": 180,
      "default": 30,
      "description": "Sliding window for the cluster_flag detection. Default 30 days."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Issuer ticker symbol — or a CIK (SEC identifier)."
    },
    "top_n": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 25,
      "description": "Maximum holders to return, ranked by shares. Default 25."
    },
    "period_end": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "13F REPORTING period_end. Omit for latest. NOT a point-in-time cutoff — use as_of_date."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD): only filings ACCEPTED by SEC on or before this date are considered across all three sources (institutional via accepted_at, insider via accepted_at, blockholders via accepted_at). Excludes amendments/late filings accepted after this date (zero look-ahead). Omit for the latest knowable cap table."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Issuer ticker symbol — or a CIK (SEC identifier)."
    },
    "lookback_days": {
      "type": "integer",
      "minimum": 30,
      "maximum": 3650,
      "default": 90,
      "description": "Lookback window for insider + blockholder components. Default 90."
    },
    "weight_institutional": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.4,
      "description": "Weight applied to the institutional component (0–1)."
    },
    "weight_blockholder": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.4,
      "description": "Weight applied to the blockholder component (0–1)."
    },
    "weight_insider": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.2,
      "description": "Weight applied to the insider component (0–1)."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) applied to all three legs (institutional, insider, blockholder) via SEC accepted_at — filings accepted after this date are excluded so the composite is computed with zero look-ahead. Omit for the latest knowable signal."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "US-listed ticker. Case-insensitive — normalised to upper. E.g. 'AAPL'."
    },
    "view": {
      "type": "string",
      "enum": [
        "bull",
        "bear",
        "neutral"
      ],
      "description": "Directional view: bull (expect outperformance), bear (under), neutral (mean-revert)."
    },
    "conviction": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "1 = low conviction (gut feel) → 5 = high conviction (deep analysis)."
    },
    "horizon_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1825,
      "description": "Investment horizon in days. 1 day–5 years (1825d). The grader uses this to pick the as-of period."
    },
    "notes": {
      "type": "string",
      "maxLength": 4000,
      "description": "Free-form rationale, ≤4000 chars. Stored verbatim; trim before submitting."
    },
    "thesis_at_price_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Optional snapshot of the ticker's market price (integer cents) at thesis creation. Used by future versions of the grader that mix in price returns; null for now is fine."
    },
    "source_report_id": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional id of a report (from `create_report` / `publish_report`) that contains the supporting analysis."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional client-supplied key. If a previous `save_thesis` from the same user used this key, the existing thesis is returned instead of creating a duplicate."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "default": "private",
      "description": "Phase 3: 'private' (default) is owner-only; 'unlisted' is visible at a known direct URL; 'public' surfaces on the author's /[handle] profile and contributes to their reputation score."
    }
  },
  "required": [
    "ticker",
    "view",
    "conviction",
    "horizon_days"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Filter to theses on this ticker (case-insensitive)."
    },
    "view": {
      "type": "string",
      "enum": [
        "bull",
        "bear",
        "neutral"
      ],
      "description": "Filter to a single view."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "closed",
        "archived",
        "all"
      ],
      "default": "active",
      "description": "'active' (default) hides archived theses; pass 'all' to include them."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Page size, 1–100. Defaults to 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 64,
      "description": "Pagination cursor returned by the previous `list_theses` call's `next_cursor`."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_thesis` or `list_theses`."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_thesis` or `list_theses`."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "thesis",
        "watchlist",
        "signal",
        "claim",
        "report"
      ],
      "description": "Which record type to restore. Citation overrides are not restorable."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The record's id. For a watchlist this is the `watchlist_id` returned by `delete_watchlist` — NOT its name, because deleting a watchlist frees its name for reuse."
    }
  },
  "required": [
    "kind",
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_thesis` or `list_theses`."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Snapshot date for the 'current' fundamentals window. Defaults to today UTC. The scorer picks the fiscal period closest to this date."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{4,80}$",
      "description": "Stripe customer_id of the target user. Defaults to the caller's own — leave it unset. Supplying a DIFFERENT customer_id is restricted to Valuein's internal scoring service and is rejected on every plan, Institutional included."
    },
    "max": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500,
      "description": "Soft cap on theses scored per call. Defaults to 100. The frontend cron walks users serially so a low cap per user keeps each MCP request bounded."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Snapshot date for the 'current' fundamentals window. Defaults to today UTC."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "workflow_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40,
      "description": "Workflow id returned by the frontend workflow builder."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "US-listed ticker the workflow should run against, e.g. 'AAPL'. Pass either `ticker` (single) or `tickers` (batch up to 50). Exactly one is required."
    },
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Batch mode — array of US-listed tickers, up to 50. When provided, the response has `plans[]` (one plan per ticker) instead of `plan`. Parity with the frontend batch-runner so agents can request 'plan over my watchlist' in a single call."
    }
  },
  "required": [
    "workflow_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "minLength": 4,
      "maxLength": 80,
      "description": "Target user's Stripe customer_id (resolved by the frontend from the handle)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Max public theses to return. Defaults to 20."
    }
  },
  "required": [
    "customer_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_thesis` or `list_theses`."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "unlisted",
        "public"
      ],
      "default": "public",
      "description": "`public` (default) → profile + reputation; `unlisted` → direct-link-only, off the profile. To revert to private, use unpublish_thesis."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_thesis` or `list_theses`."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "statement": {
      "type": "string",
      "minLength": 8,
      "maxLength": 2000,
      "description": "The atomic, falsifiable statement. One claim, not a paragraph."
    },
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "Entities referenced (uppercased). 1 for most claims; 2+ for a comparison claim."
    },
    "claim_type": {
      "type": "string",
      "enum": [
        "assertion",
        "prediction",
        "judgment"
      ],
      "description": "Epistemic type — drives scoring. assertion=true now (verified vs data); prediction=future (resolves at horizon via verifiable_condition); judgment=qualitative (not auto-scored)."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "financial",
          "valuation",
          "operational",
          "competitive",
          "structural",
          "strategic",
          "macro",
          "behavioral",
          "catalyst",
          "risk",
          "trend",
          "comparison",
          "causation",
          "liquidity",
          "governance",
          "guidance"
        ]
      },
      "maxItems": 6,
      "default": [],
      "description": "Topical labels (controlled vocab). Multi-valued; drives filtering + learning segmentation, not scoring."
    },
    "direction": {
      "type": "string",
      "enum": [
        "bullish",
        "bearish",
        "neutral"
      ],
      "description": "Directional polarity of the claim."
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Author confidence in [0,1]. Used as the Brier/log-loss weight when scored."
    },
    "eval_mode": {
      "type": "string",
      "enum": [
        "auto",
        "agent",
        "manual"
      ],
      "default": "agent",
      "description": "How the outcome is resolved: auto (deterministic grade vs data via verifiable_condition), agent (an LLM judges at resolution), manual (a human marks it)."
    },
    "verifiable_condition": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "metric": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "Canonical metric key, e.g. 'gross_margin', 'revenue_yoy', 'net_debt_to_ebitda'."
            },
            "op": {
              "type": "string",
              "enum": [
                "gt",
                "gte",
                "lt",
                "lte",
                "eq",
                "approx"
              ],
              "description": "Comparison operator the grader applies as: metric_value <op> threshold."
            },
            "threshold": {
              "type": "number",
              "description": "Numeric threshold the metric is compared against."
            },
            "unit": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 16
                },
                {
                  "type": "null"
                }
              ],
              "description": "Display unit ('%', 'x', 'usd') or null."
            }
          },
          "required": [
            "metric",
            "op",
            "threshold",
            "unit"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Machine-evaluable condition for eval_mode='auto'. Null otherwise."
    },
    "antecedent": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Scenario precondition — the claim only resolves when this holds. Null = unconditional."
    },
    "horizon_days": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 1825
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Resolution horizon in days (predictions). Null for assertions/judgments."
    },
    "evidence": {
      "type": "object",
      "properties": {
        "fact_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 128
          },
          "maxItems": 50,
          "description": "fact_ids backing the claim. Verified against live SEC data at save time (rejected if unresolvable)."
        },
        "source_urls": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          },
          "maxItems": 50,
          "description": "SEC EDGAR (or report) deep links for one-click human verification."
        },
        "source_links": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "The original stored source_url (verbatim)."
              },
              "sec_url": {
                "type": "string",
                "description": "EDGAR filing-index page — always resolves."
              },
              "document_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Direct link to the rendered primary document, or null."
              },
              "inline_viewer_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "SEC Inline-XBRL viewer on the rendered filing, or null when not iXBRL."
              }
            },
            "required": [
              "url",
              "sec_url",
              "document_url",
              "inline_viewer_url"
            ],
            "additionalProperties": false
          },
          "description": "On-read enrichment of source_urls with interactive SEC viewer links."
        }
      },
      "required": [
        "fact_ids",
        "source_urls"
      ],
      "additionalProperties": false,
      "default": {
        "fact_ids": [],
        "source_urls": []
      },
      "description": "Evidence grounding the claim."
    },
    "source_report_id": {
      "type": "string",
      "maxLength": 128,
      "description": "Optional id of a report that contains the supporting analysis."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "default": "private",
      "description": "'private' (default) owner-only; 'unlisted' visible at a direct URL; 'public' surfaces on the author's profile and contributes to the claim-accuracy reputation."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional client key for at-most-once semantics from a retrying agent."
    }
  },
  "required": [
    "statement",
    "tickers",
    "claim_type",
    "direction",
    "confidence"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Filter to claims referencing this ticker."
    },
    "claim_type": {
      "type": "string",
      "enum": [
        "assertion",
        "prediction",
        "judgment"
      ],
      "description": "Filter by epistemic type."
    },
    "tag": {
      "type": "string",
      "enum": [
        "financial",
        "valuation",
        "operational",
        "competitive",
        "structural",
        "strategic",
        "macro",
        "behavioral",
        "catalyst",
        "risk",
        "trend",
        "comparison",
        "causation",
        "liquidity",
        "governance",
        "guidance"
      ],
      "description": "Filter to claims carrying this topical tag."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "confirmed",
        "refuted",
        "expired",
        "stale",
        "needs_review",
        "all"
      ],
      "default": "all",
      "description": "Filter by lifecycle status, or 'all'."
    },
    "include_archived": {
      "type": "boolean",
      "default": false,
      "description": "Include soft-deleted claims."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Page size (max 100)."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous page's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by save_claim or list_claims."
    }
  },
  "required": [
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the claim to archive."
    }
  },
  "required": [
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the thesis (from save_thesis/list_theses)."
    },
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the claim (from save_claim/list_claims)."
    },
    "role": {
      "type": "string",
      "enum": [
        "supports",
        "refutes",
        "context"
      ],
      "description": "Relational role of the claim toward the thesis."
    }
  },
  "required": [
    "thesis_id",
    "claim_id",
    "role"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the thesis to unlink the claim from, as returned by save_thesis or list_theses."
    },
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the claim to unlink, as returned by save_claim or list_claims."
    }
  },
  "required": [
    "thesis_id",
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the thesis whose claims to list."
    }
  },
  "required": [
    "thesis_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the claim to resolve."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Snapshot date for the fundamentals window (auto mode). Defaults to today UTC."
    },
    "manual_status": {
      "type": "string",
      "enum": [
        "confirmed",
        "refuted",
        "expired",
        "stale",
        "needs_review"
      ],
      "description": "Provide to record a human/agent outcome instead of auto-grading."
    },
    "manual_score": {
      "anyOf": [
        {
          "type": "number",
          "minimum": -1,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Outcome score in [-1,1] for a manual resolution. Null for non-scored statuses."
    },
    "manual_reason": {
      "type": "string",
      "maxLength": 2000,
      "description": "Explanation for a manual resolution."
    }
  },
  "required": [
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{4,80}$",
      "description": "Target user's Stripe customer_id. Defaults to the caller's own — leave it unset. Supplying a DIFFERENT customer_id is restricted to Valuein's internal scoring service and is rejected on every plan, Institutional included."
    },
    "max": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500,
      "description": "Soft cap on claims scored per call (default 100)."
    },
    "as_of": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Snapshot date for the fundamentals window. Defaults to today UTC."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "minLength": 4,
      "maxLength": 80,
      "description": "Target user's Stripe customer_id (resolved by the frontend from the handle)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Max public claims to return. Defaults to 20."
    }
  },
  "required": [
    "customer_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_claim` or `list_claims`."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "unlisted",
        "public"
      ],
      "default": "public",
      "description": "`public` (default) → profile + reputation; `unlisted` → direct-link-only, off the profile. To revert to private, use unpublish_claim."
    }
  },
  "required": [
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "claim_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id returned by `save_claim` or `list_claims`."
    }
  },
  "required": [
    "claim_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Canonical fact identifier — usually returned in a citation's `fact_ids` array by get_report or any compute tool. Stable across report regenerations. Verified against live SEC data (scoped to `ticker`) before persistence — a fabricated or unresolvable fact_id is rejected."
    },
    "corrected_value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "User-corrected value, stringified. The frontend interprets it based on the fact's known datatype (number, string, ISO date)."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Ticker the fact belongs to (REQUIRED) — scopes fact_id resolution against live SEC data and denormalises the row for fast filtering (the workspace UI's 'my corrections on AAPL' view)."
    },
    "source_report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Optional report id the user was viewing when they applied the correction (provenance)."
    },
    "notes": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional free-form rationale, ≤500 chars."
    }
  },
  "required": [
    "fact_id",
    "corrected_value",
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Optional ticker filter, case-insensitive. Uppercased internally."
    },
    "fact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Optional fact_id filter — returns at most one row."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Maximum number of citation overrides to return (1–100). Defaults to 20."
    },
    "cursor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Cursor from the previous response's `next_cursor` — the updated_at of the last row on that page. Omit for first page."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fact_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Fact identifier whose citation override should be removed, as returned by save_citation_override or list_citation_overrides."
    }
  },
  "required": [
    "fact_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report the figure belongs to, as returned by create_report / list_my_reports / save_freeform_report."
    },
    "figure_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Opaque id you mint for one figure inside the report. Never parsed or validated beyond length — use the exact same key to update this figure's review later. Shape for a dataset-backed figure: 'fact:{fact_id}#{figure}', the figure lowercased and whitespace-collapsed as the report writes it ('fact:f_rev#$402.83b'); the Workspace mints 'raw:{hash}' for a figure with no fact, which only it can compute."
    },
    "state": {
      "type": "string",
      "enum": [
        "verified",
        "corrected",
        "external",
        "rejected"
      ],
      "description": "verified = traced to its filing and correct. corrected = wrong (supply corrected_value). external = legitimately not from Valuein data (analyst's own source). rejected = unsupported, should be removed from the report."
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "Optional free-text reviewer note (e.g. what was checked, or why it was rejected)."
    },
    "corrected_value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The correct value. REQUIRED when state='corrected'; must be omitted for every other state (a corrected_value on a non-corrected review is rejected)."
    }
  },
  "required": [
    "report_id",
    "figure_key",
    "state"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report to list figure reviews for."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Report identifier — from create_report, list_my_reports or search_reports. Resolves the run behind that report and adds the human_review + sources sections. Pass this OR run_id, not both."
    },
    "run_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Run identifier, as returned by list_agent_runs. Pass this OR report_id, not both."
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "pdf"
      ],
      "default": "json",
      "description": "json (default) = the assembled file inline. pdf = a presigned download URL for the branded compliance PDF — the human-facing artifact; rendered fresh on every call, never cached."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report to certify, as returned by create_report / list_my_reports / save_freeform_report. Must be authored by the calling customer."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report to verify, as returned by create_report / list_my_reports / save_freeform_report. Must be authored by the calling customer."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Unique-per-user display name."
    },
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10
      },
      "minItems": 1,
      "maxItems": 500,
      "description": "US tickers. Normalised to uppercase, deduped."
    },
    "criteria": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional free-form screening criteria description."
    },
    "weights": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "exclusiveMinimum": 0
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional relative position weights, ticker → number (e.g. {\"AAPL\": 40, \"MSFT\": 60}). They need NOT sum to 1 or 100 — normalisation is a display decision. Any ticker not in `tickers` is dropped. Omit to leave existing weights untouched; pass null to clear them."
    }
  },
  "required": [
    "name",
    "tickers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived",
        "all"
      ],
      "default": "active",
      "description": "Filter by state; defaults to `active`. Use `all` to include archived watchlists."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Maximum number of watchlists to return (1–100). Defaults to 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 64,
      "description": "Opaque pagination cursor from a previous response; omit for the first page."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Watchlist name to fetch (case-insensitive, 1–80 chars)."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Watchlist name to soft-delete (case-insensitive, 1–80 chars); frees the name for reuse."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Memory key (1–128 chars). Reusing an existing key overwrites its value."
    },
    "value": {
      "type": "string",
      "maxLength": 8000,
      "description": "The note to remember (≤8000 chars). Never store a figure you would cite as a fact — those come from data tools."
    }
  },
  "required": [
    "key",
    "value"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "key": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        {
          "type": "null"
        }
      ],
      "description": "A specific key to fetch, or omit/null to recall all memory (newest-first)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "The memory key to forget. Discover keys with get_agent_memory (no key = list all)."
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Name of a watchlist the caller has already saved. Pass this OR `tickers`, never both."
    },
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Tickers or CIKs to scan, passed directly. Use this for an ad-hoc question — do NOT create a watchlist in order to ask one, since that writes a durable record into the user's account. Pass this OR `name`, never both."
    },
    "since": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Cutoff date (YYYY-MM-DD); the diff returns SEC filings whose filing_date is on or after this date."
    },
    "form_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "10-K",
          "10-Q",
          "8-K",
          "20-F",
          "40-F",
          "10-K/A",
          "10-Q/A",
          "20-F/A",
          "40-F/A"
        ]
      },
      "description": "Filing forms to include. Defaults to 10-K + 10-Q + 8-K."
    }
  },
  "required": [
    "since"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Human-readable label."
    },
    "condition": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "filing_event"
            },
            "tickers": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 10
              },
              "minItems": 1,
              "maxItems": 50
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "maxItems": 25,
              "description": "SEC form types to listen for, e.g. ['8-K', '10-K'] or ['SC 13D']. An EMPTY list means any filing. Amendments match their base form (a 10-K/A fires a 10-K signal) and EDGAR's two spellings of the schedules are equivalent ('SC 13D' === 'SCHEDULE 13D')."
            }
          },
          "required": [
            "type",
            "tickers",
            "forms"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "ratio_threshold"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "ratio": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60,
              "description": "Ratio name (e.g. 'interest_coverage' or 'net_debt_to_ebitda')."
            },
            "comparator": {
              "type": "string",
              "enum": [
                "lt",
                "gt",
                "lte",
                "gte"
              ]
            },
            "threshold": {
              "type": "number"
            }
          },
          "required": [
            "type",
            "ticker",
            "ratio",
            "comparator",
            "threshold"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "watchlist_change"
            },
            "watchlist_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "maxItems": 25,
              "description": "SEC form types to fire on, e.g. ['10-K', '10-Q']. Omit to keep the historical default set (8-K, 10-K, 10-Q, 20-F, 6-K, SC 13D, SC 13G, S-1, S-3); an empty list means any filing."
            }
          },
          "required": [
            "type",
            "watchlist_name"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "price_move"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "direction": {
              "type": "string",
              "enum": [
                "up",
                "down",
                "any"
              ],
              "description": "Which direction of move to fire on. 'any' fires on either direction."
            },
            "threshold_pct": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 50,
              "description": "Minimum absolute close-to-close move, in percent (0.5–50), to fire."
            },
            "window_days": {
              "type": "number",
              "enum": [
                1,
                5,
                21
              ],
              "description": "Trading-day lookback window: 1 (daily), 5 (weekly), or 21 (monthly)."
            }
          },
          "required": [
            "type",
            "ticker",
            "direction",
            "threshold_pct",
            "window_days"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "fundamental_change"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "concept": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80,
              "description": "Standard concept name, e.g. 'TotalRevenue', 'NetIncome', 'OperatingCashFlow'."
            },
            "change": {
              "type": "string",
              "enum": [
                "new_period",
                "restated",
                "any"
              ],
              "description": "'new_period' fires only on a brand-new reporting period; 'restated' fires only when an already-reported period gets a new accepted_at vintage (an amendment); 'any' fires on either."
            }
          },
          "required": [
            "type",
            "ticker",
            "concept",
            "change"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "watchlist_restatement"
            },
            "watchlist_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80,
              "description": "Fire when ANY company in this watchlist has a fact materially restated (>0.5% swing) by a later SEC filing — the Restatement Radar, scoped to a watchlist. Distinct from fundamental_change (one ticker + one concept)."
            }
          },
          "required": [
            "type",
            "watchlist_name"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Condition evaluated each cron tick — a discriminated union of `filing_event` (a watched ticker files a new form), `ratio_threshold` (a financial ratio crosses a comparator/threshold), `watchlist_change` (any ticker in a named watchlist files), `price_move` (Pro+ — a close-to-close move crosses a percent threshold), or `fundamental_change` (Pro+ — a standard_concept reports a new period or gets restated)."
    },
    "channel": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "email"
            },
            "target": {
              "type": "string",
              "format": "email",
              "maxLength": 256
            },
            "hmac_secret": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "target"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "webhook"
            },
            "target": {
              "type": "string",
              "format": "uri",
              "maxLength": 512
            },
            "hmac_secret": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "description": "HMAC secret (≥16 chars) for webhook signature verification. Recommended for production."
            }
          },
          "required": [
            "type",
            "target"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "dashboard"
            },
            "target": {
              "type": "string",
              "maxLength": 16,
              "default": "@self",
              "description": "Always '@self' for dashboard channels. Routes to the in-app inbox keyed by the signal's owning customer."
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "slack"
            },
            "target": {
              "type": "string",
              "format": "uri",
              "maxLength": 512,
              "description": "Slack incoming-webhook URL — must be on host hooks.slack.com (e.g. https://hooks.slack.com/services/T0000/B0000/XXXX). The URL itself is the secret, so no HMAC is used."
            }
          },
          "required": [
            "type",
            "target"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "agent_run"
            },
            "target": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "A standing_agent.id identifying which standing agent team to run when this signal fires. NOT a URL — no outbound-URL validation applies to this field."
            }
          },
          "required": [
            "type",
            "target"
          ],
          "additionalProperties": false
        }
      ],
      "description": "ONE delivery channel for a match — `email` (filing conditions: the morning digest; other conditions: one transactional email per signal per UTC day, the rest go to the inbox), `webhook` (HMAC-SHA256-signed POST to your URL), `slack` (POST to a hooks.slack.com incoming-webhook URL), `dashboard` (in-app inbox, readable via list_signal_inbox), or `agent_run` (runs a standing agent identified by its id, delivering the finished artifact to your inbox). Use `channels` instead to deliver to several at once; one of the two is required."
    },
    "channels": {
      "type": "array",
      "items": {
        "$ref": "#/properties/channel"
      },
      "minItems": 1,
      "maxItems": 4,
      "description": "SEVERAL delivery channels for a match, in order (up to 4, each a distinct type+target) — e.g. `[{type:'dashboard'},{type:'email',target:'you@fund.com'}]` to get the inbox item AND the email. The first entry is what `channel` reports. Takes precedence over `channel` when both are given."
    },
    "replaces_signal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional. The id of a signal this call REPLACES with a NEW one. Prefer `update_signal`, which edits in place and keeps the fire history; use this only when you deliberately want a fresh record. A verified live record you own is discounted from the tier cap so the swap is cap-neutral; an unknown, deleted, or foreign id is ignored and the cap applies normally."
    }
  },
  "required": [
    "name",
    "condition"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "alert_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The signal's `id` from `list_signals` / `create_signal`."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "New human-readable label."
    },
    "condition": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "filing_event"
            },
            "tickers": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 10
              },
              "minItems": 1,
              "maxItems": 50
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "maxItems": 25,
              "description": "SEC form types to listen for, e.g. ['8-K', '10-K'] or ['SC 13D']. An EMPTY list means any filing. Amendments match their base form (a 10-K/A fires a 10-K signal) and EDGAR's two spellings of the schedules are equivalent ('SC 13D' === 'SCHEDULE 13D')."
            }
          },
          "required": [
            "type",
            "tickers",
            "forms"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "ratio_threshold"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "ratio": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60,
              "description": "Ratio name (e.g. 'interest_coverage' or 'net_debt_to_ebitda')."
            },
            "comparator": {
              "type": "string",
              "enum": [
                "lt",
                "gt",
                "lte",
                "gte"
              ]
            },
            "threshold": {
              "type": "number"
            }
          },
          "required": [
            "type",
            "ticker",
            "ratio",
            "comparator",
            "threshold"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "watchlist_change"
            },
            "watchlist_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "maxItems": 25,
              "description": "SEC form types to fire on, e.g. ['10-K', '10-Q']. Omit to keep the historical default set (8-K, 10-K, 10-Q, 20-F, 6-K, SC 13D, SC 13G, S-1, S-3); an empty list means any filing."
            }
          },
          "required": [
            "type",
            "watchlist_name"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "price_move"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "direction": {
              "type": "string",
              "enum": [
                "up",
                "down",
                "any"
              ],
              "description": "Which direction of move to fire on. 'any' fires on either direction."
            },
            "threshold_pct": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 50,
              "description": "Minimum absolute close-to-close move, in percent (0.5–50), to fire."
            },
            "window_days": {
              "type": "number",
              "enum": [
                1,
                5,
                21
              ],
              "description": "Trading-day lookback window: 1 (daily), 5 (weekly), or 21 (monthly)."
            }
          },
          "required": [
            "type",
            "ticker",
            "direction",
            "threshold_pct",
            "window_days"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "fundamental_change"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10
            },
            "concept": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80,
              "description": "Standard concept name, e.g. 'TotalRevenue', 'NetIncome', 'OperatingCashFlow'."
            },
            "change": {
              "type": "string",
              "enum": [
                "new_period",
                "restated",
                "any"
              ],
              "description": "'new_period' fires only on a brand-new reporting period; 'restated' fires only when an already-reported period gets a new accepted_at vintage (an amendment); 'any' fires on either."
            }
          },
          "required": [
            "type",
            "ticker",
            "concept",
            "change"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "watchlist_restatement"
            },
            "watchlist_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80,
              "description": "Fire when ANY company in this watchlist has a fact materially restated (>0.5% swing) by a later SEC filing — the Restatement Radar, scoped to a watchlist. Distinct from fundamental_change (one ticker + one concept)."
            }
          },
          "required": [
            "type",
            "watchlist_name"
          ],
          "additionalProperties": false
        }
      ],
      "description": "New condition — the same discriminated union `create_signal` takes. Replaces the stored condition entirely."
    },
    "channels": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "email"
              },
              "target": {
                "type": "string",
                "format": "email",
                "maxLength": 256
              },
              "hmac_secret": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "webhook"
              },
              "target": {
                "type": "string",
                "format": "uri",
                "maxLength": 512
              },
              "hmac_secret": {
                "type": "string",
                "minLength": 16,
                "maxLength": 128,
                "description": "HMAC secret (≥16 chars) for webhook signature verification. Recommended for production."
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "dashboard"
              },
              "target": {
                "type": "string",
                "maxLength": 16,
                "default": "@self",
                "description": "Always '@self' for dashboard channels. Routes to the in-app inbox keyed by the signal's owning customer."
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "slack"
              },
              "target": {
                "type": "string",
                "format": "uri",
                "maxLength": 512,
                "description": "Slack incoming-webhook URL — must be on host hooks.slack.com (e.g. https://hooks.slack.com/services/T0000/B0000/XXXX). The URL itself is the secret, so no HMAC is used."
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "agent_run"
              },
              "target": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "description": "A standing_agent.id identifying which standing agent team to run when this signal fires. NOT a URL — no outbound-URL validation applies to this field."
              }
            },
            "required": [
              "type",
              "target"
            ],
            "additionalProperties": false
          }
        ]
      },
      "minItems": 1,
      "maxItems": 4,
      "description": "New delivery list (up to 4, each a distinct type+target). Replaces the stored list entirely; the first entry becomes `channel`."
    }
  },
  "required": [
    "alert_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "deleted",
        "all"
      ],
      "default": "active",
      "description": "Filter by lifecycle state; defaults to `active`. Use `all` to include paused and soft-deleted signals."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Maximum number of signals to return (1–100). Defaults to 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 64,
      "description": "Opaque pagination cursor from a previous response; omit for the first page."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "signal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the signal to soft-delete, as returned by create_signal or list_signals."
    }
  },
  "required": [
    "signal_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "signal_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the signal to fire a synthetic test notification through, as returned by create_signal or list_signals."
    }
  },
  "required": [
    "signal_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "unread_only": {
      "type": "boolean",
      "default": false,
      "description": "When true, return only items where read_at IS NULL."
    },
    "include_dismissed": {
      "type": "boolean",
      "default": false,
      "description": "When true, also return items the caller previously dismissed."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Maximum number of inbox items to return (1–100). Defaults to 20."
    },
    "cursor": {
      "type": "integer",
      "description": "Pagination cursor — the `fired_at` of the last item on the previous page."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "inbox_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the inbox item to mark read, as returned by list_signal_inbox or the signals feed resource."
    }
  },
  "required": [
    "inbox_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "inbox_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the inbox item to dismiss (soft-delete), as returned by list_signal_inbox."
    }
  },
  "required": [
    "inbox_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "tool_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "The MCP tool this action would call once approved (e.g. 'save_thesis', 'create_signal', 'publish_report')."
    },
    "tool_args": {
      "type": "object",
      "additionalProperties": {},
      "default": {},
      "description": "The exact arguments to replay through that tool if/when a human approves."
    },
    "origin": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Free-form label identifying who/what is proposing this action — e.g. 'agent-runner:managed', 'claude-connector', 'cursor', or any caller-supplied identifier. Lets a human distinguish which session/agent proposed a given write."
    }
  },
  "required": [
    "tool_name",
    "origin"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "Page size (max 100)."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous page's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "staged_action_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the staged action to approve, from stage_action or list_pending_approvals."
    }
  },
  "required": [
    "staged_action_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "staged_action_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of the staged action to reject."
    },
    "reason": {
      "type": "string",
      "maxLength": 2000,
      "description": "Optional free-text reason recorded on the staged action."
    }
  },
  "required": [
    "staged_action_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Human-readable description of the deferred work."
    },
    "wake_in_days": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 90,
      "description": "How many days from now this task becomes due (0 < n <= 90)."
    },
    "context": {
      "type": "object",
      "additionalProperties": {},
      "description": "Saved thesis/claim/report ids and any other state needed to reconstitute a fresh prompt at wake time. Set `managed: true` + `team_id: \"<standing_agent id>\"` to also kick off a live managed re-run of that team at wake time (see description)."
    }
  },
  "required": [
    "task",
    "wake_in_days"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed",
        "cancelled",
        "cancelled_owner_inactive",
        "all"
      ],
      "default": "pending",
      "description": "Filter by lifecycle state; defaults to `pending`."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "cursor": {
      "type": "integer",
      "description": "Pagination cursor from a previous response's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the scheduled task to cancel."
    }
  },
  "required": [
    "task_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Human-readable label."
    },
    "trigger": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "alert_fired"
            },
            "alert_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "Scope to one specific alert id. Omit to react to ANY of the rule owner's alerts firing."
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "schedule_tick"
            },
            "interval_minutes": {
              "type": "integer",
              "minimum": 5,
              "maximum": 10080,
              "description": "Minimum minutes between fires (5 min – 7 days). Rounded up to the nearest 5-minute cron tick."
            }
          },
          "required": [
            "type",
            "interval_minutes"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "inbox_item"
            },
            "condition_type_filter": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60,
              "description": "Only consider inbox items whose condition_type equals this value. Omit to react to any inbox item."
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "price_threshold"
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10,
              "pattern": "^[A-Za-z][A-Za-z0-9.\\-]{0,9}$"
            }
          },
          "required": [
            "type",
            "ticker"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "filing_event"
            },
            "ticker": {
              "$ref": "#/properties/trigger/anyOf/3/properties/ticker"
            },
            "forms": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              },
              "maxItems": 25
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "manual"
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "scheduled_task_wake"
            },
            "task_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "Scope to one specific scheduled_task id. Omit to react to ANY of the owner's tasks waking."
            }
          },
          "required": [
            "type"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Discriminated union — which signal fires this rule."
    },
    "condition_expr": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Optional single comparison against the trigger payload, e.g. \"price_change_pct gt 5\". Omit to fire on the trigger alone."
    },
    "action": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "run_team"
            },
            "team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "A standing_agent.id identifying which team to run — same identifier shape as a signal's agent_run channel target."
            }
          },
          "required": [
            "type",
            "team_id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "send_alert"
            },
            "channel": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "email"
                    },
                    "target": {
                      "type": "string",
                      "format": "email",
                      "maxLength": 256
                    },
                    "hmac_secret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "target"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "webhook"
                    },
                    "target": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 512
                    },
                    "hmac_secret": {
                      "type": "string",
                      "minLength": 16,
                      "maxLength": 128,
                      "description": "HMAC secret (≥16 chars) for webhook signature verification. Recommended for production."
                    }
                  },
                  "required": [
                    "type",
                    "target"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "dashboard"
                    },
                    "target": {
                      "type": "string",
                      "maxLength": 16,
                      "default": "@self",
                      "description": "Always '@self' for dashboard channels. Routes to the in-app inbox keyed by the signal's owning customer."
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "slack"
                    },
                    "target": {
                      "type": "string",
                      "format": "uri",
                      "maxLength": 512,
                      "description": "Slack incoming-webhook URL — must be on host hooks.slack.com (e.g. https://hooks.slack.com/services/T0000/B0000/XXXX). The URL itself is the secret, so no HMAC is used."
                    }
                  },
                  "required": [
                    "type",
                    "target"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "agent_run"
                    },
                    "target": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 64,
                      "description": "A standing_agent.id identifying which standing agent team to run when this signal fires. NOT a URL — no outbound-URL validation applies to this field."
                    }
                  },
                  "required": [
                    "type",
                    "target"
                  ],
                  "additionalProperties": false
                }
              ],
              "description": "Delivery channel — same discriminated union create_signal accepts (email/webhook/dashboard/slack/agent_run)."
            },
            "message": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000,
              "description": "Optional custom message; defaults to a summary of the trigger event."
            }
          },
          "required": [
            "type",
            "channel"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "create_report"
            },
            "report_type": {
              "type": "string",
              "enum": [
                "reverse_dcf",
                "thesis"
              ]
            },
            "ticker": {
              "type": "string",
              "minLength": 1,
              "maxLength": 10,
              "description": "Required when report_type=reverse_dcf."
            },
            "thesis_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "Required when report_type=thesis."
            },
            "params": {
              "type": "object",
              "additionalProperties": {},
              "description": "reverse_dcf DCF params — see create_report's own schema."
            },
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "required": [
            "type",
            "report_type"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "score_thesis"
            },
            "thesis_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "as_of": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            }
          },
          "required": [
            "type",
            "thesis_id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "schedule_task"
            },
            "task": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "wake_in_days": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 90
            },
            "context": {
              "type": "object",
              "additionalProperties": {}
            }
          },
          "required": [
            "type",
            "task",
            "wake_in_days"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "post_inbox"
            },
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "message": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            }
          },
          "required": [
            "type",
            "title",
            "message"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Discriminated union — what happens when the rule fires."
    },
    "replaces_rule_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional. The id of a signal this call REPLACES — set it when saving an edit, which is stored as create-then-delete because neither engine has an update tool. A verified live record you own is discounted from the tier cap so an edit is cap-neutral; an unknown, deleted, or foreign id is ignored and the cap applies normally."
    }
  },
  "required": [
    "name",
    "trigger",
    "action"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "cursor": {
      "type": "integer",
      "description": "Pagination cursor from a previous response's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "rule_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the rule to delete."
    }
  },
  "required": [
    "rule_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "rule_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the rule to dry-run, from create_rule or list_rules."
    },
    "sample_payload_override": {
      "type": "object",
      "additionalProperties": {},
      "description": "Merged over the built-in synthetic payload for this rule's trigger_type — lets you test a specific value."
    }
  },
  "required": [
    "rule_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "day": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Specific day to fetch (YYYY-MM-DD). Omit to get the most recent brief available for this customer."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max runs to return (1-50, default 10)."
    },
    "status": {
      "type": "string",
      "description": "Filter to an exact status match."
    },
    "agent_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Filter to runs belonging to one agent (from save_agent/list_agents)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string",
      "minLength": 1,
      "description": "Run identifier, from list_agent_runs."
    }
  },
  "required": [
    "run_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Omit to create a new agent; pass an existing agent's id (from save_agent/list_agents/get_agent) to update it."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Human-readable label."
    },
    "goal": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "What this agent is trying to accomplish — drives an autonomous agent's AI-directed team, and documents intent for a workflow agent's fixed steps."
    },
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10
      },
      "minItems": 1,
      "maxItems": 500,
      "description": "US tickers this agent operates over. Normalised to uppercase."
    },
    "agent_type": {
      "type": "string",
      "enum": [
        "workflow",
        "autonomous"
      ],
      "description": "STRUCTURAL and immutable. \"workflow\" = fixed step recipe, free/deterministic, requires `steps`. \"autonomous\" = AI-directed team, charged, may set `managed_model`."
    },
    "when": {
      "type": "string",
      "enum": [
        "manual",
        "schedule"
      ],
      "description": "Trigger mode. \"manual\" fires only via run_agent/the UI; \"schedule\" requires the `schedule` object."
    },
    "schedule": {
      "type": "object",
      "properties": {
        "cadence": {
          "type": "string",
          "enum": [
            "daily",
            "weekly",
            "monthly"
          ],
          "description": "How often this agent fires."
        },
        "hour_utc": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23,
          "description": "UTC hour to fire at (0-23)."
        },
        "minute": {
          "type": "integer",
          "minimum": 0,
          "maximum": 59,
          "description": "UTC minute to fire at (0-59, default 0)."
        },
        "day_of_week": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6,
          "description": "0=Sunday..6=Saturday. Required when cadence=\"weekly\"."
        },
        "day_of_month": {
          "type": "integer",
          "minimum": 1,
          "maximum": 28,
          "description": "1-28 (clamped to avoid short-month skips). Required when cadence=\"monthly\"."
        },
        "timezone": {
          "type": "string",
          "maxLength": 64,
          "description": "IANA timezone (e.g. \"America/New_York\") for display only — hour_utc/minute above are authoritative and always UTC."
        }
      },
      "required": [
        "cadence",
        "hour_utc"
      ],
      "additionalProperties": false,
      "description": "Required when when=\"schedule\"; ignored otherwise."
    },
    "managed_model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Managed-lane model override for agent_type=\"autonomous\" only (e.g. when no BYO key is connected). Omit to use the account default."
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "tool",
              "sop"
            ],
            "description": "Whether `name` names an MCP tool or a SOP (playbook) slug."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Tool name (e.g. \"get_company_fundamentals\") or SOP slug (e.g. \"equity_research_brief\")."
          },
          "args": {
            "type": "object",
            "additionalProperties": {},
            "description": "Arguments for this step. Supports {{ticker}} substitution the same way run_workflow's plan does."
          },
          "label": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional human-readable label for this step."
          }
        },
        "required": [
          "kind",
          "name",
          "args"
        ],
        "additionalProperties": false
      },
      "maxItems": 50,
      "description": "Fixed step recipe for agent_type=\"workflow\". Required + non-empty when CREATING a workflow agent; must be omitted for agent_type=\"autonomous\"."
    }
  },
  "required": [
    "name",
    "goal",
    "tickers",
    "agent_type",
    "when"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Max agents to return (1-50, default 20)."
    },
    "agent_type": {
      "type": "string",
      "enum": [
        "workflow",
        "autonomous"
      ],
      "description": "Filter to one agent_type."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Agent identifier, from save_agent or list_agents."
    }
  },
  "required": [
    "agent_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the agent to delete."
    }
  },
  "required": [
    "agent_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Identifier of the agent to run now."
    }
  },
  "required": [
    "agent_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_type": {
      "type": "string",
      "enum": [
        "reverse_dcf",
        "thesis"
      ],
      "description": "Subtype. `reverse_dcf` requires ticker + params; `thesis` requires thesis_id (from save_thesis / list_theses)."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "US-listed ticker — required for report_type=reverse_dcf. Case-insensitive."
    },
    "params": {
      "type": "object",
      "properties": {
        "target_price_cents": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "description": "Per-share market price the model solves for (integer cents)."
        },
        "wacc": {
          "type": "number",
          "minimum": 0.01,
          "maximum": 0.5,
          "default": 0.09,
          "description": "Discount rate. Default 0.09 (9%)."
        },
        "terminal_growth_rate": {
          "type": "number",
          "minimum": -0.05,
          "maximum": 0.1,
          "default": 0.025,
          "description": "Long-run growth assumption. Default 0.025 (2.5%)."
        },
        "stage1_years": {
          "type": "integer",
          "minimum": 3,
          "maximum": 15,
          "default": 5,
          "description": "Length of the explicit forecast horizon. Default 5."
        }
      },
      "required": [
        "target_price_cents"
      ],
      "additionalProperties": false,
      "description": "Reverse-DCF parameters — required for report_type=reverse_dcf."
    },
    "thesis_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Id of a saved thesis owned by the caller — required for report_type=thesis."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Optional human-supplied title; auto-generated when omitted."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional key for at-most-once semantics. Same key from the same user always yields the same report id."
    }
  },
  "required": [
    "report_type"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Id from `create_report` or `list_my_reports`."
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "json",
        "preview"
      ],
      "default": "markdown",
      "description": "Response shape. Defaults to markdown."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "ready",
        "listed",
        "delisted",
        "all"
      ],
      "default": "ready",
      "description": "Filter by status. Default 'ready' (excludes drafts + delisted)."
    },
    "report_type": {
      "type": "string",
      "enum": [
        "reverse_dcf"
      ],
      "description": "Filter by report type."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Filter to a single ticker (case-insensitive)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Page size."
    },
    "cursor": {
      "type": "string",
      "maxLength": 64,
      "description": "Cursor from previous `next_cursor`."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Id from `create_report` or `list_my_reports`."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "visibility": {
      "type": "string",
      "enum": [
        "unlisted",
        "listed"
      ],
      "default": "listed"
    },
    "price_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Currently must be omitted or 0 — all listings are free. A non-zero value is rejected until paid listings ship."
    },
    "tier_required": {
      "type": "string",
      "enum": [
        "sample",
        "sp500",
        "pro",
        "full"
      ],
      "description": "Minimum subscriber tier to read the full body. Defaults to the author's plan."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Free-text query over title + abstract (case-insensitive)."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Filter to a single subject ticker."
    },
    "report_type": {
      "type": "string",
      "enum": [
        "reverse_dcf"
      ],
      "description": "Filter by report type."
    },
    "price_max_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Reserved for future paid listings; currently ignored (all reports are free)."
    },
    "sort": {
      "type": "string",
      "enum": [
        "newest",
        "oldest"
      ],
      "default": "newest"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "cursor": {
      "type": "string",
      "maxLength": 128
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B."
    },
    "stage1_growth_rate": {
      "type": "number",
      "minimum": -0.5,
      "maximum": 1,
      "description": "Stage-1 FCF growth rate (e.g. 0.12 = 12%/yr)."
    },
    "wacc": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 0.5,
      "default": 0.09,
      "description": "Discount rate. Default 0.09."
    },
    "terminal_growth_rate": {
      "type": "number",
      "minimum": -0.05,
      "maximum": 0.1,
      "default": 0.025,
      "description": "Long-run growth. Default 0.025."
    },
    "stage1_years": {
      "type": "integer",
      "minimum": 3,
      "maximum": 15,
      "default": 5,
      "description": "Number of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5."
    },
    "fcf_base_override": {
      "type": "number",
      "description": "Override the auto-pulled FCF base (USD). Leave unset to use R2-derived."
    },
    "shares_override": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override shares outstanding. Leave unset to use R2-derived."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs."
    },
    "fcf_source": {
      "type": "string",
      "enum": [
        "trend",
        "three_statement"
      ],
      "default": "trend",
      "description": "\"trend\" (default): compound fcf_base by stage1_growth_rate every year (unchanged original behavior). \"three_statement\": derive the FCF stream from a full linked 3-statement projection instead — see the tool description for details."
    },
    "three_statement_assumptions": {
      "type": "object",
      "properties": {
        "interest_rate_on_debt": {
          "type": "number",
          "minimum": 0,
          "maximum": 0.5,
          "description": "Default 0.06."
        },
        "tax_rate": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Default 0.21."
        },
        "cash_sweep_pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Default 0."
        },
        "dividend_payout_pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Default 0."
        }
      },
      "additionalProperties": false,
      "description": "Only used when fcf_source is \"three_statement\". Overrides for the underlying projection; unset fields use project_three_statement's defaults."
    }
  },
  "required": [
    "ticker",
    "stage1_growth_rate"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the company to audit, e.g. AAPL, MSFT, BRK.B."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "As-of calendar date (YYYY-MM-DD). Returns the close of the most recent trading day on or before this date — a weekend/holiday resolves to the prior trading close. Omit to get the latest available close."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Inclusive start of the date range (YYYY-MM-DD). Bars on or after this date are returned (up to `limit`). Omit to receive the `limit` most-recent bars before end_date."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Inclusive end of the date range (YYYY-MM-DD). Defaults to today (the latest available close). Weekends and holidays resolve to the last trading close on or before this date."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 360,
      "default": 252,
      "description": "Maximum number of bars to return. Daily plans (Pro, Institutional): 1–252, default 252 ≈ 1 trading year. Free plans (sample, benchmark), which return month-end bars: 1–360, covering up to the full ~30-year monthly archive. When the range contains more bars than `limit`, the most recent `limit` bars within the range are returned."
    }
  },
  "required": [
    "ticker"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "pattern": "^[A-Za-z0-9.\\-]+$",
      "description": "Stock ticker symbol, e.g. AAPL, MSFT — or a CIK (SEC identifier), e.g. '0000320193'."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The historical date for the valuation snapshot (YYYY-MM-DD). The EOD close on the nearest prior trading day will be used. All financials are PIT-filtered to filings accepted on or before this date. Use a date in the recent past (within the last year) to get current-ish multiples; use any historical date back to 1993 (subject to your plan's history window) to get the multiples as they would have been observable on that date."
    }
  },
  "required": [
    "ticker",
    "as_of_date"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "tickers": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10,
        "pattern": "^([A-Za-z][A-Za-z0-9.\\-]{0,9}|\\d{1,10})$"
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "1-10 stock ticker symbols, e.g. [\"AAPL\",\"MSFT\"]."
    },
    "rebalance_dates": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
      },
      "minItems": 1,
      "maxItems": 12,
      "description": "1-12 historical dates (YYYY-MM-DD) to snapshot valuation multiples on. Order does not matter — the tool sorts them chronologically. Forward return is computed from each date to the NEXT one in the sorted list."
    },
    "factors": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "pe_ratio",
          "ps_ratio",
          "pb_ratio",
          "ev_ebitda",
          "ev_revenue",
          "fcf_yield_pct",
          "gross_margin_pct",
          "operating_margin_pct",
          "net_margin_pct"
        ]
      },
      "description": "Which of get_pit_valuation_ratios's own output fields to include as factor_values. One or more of: pe_ratio, ps_ratio, pb_ratio, ev_ebitda, ev_revenue, fcf_yield_pct, gross_margin_pct, operating_margin_pct, net_margin_pct. Omit to include all of them."
    }
  },
  "required": [
    "tickers",
    "rebalance_dates"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol, e.g. AAPL, MSFT, BRK.B."
    },
    "years": {
      "type": "integer",
      "minimum": 1,
      "maximum": 15,
      "default": 5,
      "description": "Projection horizon in years (1-15). Defaults to 5."
    },
    "revenue_growth_rate": {
      "type": "number",
      "minimum": -0.5,
      "maximum": 1,
      "description": "Flat annual revenue growth rate applied every year (e.g. 0.08 = 8%/yr)."
    },
    "interest_rate_on_debt": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.5,
      "default": 0.06,
      "description": "Annual interest rate on beginning-of-period debt. Assumption — default 0.06."
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.21,
      "description": "Effective tax rate on positive pretax income. Default 0.21 (US statutory)."
    },
    "gross_margin_pct_override": {
      "type": "number",
      "description": "Override the seed period's gross margin (held flat across all years). Leave unset to use the historical ratio."
    },
    "operating_margin_pct_override": {
      "type": "number",
      "description": "Override the seed period's operating margin. Leave unset to use the historical ratio."
    },
    "capex_pct_of_revenue_override": {
      "type": "number",
      "description": "Override the seed period's capex-as-%-of-revenue ratio. Leave unset to use the historical ratio."
    },
    "cash_sweep_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0,
      "description": "Fraction (0-1) of each year's free cash flow swept to debt paydown. Default 0 (going-concern; use ~1.0 for an LBO-style paydown)."
    },
    "dividend_payout_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0,
      "description": "Fraction (0-1) of net income paid out as dividends each year. Default 0."
    },
    "new_debt_draw_year1": {
      "type": "number",
      "minimum": 0,
      "default": 0,
      "description": "New debt drawn at year 1 only (absolute USD) — e.g. acquisition financing. Default 0."
    },
    "new_equity_draw_year1": {
      "type": "number",
      "minimum": 0,
      "default": 0,
      "description": "New equity contributed at year 1 only (absolute USD) — hits cash + equity symmetrically. Default 0."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) for the seed period. Omit to use the latest knowable annual period."
    }
  },
  "required": [
    "ticker",
    "revenue_growth_rate"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the LBO target, e.g. AAPL."
    },
    "entry_multiple": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "EV/EBITDA multiple paid at entry (e.g. 10 = 10x)."
    },
    "exit_multiple": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "EV/EBITDA multiple assumed at exit. Defaults to entry_multiple (no multiple expansion/contraction) when omitted."
    },
    "leverage_multiple": {
      "type": "number",
      "minimum": 0,
      "description": "Debt/EBITDA raised at entry (e.g. 5 = 5x leverage)."
    },
    "hold_period_years": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 5,
      "description": "Hold period in years (1-10). Defaults to 5."
    },
    "revenue_growth_rate": {
      "type": "number",
      "minimum": -0.5,
      "maximum": 1,
      "description": "Flat annual revenue growth rate applied every year of the hold (e.g. 0.05 = 5%/yr)."
    },
    "interest_rate_on_debt": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.5,
      "default": 0.08,
      "description": "Annual interest rate on beginning-of-period LBO debt. Default 0.08 (leveraged debt typically prices above IG)."
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.21,
      "description": "Effective tax rate on positive pretax income. Default 0.21."
    },
    "cash_sweep_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 1,
      "description": "Fraction (0-1) of each year's FCF swept to debt paydown. Default 1.0 (standard LBO — 100% sweep)."
    },
    "dividend_payout_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0,
      "description": "Fraction (0-1) of net income distributed to the sponsor each year (dividend recap style). Default 0 — most LBOs return capital only at exit."
    },
    "minimum_cash": {
      "type": "number",
      "minimum": 0,
      "default": 0,
      "description": "Minimum operating cash left on the pro-forma opening balance sheet. Default 0."
    },
    "entry_ebitda_override": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override the EBITDA figure used for both entry and exit multiples. Without this, EBITDA is proxied by operating income."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) for the seed period. Omit to use the latest knowable annual period."
    }
  },
  "required": [
    "ticker",
    "entry_multiple",
    "leverage_multiple",
    "revenue_growth_rate"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "acquirer_ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Acquirer's stock ticker symbol, e.g. MSFT."
    },
    "target_ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Target's stock ticker symbol, e.g. ATVI."
    },
    "offer_price_per_share": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Offer price per target share (USD)."
    },
    "cash_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Fraction (0-1) of deal value paid in cash; the remainder (1 - cash_pct) is paid in acquirer stock."
    },
    "synergies_pretax": {
      "type": "number",
      "default": 0,
      "description": "Pretax annual run-rate cost/revenue synergies (USD). Default 0."
    },
    "cash_financing_source": {
      "type": "string",
      "enum": [
        "new_debt",
        "balance_sheet_cash"
      ],
      "default": "new_debt",
      "description": "Where the cash consideration is funded from. \"new_debt\" (default) applies an after-tax interest drag; \"balance_sheet_cash\" applies none."
    },
    "new_debt_interest_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.5,
      "default": 0.06,
      "description": "Annual interest rate on new acquisition debt (only used when cash_financing_source is \"new_debt\"). Default 0.06."
    },
    "tax_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.21,
      "description": "Effective tax rate applied to synergies and the interest drag. Default 0.21."
    },
    "acquirer_share_price_override": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override the acquirer's live EOD close. Leave unset to use the latest R2-derived price."
    },
    "target_share_price_override": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Override the target's live EOD close (used only for the disclosed premium). Leave unset to use the latest R2-derived price."
    },
    "as_of_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Point-in-time cutoff (YYYY-MM-DD) for both companies' fundamentals + prices. Omit to use the latest knowable data."
    }
  },
  "required": [
    "acquirer_ticker",
    "target_ticker",
    "offer_price_per_share",
    "cash_pct"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report to update, as returned by create_report or list_my_reports."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Optional new title."
    },
    "abstract": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Optional new abstract."
    },
    "sections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "heading": {
            "type": "string",
            "maxLength": 200
          },
          "markdown": {
            "type": "string",
            "maxLength": 20000
          }
        },
        "required": [
          "id",
          "markdown"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Sections to replace. Sections not listed are preserved — to DELETE one, name it in `remove_section_ids`. Section ids must match the existing payload."
    },
    "remove_section_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "maxItems": 20,
      "description": "Section ids to DELETE outright. Without this, a merge-only update cannot express a deletion: an editor that drops a section simply omits it, the omitted section is preserved, and the caller sees a bumped version with the deleted content still there — a save that reports success and changed nothing. Ids must exist, and the last remaining section cannot be removed (a report with no sections is unreadable); remove the report instead with delete_report."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "claim": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Plain-English claim, quoting the figure as the prose writes it (e.g. 'FY2024 revenue: $391.0B')."
          },
          "fact_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "maxItems": 50,
            "description": "Valuein fact_ids backing the claim, as returned by the data tools."
          },
          "accession_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "maxItems": 50,
            "description": "Optional SEC accession ids backing the claim."
          },
          "sec_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "maxItems": 50,
            "description": "Optional EDGAR URLs, one per accession."
          },
          "evidence": {
            "type": "string",
            "enum": [
              "primary",
              "derived",
              "external"
            ],
            "description": "Provenance class. Defaults to 'derived' — the weaker claim."
          },
          "ticker": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10,
            "description": "Ticker the fact belongs to. Lets a figure be verified when the report has no ticker."
          },
          "form_type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "description": "SEC form the figure was reported on ('10-K', '10-Q', '20-F'), verbatim from the source."
          },
          "filed_at": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "SEC acceptance timestamp of the filing (ISO 8601) — when the figure became public."
          },
          "period_end": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Last day of the period the figure COVERS (YYYY-MM-DD). Not the filing date."
          },
          "period_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "How the filer names that period: 'FY2025', 'Q3 2025'."
          }
        },
        "required": [
          "claim",
          "fact_ids"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000,
      "description": "Lineage for figures in the edited sections. MERGED into the report's existing citations (first claim wins), never replacing them — so an editor autosave that sends none preserves every citation the report already had."
    },
    "expected_version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Optimistic concurrency check. If supplied and the current HEAD version is different, the call returns a `version_conflict` error WITHOUT writing. Pass the version you loaded so a concurrent agent edit produces a 'conflict — review' UX instead of silently overwriting (eng review A3A)."
    }
  },
  "required": [
    "report_id",
    "sections"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report whose version history to list, as returned by create_report or list_my_reports."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20,
      "description": "Maximum number of archived versions to return (1–100). Defaults to 20."
    },
    "cursor": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Cursor from the previous response's `next_cursor` — the smallest version number on the previous page. Omit for the first page."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier of the report whose archived version to fetch, as returned by create_report or list_my_reports."
    },
    "version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Version number to fetch (from list_report_versions)."
    }
  },
  "required": [
    "report_id",
    "version"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Id from create_report or list_my_reports."
    },
    "format": {
      "type": "string",
      "enum": [
        "md",
        "docx",
        "pdf"
      ],
      "description": "md = raw markdown (the same body the editor renders). docx = branded Word document; pdf = the same branded research-note design as a shareable PDF (Geist faces embedded, clickable citation links)."
    },
    "force_regenerate": {
      "type": "boolean",
      "default": false,
      "description": "If true, ignore the cached DOCX/PDF and re-render. No effect on md (markdown is canonical)."
    },
    "author_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Display name of the report's author, shown as a named byline ('By {name}') on the masthead — the way a real research note credits an analyst. Omit to show 'Valuein Research'. Only affects the binary formats; ignored on a cache hit (the cached file keeps whatever byline was baked in on first render — pass `force_regenerate: true` to refresh it)."
    }
  },
  "required": [
    "report_id",
    "format"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Report title."
    },
    "markdown": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100000,
      "description": "Free-form markdown body (≤100k chars). Headings become sections."
    },
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Optional ticker for context/catalog. Case-insensitive."
    },
    "abstract": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Optional 1–2 sentence summary."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional key for at-most-once semantics. Same key from the same user always yields the same report id."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "claim": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Plain-English claim, quoting the figure as the prose writes it (e.g. 'FY2024 revenue: $391.0B')."
          },
          "fact_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "maxItems": 50,
            "description": "Valuein fact_ids backing the claim, as returned by the data tools."
          },
          "accession_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            },
            "maxItems": 50,
            "description": "Optional SEC accession ids backing the claim."
          },
          "sec_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "maxItems": 50,
            "description": "Optional EDGAR URLs, one per accession."
          },
          "evidence": {
            "type": "string",
            "enum": [
              "primary",
              "derived",
              "external"
            ],
            "description": "Provenance class. Defaults to 'derived' — the weaker claim."
          },
          "ticker": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10,
            "description": "Ticker the fact belongs to. Lets a figure be verified when the report has no ticker."
          },
          "form_type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "description": "SEC form the figure was reported on ('10-K', '10-Q', '20-F'), verbatim from the source."
          },
          "filed_at": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "SEC acceptance timestamp of the filing (ISO 8601) — when the figure became public."
          },
          "period_end": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Last day of the period the figure COVERS (YYYY-MM-DD). Not the filing date."
          },
          "period_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "How the filer names that period: 'FY2025', 'Q3 2025'."
          }
        },
        "required": [
          "claim",
          "fact_ids"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000,
      "description": "Lineage you already hold for the figures in `markdown` — pass it rather than dropping it. Each claim should quote the figure exactly as the prose writes it, so figure review can link the two. Persisted as-is and NOT verified here; sign-off re-resolves every fact_id before certifying."
    }
  },
  "required": [
    "title",
    "markdown"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The upload_id returned by POST /v1/uploads."
    }
  },
  "required": [
    "upload_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Max uploads to return (default 20, the same cap as MAX_ACTIVE_UPLOADS_PER_CUSTOMER)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "The upload_id returned by POST /v1/uploads."
    }
  },
  "required": [
    "upload_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the company the DCF workbook is built for, e.g. AAPL."
    },
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional — surfaces on the cover row. Falls back to ticker only."
    },
    "dcf_result": {
      "type": "object",
      "properties": {
        "value_per_share_cents": {
          "type": [
            "number",
            "null"
          ]
        },
        "enterprise_value": {
          "type": [
            "number",
            "null"
          ]
        },
        "equity_value": {
          "type": [
            "number",
            "null"
          ]
        },
        "terminal_value_pct": {
          "type": [
            "number",
            "null"
          ]
        },
        "inputs_echo": {
          "type": "object",
          "properties": {
            "fcf_base_total_usd": {
              "type": "number"
            },
            "shares_outstanding": {
              "type": "number",
              "exclusiveMinimum": 0
            },
            "net_debt": {
              "type": "number"
            },
            "stage1_growth_rate": {
              "type": "number"
            },
            "wacc": {
              "type": "number"
            },
            "terminal_growth_rate": {
              "type": "number"
            },
            "stage1_years": {
              "type": "integer"
            }
          },
          "required": [
            "fcf_base_total_usd",
            "shares_outstanding",
            "net_debt",
            "stage1_growth_rate",
            "wacc",
            "terminal_growth_rate",
            "stage1_years"
          ],
          "additionalProperties": false
        },
        "sensitivity_table": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "wacc": {
                  "type": "number"
                },
                "terminal_growth_rate": {
                  "type": "number"
                },
                "value_per_share_cents": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "wacc",
                "terminal_growth_rate",
                "value_per_share_cents"
              ],
              "additionalProperties": false
            }
          }
        },
        "reason": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "value_per_share_cents",
        "enterprise_value",
        "equity_value",
        "terminal_value_pct",
        "inputs_echo",
        "sensitivity_table",
        "reason"
      ],
      "additionalProperties": false,
      "description": "Structured DCF result — typically the `result` field returned by `compute_dcf`."
    }
  },
  "required": [
    "ticker",
    "dcf_result"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol the brief covers, e.g. AAPL, MSFT, BRK.B."
    },
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional display name shown in the masthead subtitle; falls back to the ticker if omitted."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Document title rendered in the page-1 masthead (1–200 chars)."
    },
    "abstract": {
      "type": "string",
      "maxLength": 2000,
      "description": "Optional executive-summary paragraph (≤2000 chars) shown after the masthead."
    },
    "snapshot": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false
      },
      "maxItems": 20,
      "default": [],
      "description": "Optional at-a-glance metric rows (≤20) rendered as the snapshot table."
    },
    "sections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "heading": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000
          }
        },
        "required": [
          "heading",
          "text"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Ordered body sections of the brief (1–20); each has a heading and body text."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "claim": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "source_filing": {
            "type": "string",
            "maxLength": 40
          },
          "source_url": {
            "type": "string",
            "maxLength": 500
          },
          "evidence": {
            "type": "string",
            "enum": [
              "primary",
              "derived",
              "external"
            ]
          }
        },
        "required": [
          "claim",
          "source_filing",
          "source_url",
          "evidence"
        ],
        "additionalProperties": false
      },
      "maxItems": 60,
      "default": [],
      "description": "Optional source citations (≤60) rendered as a table with clickable SEC EDGAR hyperlinks."
    },
    "author_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Display name of the analyst producing this brief, shown as a named byline ('By {name}') on the masthead — the way a real research note credits an analyst. Omit to show just the date."
    }
  },
  "required": [
    "ticker",
    "title",
    "sections"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "subject_ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the subject company the comps sheet is built around, e.g. AAPL."
    },
    "subject_company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional display name for the subject company; falls back to the ticker if omitted."
    },
    "peers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10
          },
          "company_name": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 120
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "sector": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 60
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "market_cap": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "pe_ratio": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "pb_ratio": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "ev_to_ebitda": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "ev_to_revenue": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "gross_margin": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "operating_margin": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "net_margin": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "roe": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "roic": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          },
          "fcf_yield": {
            "type": [
              "number",
              "null"
            ],
            "default": null
          }
        },
        "required": [
          "ticker"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Peer companies to tabulate against the subject (1–50 rows); each row carries the peer's ticker, name, and comparable ratio values."
    },
    "notes": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional free-text note (≤500 chars) rendered on the Summary sheet."
    }
  },
  "required": [
    "subject_ticker",
    "peers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10,
      "description": "Stock ticker symbol of the LBO target, e.g. AAPL."
    },
    "company_name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional — surfaces on the cover row. Falls back to ticker only."
    },
    "lbo_result": {
      "type": "object",
      "properties": {
        "entry_ebitda": {
          "type": "number"
        },
        "entry_ebitda_is_proxy": {
          "type": "boolean"
        },
        "entry_enterprise_value": {
          "type": "number"
        },
        "entry_debt": {
          "type": "number"
        },
        "sponsor_equity": {
          "type": "number"
        },
        "exit_ebitda": {
          "type": "number"
        },
        "exit_enterprise_value": {
          "type": "number"
        },
        "exit_net_debt": {
          "type": "number"
        },
        "exit_equity_value": {
          "type": "number"
        },
        "total_distributions": {
          "type": "number"
        },
        "moic": {
          "type": "number"
        },
        "irr": {
          "type": "object",
          "properties": {
            "irr": {
              "type": [
                "number",
                "null"
              ]
            },
            "converged": {
              "type": "boolean"
            },
            "iterations": {
              "type": "integer"
            }
          },
          "required": [
            "irr",
            "converged",
            "iterations"
          ],
          "additionalProperties": false
        },
        "projection": {
          "type": "object",
          "properties": {
            "years": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "year": {
                    "type": "integer"
                  },
                  "revenue": {
                    "type": "number"
                  },
                  "gross_profit": {
                    "type": "number"
                  },
                  "operating_income": {
                    "type": "number"
                  },
                  "interest_expense": {
                    "type": "number"
                  },
                  "pretax_income": {
                    "type": "number"
                  },
                  "tax": {
                    "type": "number"
                  },
                  "net_income": {
                    "type": "number"
                  },
                  "capex": {
                    "type": "number"
                  },
                  "noncash_adjustment": {
                    "type": "number"
                  },
                  "operating_cash_flow": {
                    "type": "number"
                  },
                  "free_cash_flow": {
                    "type": "number"
                  },
                  "debt_draw": {
                    "type": "number"
                  },
                  "debt_paydown": {
                    "type": "number"
                  },
                  "dividends_paid": {
                    "type": "number"
                  },
                  "ending_debt": {
                    "type": "number"
                  },
                  "ending_cash": {
                    "type": "number"
                  },
                  "ending_non_cash_assets": {
                    "type": "number"
                  },
                  "ending_total_assets": {
                    "type": "number"
                  },
                  "ending_non_debt_liabilities": {
                    "type": "number"
                  },
                  "ending_total_liabilities": {
                    "type": "number"
                  },
                  "ending_stockholders_equity": {
                    "type": "number"
                  },
                  "tie_out_diff": {
                    "type": "number"
                  },
                  "tie_out_ok": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "year",
                  "revenue",
                  "gross_profit",
                  "operating_income",
                  "interest_expense",
                  "pretax_income",
                  "tax",
                  "net_income",
                  "capex",
                  "noncash_adjustment",
                  "operating_cash_flow",
                  "free_cash_flow",
                  "debt_draw",
                  "debt_paydown",
                  "dividends_paid",
                  "ending_debt",
                  "ending_cash",
                  "ending_non_cash_assets",
                  "ending_total_assets",
                  "ending_non_debt_liabilities",
                  "ending_total_liabilities",
                  "ending_stockholders_equity",
                  "tie_out_diff",
                  "tie_out_ok"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "years"
          ],
          "additionalProperties": true
        },
        "caveats": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "inputs_echo": {
          "type": "object",
          "properties": {
            "seed": {
              "type": "object",
              "properties": {
                "revenue": {
                  "type": "number"
                },
                "gross_margin_pct": {
                  "type": "number"
                },
                "operating_margin_pct": {
                  "type": "number"
                },
                "noncash_adj_pct_of_revenue": {
                  "type": "number"
                },
                "capex_pct_of_revenue": {
                  "type": "number"
                },
                "total_assets": {
                  "type": "number"
                },
                "total_liabilities": {
                  "type": "number"
                },
                "stockholders_equity": {
                  "type": "number"
                },
                "cash": {
                  "type": "number"
                },
                "total_debt": {
                  "type": "number"
                }
              },
              "required": [
                "revenue",
                "gross_margin_pct",
                "operating_margin_pct",
                "noncash_adj_pct_of_revenue",
                "capex_pct_of_revenue",
                "total_assets",
                "total_liabilities",
                "stockholders_equity",
                "cash",
                "total_debt"
              ],
              "additionalProperties": false
            },
            "entry_multiple": {
              "type": "number"
            },
            "exit_multiple": {
              "type": "number"
            },
            "leverage_multiple": {
              "type": "number"
            },
            "hold_period_years": {
              "type": "integer"
            },
            "revenue_growth_rate": {
              "type": "number"
            },
            "interest_rate_on_debt": {
              "type": "number"
            },
            "tax_rate": {
              "type": "number"
            },
            "cash_sweep_pct": {
              "type": "number"
            },
            "dividend_payout_pct": {
              "type": "number"
            },
            "minimum_cash": {
              "type": "number"
            },
            "entry_ebitda_override": {
              "type": "number"
            }
          },
          "required": [
            "seed",
            "entry_multiple",
            "exit_multiple",
            "leverage_multiple",
            "hold_period_years",
            "revenue_growth_rate",
            "interest_rate_on_debt",
            "tax_rate",
            "cash_sweep_pct",
            "dividend_payout_pct",
            "minimum_cash"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "entry_ebitda",
        "entry_ebitda_is_proxy",
        "entry_enterprise_value",
        "entry_debt",
        "sponsor_equity",
        "exit_ebitda",
        "exit_enterprise_value",
        "exit_net_debt",
        "exit_equity_value",
        "total_distributions",
        "moic",
        "irr",
        "projection",
        "caveats",
        "inputs_echo"
      ],
      "additionalProperties": false,
      "description": "Structured LBO result — typically the `result` field returned by `compute_lbo`."
    }
  },
  "required": [
    "ticker",
    "lbo_result"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}