Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Peer Comparables

get_peer_comparables

Read-onlyIdempotent

Get ratio-based peer comparison for a company and its closest competitors. Peers are selected by matching 2-digit SIC industry code. Returns pipeline-computed ratios from up to 10 peers alongside the subject company for direct benchmarking. Ratio categories: profitability, liquidity, leverage, efficiency, per_share, owner_earnings, valuation. TTM (trailing twelve months) ratios are used when available for the most current view. The exact 4-digit code is matched first, then the 3- and 2-digit groupings, with S&P 500 members first within each. Each company appears once, under its main listed share class; a candidate with no figures for the period is left out and counted in peers_omitted_no_data. Without as_of_date, peers are companies listed today. With as_of_date, peers are companies listed on that date — including ones delisted since — ranked by S&P 500 membership on that date, and figures are limited to that date: by SEC acceptance time when the ratio data carries it (_meta.pit_safe=true), otherwise by period end (_meta.pit_safe=false). Set peer_universe to sp500_sector to compare against S&P 500 members in the subject's own sector, ranked by latest fiscal-year market cap, instead of SIC-code peers. Available on every plan — sample returns the subset covered by the sample bucket.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of peers to return alongside the subject company (1–10). Defaults to 5.
`ticker`	Yes	Subject company ticker or CIK, e.g. AAPL or '0000320193'. Peers are auto-selected by SIC code.
`as_of_date`	No	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).
`categories`	No	Ratio categories to include in the comparison. Defaults to profitability, valuation, and leverage.
`peer_universe`	No	Where peers come from: 'sic' (default) matches SIC industry codes; 'sp500_sector' uses S&P 500 members in the subject's own sector, largest market cap first.
`period_end_before`	No	Alias of as_of_date (as_of_date preferred — the canonical name). Only include ratios with period_end on or before this date.

Output Schema

Name	Required	Description
`data`	Yes	One row per company (subject + peers): ticker, cik, name, sector, industry, is_subject, ratios
`note`	No
`_meta`	Yes	Provenance envelope — data lineage for every MCP response
`lineage`	No	Provenance for pipeline-derived values (ratio.parquet / factor_scores.parquet): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run).
`subject`	Yes	Subject ticker the peer set is built around
`as_of_date`	No
`categories`	Yes	Ratio categories included in each peer panel
`peers_returned`	Yes
`subject_ratios`	No	The subject company's ratio panel
`period_end_before`	No
`peers_omitted_no_data`	No	Candidate peers left out because they had no ratio figures for the period; each was replaced by the next-closest candidate

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 29, 2026

changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description

Previous value: -"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."New value: +"payg_charge = real pay-per-call charge (a card or MPP payment through agent-pay). payg_rate_card = indicative price, not billed."

Changed2 schema fields changedOct 29, 2026

changedOutput schema / properties / _meta / properties / cost_usd / properties / basis / description

Previous value: -"payg_charge = real agent-pay charge. payg_rate_card = indicative price, not billed."New value: +"payg_charge = real charge (agent-pay or your balance). payg_rate_card = indicative price, not billed."

changedOutput schema / properties / _meta / properties / cost_usd / properties / billed / description

Previous value: -"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value; your plan already covers this call for free."New value: +"true = this amount was actually charged via PAYG for this call. false = indicative PAYG-equivalent value only: no charge was made for this call (it was within your plan)."

Changed1 schema field changedOct 23, 2026
- removedOutput schema / properties / lineage / properties / pit_safe / const
```
Removed value: -false
```

Changed1 schema field changedOct 18, 2026

addedInput schema / properties / peer_universe

Added value: +{
+  "description": "Where peers come from: 'sic' (default) matches SIC industry codes; 'sp500_sector' uses S&P 500 members in the subject's own sector, largest market cap first.",
+  "enum": [
+    "sic",
+    "sp500_sector"
+  ],
+  "type": "string"
+}

Changed21 schema fields changedOct 16, 2026

changedInput schema / properties / as_of_date / description

Previous value: -"Historical cutoff, YYYY-MM-DD: ratios known by this date, with peers ranked by index membership on it, e.g. 2024-06-30."New value: +"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)."

