Previous value: -"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to."New value: +"ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export."

Previous value: -"Stock ticker symbol, e.g. AAPL, MSFT, BRK.B"New value: +"Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'."

Previous value: -"^[A-Za-z.\\-]+$"New value: +"^[A-Za-z0-9.\\-]+$"

Previous value: -"Output shape. 'flat' (default) returns the legacy `metrics` object plus the additive `metrics_availability`/`metrics_provenance` sidecars. 'envelope' additionally attaches `metric_envelopes` — one canonical {metric,value,unit,scale,period,availability,provenance} object per metric."New value: +"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."

Previous value: -[
-  "absolute",
-  "thousands",
-  "millions",
-  "ratio",
-  "percent",
-  "shares"
-]New value: +[
+  "absolute",
+  "thousands",
+  "millions",
+  "ratio",
+  "percent",
+  "fraction",
+  "shares"
+]

Added value: +{
+  "additionalProperties": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "description": "The figure rendered exactly as it should be quoted in prose ($402.83B, 59.65%, $6.11). QUOTE THESE VERBATIM. Do not re-render the raw number in `metrics` yourself: a figure you reformat no longer matches the string Valuein can bind to its filing, so it is reported to the reader as unverified even though the underlying fact was sound.",
+  "type": "object"
+}

Added value: +{
+  "description": "ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt. Use THIS — not `last_updated` — when telling a user how current the fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to.",
+  "type": "string"
+}

Added value: +{
+  "description": "ISO timestamp when the price surfaces were last refreshed.",
+  "type": "string"
+}

Added value: +{
+  "description": "The figure rendered exactly as it should be quoted in prose ($391.04B, 23.7%, $6.11). QUOTE THIS VERBATIM rather than re-rounding `value` yourself — re-rendering a raw number is how a stated figure drifts away from the filing it came from.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Previous value: -[
-  "metric",
-  "value",
-  "unit",
-  "scale",
-  "period",
-  "availability",
-  "provenance"
-]New value: +[
+  "metric",
+  "value",
+  "unit",
+  "display",
+  "scale",
+  "period",
+  "availability",
+  "provenance"
+]

Previous value: -"Per-period provenance envelope + per-metric availability/provenance sidecars. 'compact' (default) returns source_filing + source_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."New value: +"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."

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "type": "string"
+}

Previous value: -[
-  "source_filing",
-  "source_url",
-  "restated_in_warehouse"
-]New value: +[
+  "source_filing",
+  "source_url",
+  "sec_url",
+  "document_url",
+  "inline_viewer_url",
+  "restated_in_warehouse"
+]

Added value: +{
+  "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).",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Per-call cost transparency. Omitted for subscription-only tools that have no PAYG-equivalent price.",
+  "properties": {
+    "amount_usd": {
+      "minimum": 0,
+      "type": "number"
+    },
+    "basis": {
+      "description": "payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed.",
+      "enum": [
+        "payg_charge",
+        "payg_rate_card"
+      ],
+      "type": "string"
+    },
+    "billed": {
+      "description": "true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "amount_usd",
+    "billed",
+    "basis"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
+  "minimum": 0,
+  "type": "integer"
+}

Added value: +"true iff a zero-look-ahead point-in-time cut was applied to every returned figure"

Previous value: -"Per-period provenance envelope. 'compact' (default) returns source_filing + source_url + restated flag for one-click SEC verification. 'full' adds first_filed_at + accepted_at for Bloomberg-Option-C restatement reasoning. 'off' omits lineage entirely."New value: +"Per-period provenance envelope + per-metric availability/provenance sidecars. 'compact' (default) returns source_filing + source_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."

Added value: +{
+  "default": "flat",
+  "description": "Output shape. 'flat' (default) returns the legacy `metrics` object plus the additive `metrics_availability`/`metrics_provenance` sidecars. 'envelope' additionally attaches `metric_envelopes` — one canonical {metric,value,unit,scale,period,availability,provenance} object per metric.",
+  "enum": [
+    "flat",
+    "envelope"
+  ],
+  "type": "string"
+}

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "availability": {
+        "$ref": "#/properties/data/items/properties/metrics_availability/additionalProperties"
+      },
+      "metric": {
+        "type": "string"
+      },
+      "period": {
+        "additionalProperties": false,
+        "properties": {
+          "fiscal_period": {
+            "type": "string"
+          },
+          "fiscal_year": {
+            "type": "integer"
+          },
+          "period_end": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "fiscal_year",
+          "fiscal_period",
+          "period_end"
+        ],
+        "type": "object"
+      },
+      "provenance": {
+        "$ref": "#/properties/data/items/properties/metrics_provenance/additionalProperties"
+      },
+      "scale": {
+        "enum": [
+          "absolute",
+          "thousands",
+          "millions",
+          "ratio",
+          "percent",
+          "shares"
+        ],
+        "type": "string"
+      },
+      "unit": {
+        "type": "string"
+      },
+      "value": {
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "metric",
+      "value",
+      "unit",
+      "scale",
+      "period",
+      "availability",
+      "provenance"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "Common shares outstanding (CommonSharesOutstanding) — equity-value→per-share divisor.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "description": "Short-term / marketable investments (ShortTermInvestments). Non-overlapping with `cash`; Wall-Street net_debt subtracts (cash + short_term_investments).",
+  "type": [
+    "number",
+    "null"
+  ]
+}

Previous value: -[
-  "revenue",
-  "gross_profit",
-  "operating_income",
-  "net_income",
-  "eps_diluted",
-  "total_assets",
-  "total_liabilities",
-  "stockholders_equity",
-  "cash",
-  "total_debt",
-  "operating_cash_flow",
-  "capex"
-]New value: +[
+  "revenue",
+  "gross_profit",
+  "operating_income",
+  "net_income",
+  "eps_diluted",
+  "total_assets",
+  "total_liabilities",
+  "stockholders_equity",
+  "cash",
+  "short_term_investments",
+  "total_debt",
+  "operating_cash_flow",
+  "capex",
+  "shares_outstanding"
+]

Added value: +{
+  "additionalProperties": {
+    "description": "Explicit availability status. A real reported zero is 'available' with value 0 — never null. 'not_reported' = filing omitted it; 'not_mapped' = XBRL mapping uncertain; 'suppressed' = below confidence; 'error' = compute/retrieval failed.",
+    "enum": [
+      "available",
+      "not_reported",
+      "not_mapped",
+      "suppressed",
+      "error"
+    ],
+    "type": "string"
+  },
+  "type": "object"
+}

Added value: +{
+  "additionalProperties": {
+    "additionalProperties": false,
+    "description": "Provenance pointer: origin 'dataset' carries the SHA-256 fact_id + source filing; origin 'computed' carries the formula + the input fact_ids (verify with verify_fact_lineage).",
+    "properties": {
+      "accepted_at": {
+        "type": "string"
+      },
+      "fact_id": {
+        "type": "string"
+      },
+      "formula": {
+        "type": "string"
+      },
+      "inputs": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "fact_id": {
+              "type": "string"
+            },
+            "role": {
+              "type": "string"
+            },
+            "value": {
+              "type": [
+                "number",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "role"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "origin": {
+        "enum": [
+          "dataset",
+          "computed"
+        ],
+        "type": "string"
+      },
+      "source_filing": {
+        "type": "string"
+      },
+      "source_url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "origin"
+    ],
+    "type": "object"
+  },
+  "type": "object"
+}

Added value: +{
+  "type": "string"
+}

Removed value: -{
-  "type": "boolean"
-}

Added value: +{
+  "type": "boolean"
+}

Previous value: -[
-  "source_filing",
-  "source_url",
-  "restated"
-]New value: +[
+  "source_filing",
+  "source_url",
+  "restated_in_warehouse"
+]

Added value: +{
+  "type": "string"
+}

Added value: +{
+  "type": "number"
+}

Previous value: -[
-  "quote_id",
-  "tool",
-  "meter",
-  "amount_cents",
-  "retry_token_hash"
-]New value: +[
+  "quote_id",
+  "tool",
+  "meter",
+  "amount_cents",
+  "ticker_count",
+  "entity_scope_hash",
+  "retry_token_hash"
+]

Added value: +{
+  "additionalProperties": false,
+  "description": "Set when this single response was paid for via the agent-pay PAYG flow — the rate-limit / depth-limit checks were bypassed for this call only.",
+  "properties": {
+    "amount_cents": {
+      "type": "number"
+    },
+    "meter": {
+      "type": "string"
+    },
+    "quote_id": {
+      "type": "string"
+    },
+    "retry_token_hash": {
+      "type": "string"
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "quote_id",
+    "tool",
+    "meter",
+    "amount_cents",
+    "retry_token_hash"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Soft-warning array for partial fulfillment. Each entry carries a stable subcode + remediation.options[]. AI agents pattern-match on subcode.",
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "code": {
+        "const": "LIMIT_EXCEEDED",
+        "type": "string"
+      },
+      "current_plan": {
+        "type": "string"
+      },
+      "extensions": {
+        "additionalProperties": {},
+        "type": "object"
+      },
+      "limit_type": {
+        "type": "string"
+      },
+      "limit_value": {},
+      "remediation": {
+        "additionalProperties": true,
+        "properties": {
+          "contact_sales": {
+            "type": "string"
+          },
+          "default_action": {
+            "type": "string"
+          },
+          "options": {
+            "items": {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "pricing_page": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "options",
+          "default_action",
+          "pricing_page",
+          "contact_sales"
+        ],
+        "type": "object"
+      },
+      "requested_value": {},
+      "returned_value": {},
+      "subcode": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "subcode",
+      "limit_type",
+      "current_plan",
+      "remediation"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Added value: +{
+  "default": "compact",
+  "description": "Per-period provenance envelope. 'compact' (default) returns source_filing + source_url + restated flag for one-click SEC verification. 'full' adds first_filed_at + accepted_at for Bloomberg-Option-C restatement reasoning. 'off' omits lineage entirely.",
+  "enum": [
+    "off",
+    "compact",
+    "full"
+  ],
+  "type": "string"
+}

Added value: +{
+  "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.",
+  "type": "boolean"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Set when fewer rows were returned than requested — explains why and points to a remedy",
+  "properties": {
+    "current_plan": {
+      "type": "string"
+    },
+    "plan_limit": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "reason": {
+      "enum": [
+        "PLAN_LIMIT",
+        "DATA_NOT_AVAILABLE",
+        "FISCAL_YEAR_BOUNDARY_FILTER",
+        "OTHER"
+      ],
+      "type": "string"
+    },
+    "requested": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "returned": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "upgrade_required_for": {
+      "type": "string"
+    },
+    "upgrade_url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "requested",
+    "returned",
+    "reason"
+  ],
+  "type": "object"
+}

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "accepted_at": {
+      "type": "string"
+    },
+    "first_filed_at": {
+      "type": "string"
+    },
+    "restated": {
+      "type": "boolean"
+    },
+    "source_filing": {
+      "type": "string"
+    },
+    "source_url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "source_filing",
+    "source_url",
+    "restated"
+  ],
+  "type": "object"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Server-side invariants run on this response",
+  "properties": {
+    "notes": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "validation_failed": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "detail": {
+            "type": "string"
+          },
+          "rule": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "rule",
+          "detail"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "validation_passed": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "validation_passed",
+    "validation_failed",
+    "notes"
+  ],
+  "type": "object"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Caller's remaining budget",
+  "properties": {
+    "limit": {
+      "type": "integer"
+    },
+    "remaining": {
+      "type": "integer"
+    },
+    "reset_at": {
+      "description": "ISO 8601 timestamp when the window resets",
+      "type": "string"
+    },
+    "window": {
+      "enum": [
+        "minute",
+        "hour"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "limit",
+    "remaining",
+    "reset_at",
+    "window"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Per-request correlation id (8-char)",
+  "type": "string"
+}

Previous value: -"Point-in-time date (YYYY-MM-DD). Only returns facts with knowledge_at on or before this date — eliminates look-ahead bias for backtesting. Omit for the full dataset."New value: +"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."

Added value: +{
+  "type": "string"
+}

Removed value: -{
-  "type": "string"
-}

Previous value: -[
-  "fiscal_year",
-  "fiscal_period",
-  "period_end",
-  "filing_date",
-  "knowledge_at",
-  "metrics"
-]New value: +[
+  "fiscal_year",
+  "fiscal_period",
+  "period_end",
+  "filing_date",
+  "accepted_at",
+  "metrics"
+]

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Previous value: -[
-  "revenue",
-  "net_income",
-  "eps_diluted",
-  "total_assets",
-  "total_liabilities",
-  "operating_cash_flow",
-  "capex"
-]New value: +[
+  "revenue",
+  "gross_profit",
+  "operating_income",
+  "net_income",
+  "eps_diluted",
+  "total_assets",
+  "total_liabilities",
+  "stockholders_equity",
+  "cash",
+  "total_debt",
+  "operating_cash_flow",
+  "capex"
+]