changedInput schema / properties / categories / description

Previous value: -"Groups to include: profitability, liquidity, leverage, efficiency, per_share, owner_earnings or valuation; defaults to profitability, valuation and leverage, e.g. [\"valuation\"]."New value: +"Ratio categories to include in the comparison. Defaults to profitability, valuation, and leverage."

changedInput schema / properties / limit / description

Previous value: -"Number of peers besides the company, 1 to 10; defaults to 5, e.g. 8."New value: +"Maximum number of peers to return alongside the subject company (1–10). Defaults to 5."

addedInput schema / properties / period_end_before

Added value: +{
+  "description": "Alias of as_of_date (as_of_date preferred — the canonical name). Only include ratios with period_end on or before this date.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

changedInput schema / properties / ticker / description

Previous value: -"Ticker symbol or SEC CIK of the company to compare, e.g. AAPL."New value: +"Subject company ticker or CIK, e.g. AAPL or '0000320193'. Peers are auto-selected by SIC code."

addedOutput schema / properties / _meta / properties / cost_usd

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"
+}

addedOutput schema / properties / _meta / properties / data_plan

Added value: +{
+  "description": "Access plan: sample | sp500 | pro | full",
+  "type": "string"
+}

changedOutput schema / properties / _meta / properties / fundamentals_as_of / description

Previous value: -"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."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."

addedOutput schema / properties / _meta / properties / last_updated

Added value: +{
+  "description": "ISO timestamp when the snapshot was exported",
+  "type": "string"
+}

addedOutput schema / properties / _meta / properties / latency_ms

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

addedOutput schema / properties / _meta / properties / limit_warnings

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"
+}

addedOutput schema / properties / _meta / properties / payg_override

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"
+    },
+    "entity_scope_hash": {
+      "type": "string"
+    },
+    "meter": {
+      "type": "string"
+    },
+    "quote_id": {
+      "type": "string"
+    },
+    "retry_token_hash": {
+      "type": "string"
+    },
+    "ticker_count": {
+      "type": "number"
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "quote_id",
+    "tool",
+    "meter",
+    "amount_cents",
+    "ticker_count",
+    "entity_scope_hash",
+    "retry_token_hash"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / _meta / properties / rate_limit

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"
+}

addedOutput schema / properties / _meta / properties / request_id

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

addedOutput schema / properties / _meta / properties / schema_version

Added value: +{
+  "description": "Parquet schema version from manifest.json",
+  "type": "string"
+}

addedOutput schema / properties / _meta / properties / snapshot

Added value: +{
+  "description": "Snapshot directory name (e.g. snapshot_20260420)",
+  "type": "string"
+}

addedOutput schema / properties / _meta / properties / truncation / properties / current_plan
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / _meta / properties / truncation / properties / upgrade_required_for
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / _meta / properties / truncation / properties / upgrade_url
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / _meta / required

Previous value: -[
-  "source",
-  "pit_safe"
-]New value: +[
+  "data_plan",
+  "schema_version",
+  "snapshot",
+  "last_updated",
+  "source",
+  "pit_safe"
+]

changedOutput schema / properties / lineage / description

Previous value: -"Provenance for pipeline-derived values (the ratio table / the factor_scores table): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run)."New value: +"Provenance for pipeline-derived values (ratio.parquet / factor_scores.parquet): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run)."

Changed1 schema field changedSep 29, 2026

removedInput schema / properties / period_end_before

Removed value: -{
-  "description": "Older name for as_of_date, same format and meaning; as_of_date wins when both are set, e.g. 2024-06-30.",
-  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-  "type": "string"
-}

Changed23 schema fields changedSep 29, 2026

changedInput schema / properties / as_of_date / description

Previous value: -"Historical cutoff (canonical cross-tool date param) for the FIGURE leg: PIT by ratio accepted_at when present (latest-knowable, zero look-ahead, _meta.pit_safe=true), else by ratio.period_end (pit_safe=false). Peer SELECTION still uses current S&P 500 membership as a ranking proxy regardless of as_of_date (W3-G2)."New value: +"Historical cutoff, YYYY-MM-DD: ratios known by this date, with peers ranked by index membership on it, e.g. 2024-06-30."

changedInput schema / properties / categories / description

Previous value: -"Ratio categories to include in the comparison. Defaults to profitability, valuation, and leverage."New value: +"Groups to include: profitability, liquidity, leverage, efficiency, per_share, owner_earnings or valuation; defaults to profitability, valuation and leverage, e.g. [\"valuation\"]."

addedInput schema / properties / categories / maxItems
```
Added value: +7
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of peers to return alongside the subject company (1–10). Defaults to 5."New value: +"Number of peers besides the company, 1 to 10; defaults to 5, e.g. 8."

changedInput schema / properties / period_end_before / description

Previous value: -"Alias of as_of_date (as_of_date preferred — the canonical name). Only include ratios with period_end on or before this date."New value: +"Older name for as_of_date, same format and meaning; as_of_date wins when both are set, e.g. 2024-06-30."

changedInput schema / properties / ticker / description

Previous value: -"Subject company ticker or CIK, e.g. AAPL or '0000320193'. Peers are auto-selected by SIC code."New value: +"Ticker symbol or SEC CIK of the company to compare, e.g. AAPL."

removedOutput schema / properties / _meta / properties / cost_usd

Removed 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"
-}

removedOutput schema / properties / _meta / properties / data_plan

Removed value: -{
-  "description": "Access plan: sample | sp500 | pro | full",
-  "type": "string"
-}

changedOutput schema / properties / _meta / properties / fundamentals_as_of / description

Previous 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."New value: +"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."

removedOutput schema / properties / _meta / properties / last_updated

Removed value: -{
-  "description": "ISO timestamp when the snapshot was exported",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / latency_ms

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

removedOutput schema / properties / _meta / properties / limit_warnings

Removed 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"
-}

removedOutput schema / properties / _meta / properties / payg_override

Removed 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"
-    },
-    "entity_scope_hash": {
-      "type": "string"
-    },
-    "meter": {
-      "type": "string"
-    },
-    "quote_id": {
-      "type": "string"
-    },
-    "retry_token_hash": {
-      "type": "string"
-    },
-    "ticker_count": {
-      "type": "number"
-    },
-    "tool": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "quote_id",
-    "tool",
-    "meter",
-    "amount_cents",
-    "ticker_count",
-    "entity_scope_hash",
-    "retry_token_hash"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / rate_limit

Removed 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"
-}

removedOutput schema / properties / _meta / properties / request_id

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

removedOutput schema / properties / _meta / properties / schema_version

Removed value: -{
-  "description": "Parquet schema version from manifest.json",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / snapshot

Removed value: -{
-  "description": "Snapshot directory name (e.g. snapshot_20260420)",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / truncation / properties / current_plan
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / _meta / properties / truncation / properties / upgrade_required_for
```
Removed value: -{
-  "type": "string"
-}
```
removedOutput schema / properties / _meta / properties / truncation / properties / upgrade_url
```
Removed value: -{
-  "type": "string"
-}
```

changedOutput schema / properties / _meta / required

Previous value: -[
-  "data_plan",
-  "schema_version",
-  "snapshot",
-  "last_updated",
-  "source",
-  "pit_safe"
-]New value: +[
+  "source",
+  "pit_safe"
+]

changedOutput schema / properties / lineage / description

Previous value: -"Provenance for pipeline-derived values (ratio.parquet / factor_scores.parquet): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run)."New value: +"Provenance for pipeline-derived values (the ratio table / the factor_scores table): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run)."

addedOutput schema / properties / peers_omitted_no_data

Added value: +{
+  "description": "Candidate peers left out because they had no ratio figures for the period; each was replaced by the next-closest candidate",
+  "type": "integer"
+}

Changed1 schema field changedSep 18, 2026

changedOutput schema / properties / _meta / properties / fundamentals_as_of / description

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."

Changed2 schema fields changedSep 11, 2026

changedInput schema / properties / ticker / description

Previous value: -"Subject company ticker, e.g. AAPL. Peers are auto-selected by SIC code."New value: +"Subject company ticker or CIK, e.g. AAPL or '0000320193'. Peers are auto-selected by SIC code."

changedInput schema / properties / ticker / pattern

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

Changed2 schema fields changedJul 25, 2026

addedOutput schema / properties / _meta / properties / fundamentals_as_of

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"
+}

addedOutput schema / properties / _meta / properties / price_as_of

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

Changed2 schema fields changedJul 7, 2026

addedOutput schema / properties / _meta / properties / cost_usd

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"
+}

addedOutput schema / properties / _meta / properties / latency_ms

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

Changed2 schema fields changedJun 26, 2026

changedInput schema / properties / as_of_date / description

Previous value: -"Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics) for the figure leg. When the ratio data carries an SEC accepted_at timestamp, this filters the figures point-in-time by accepted_at (latest-knowable per ratio, zero look-ahead, _meta.pit_safe=true). When it does not (current data), it filters by ratio.period_end (_meta.pit_safe=false). Peer SELECTION still uses current S&P 500 membership as a ranking proxy regardless of as_of_date (W3-G2)."New value: +"Historical cutoff (canonical cross-tool date param) for the FIGURE leg: PIT by ratio accepted_at when present (latest-knowable, zero look-ahead, _meta.pit_safe=true), else by ratio.period_end (pit_safe=false). Peer SELECTION still uses current S&P 500 membership as a ranking proxy regardless of as_of_date (W3-G2)."

changedInput schema / properties / period_end_before / description

Previous value: -"Alias of as_of_date — either works; as_of_date is preferred (canonical name used across every time-series tool). Only include ratios with period_end on or before this date."New value: +"Alias of as_of_date (as_of_date preferred — the canonical name). Only include ratios with period_end on or before this date."

Changed1 schema field changedJun 18, 2026
- addedOutput schema / properties / _meta / properties / pit_safe / description
```
Added value: +"true iff a zero-look-ahead point-in-time cut was applied to every returned figure"
```

Changed2 schema fields changedJun 5, 2026

changedInput schema / properties / as_of_date / description

Previous value: -"Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics). Only include ratios whose period_end is on or before this date, for historical peer-benchmarking snapshots. Ratios are period_end-keyed (pipeline-derived), not accepted_at PIT."New value: +"Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics) for the figure leg. When the ratio data carries an SEC accepted_at timestamp, this filters the figures point-in-time by accepted_at (latest-knowable per ratio, zero look-ahead, _meta.pit_safe=true). When it does not (current data), it filters by ratio.period_end (_meta.pit_safe=false). Peer SELECTION still uses current S&P 500 membership as a ranking proxy regardless of as_of_date (W3-G2)."

addedOutput schema / properties / lineage

Added value: +{
+  "additionalProperties": false,
+  "description": "Provenance for pipeline-derived values (ratio.parquet / factor_scores.parquet): source table + pipeline computed_at, plus a pointer to the tools that return filing-level lineage. NOT point-in-time (recomputed on each pipeline run).",
+  "properties": {
+    "computed_at": {
+      "type": "string"
+    },
+    "derivation": {
+      "const": "pipeline_computed",
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "pit_safe": {
+      "const": false,
+      "type": "boolean"
+    },
+    "source_table": {
+      "type": "string"
+    },
+    "verify_with": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "source_table",
+    "derivation",
+    "pit_safe",
+    "note",
+    "verify_with"
+  ],
+  "type": "object"
+}

Changed1 schema field changedJun 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "_meta": {
+      "additionalProperties": false,
+      "description": "Provenance envelope — data lineage for every MCP response",
+      "properties": {
+        "as_of_date": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "data_plan": {
+          "description": "Access plan: sample | sp500 | pro | full",
+          "type": "string"
+        },
+        "data_quality": {
+          "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"
+        },
+        "last_updated": {
+          "description": "ISO timestamp when the snapshot was exported",
+          "type": "string"
+        },
+        "limit_warnings": {
+          "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"
+        },
+        "payg_override": {
+          "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"
+            },
+            "entity_scope_hash": {
+              "type": "string"
+            },
+            "meter": {
+              "type": "string"
+            },
+            "quote_id": {
+              "type": "string"
+            },
+            "retry_token_hash": {
+              "type": "string"
+            },
+            "ticker_count": {
+              "type": "number"
+            },
+            "tool": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "quote_id",
+            "tool",
+            "meter",
+            "amount_cents",
+            "ticker_count",
+            "entity_scope_hash",
+            "retry_token_hash"
+          ],
+          "type": "object"
+        },
+        "pit_safe": {
+          "type": "boolean"
+        },
+        "rate_limit": {
+          "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"
+        },
+        "request_id": {
+          "description": "Per-request correlation id (8-char)",
+          "type": "string"
+        },
+        "result_count": {
+          "type": "integer"
+        },
+        "schema_version": {
+          "description": "Parquet schema version from manifest.json",
+          "type": "string"
+        },
+        "snapshot": {
+          "description": "Snapshot directory name (e.g. snapshot_20260420)",
+          "type": "string"
+        },
+        "source": {
+          "const": "SEC EDGAR",
+          "type": "string"
+        },
+        "ticker": {
+          "type": "string"
+        },
+        "truncation": {
+          "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"
+        }
+      },
+      "required": [
+        "data_plan",
+        "schema_version",
+        "snapshot",
+        "last_updated",
+        "source",
+        "pit_safe"
+      ],
+      "type": "object"
+    },
+    "as_of_date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "categories": {
+      "description": "Ratio categories included in each peer panel",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "data": {
+      "description": "One row per company (subject + peers): ticker, cik, name, sector, industry, is_subject, ratios",
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "note": {
+      "type": "string"
+    },
+    "peers_returned": {
+      "type": "integer"
+    },
+    "period_end_before": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "subject": {
+      "description": "Subject ticker the peer set is built around",
+      "type": "string"
+    },
+    "subject_ratios": {
+      "additionalProperties": true,
+      "description": "The subject company's ratio panel",
+      "properties": {},
+      "type": "object"
+    }
+  },
+  "required": [
+    "_meta",
+    "subject",
+    "categories",
+    "peers_returned",
+    "data"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedJun 2, 2026

addedInput schema / properties / as_of_date

Added value: +{
+  "description": "Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics). Only include ratios whose period_end is on or before this date, for historical peer-benchmarking snapshots. Ratios are period_end-keyed (pipeline-derived), not accepted_at PIT.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

changedInput schema / properties / period_end_before / description

Previous value: -"Historical cutoff: only include ratios with period_end on or before this date. Use this for historical peer benchmarking snapshots."New value: +"Alias of as_of_date — either works; as_of_date is preferred (canonical name used across every time-series tool). Only include ratios with period_end on or before this date."

First observedApr 22, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare read-only/idempotent/non-destructive; the description adds substantial context they don't cover: TTM preference, dedup by main listed share class, exclusion of no-data candidates counted in peers_omitted_no_data, and the point-in-time semantics including _meta.pit_safe handling for delisted names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and peer-selection logic, then conditionals. It is dense rather than padded, though the as_of_date paragraph substantially repeats the schema's own description and the peer_universe sentence duplicates the enum docs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter analytical tool with an output schema, everything an agent needs to call it correctly is present: peer selection, ranking, date semantics, coverage limits, and the full ratio category list. Return-value structure is rightly deferred to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a 3 is the floor; the description exceeds it by explaining what peer_universe actually changes (SIC matching vs S&P 500 sector ranked by fiscal-year market cap) and how as_of_date alters the peer universe, not just the figures. The period_end_before alias is not mentioned in prose, but the schema covers it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Get ratio-based peer comparison for a company and its closest competitors') and immediately specifies the selection mechanism (2-digit SIC, extended to 4/3-digit matching). It is unmistakable against siblings like get_financial_ratios (single company) or screen_universe (filtering).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear conditional guidance inside the tool: use peer_universe=sp500_sector for sector benchmarking instead of SIC peers, and explains plan/sample behavior. It stops short of naming sibling tools (e.g., generate_comps_xlsx, compare_periods) as alternatives, so routing across the toolset is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Valuein — SEC EDGAR Fundamentals & Smart-Money Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Peer Comparables

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources