Skip to main content
Glama
Sign In

Valuein — SEC EDGAR Fundamentals & Smart-Money Data

by io.github.valuein
OverviewDiscussionsAdmin

Search Companies

search_companies
Read-onlyIdempotent

Search for US public companies by name, ticker symbol, CIK (SEC identifier), or SIC industry code. Returns ticker, company name, sector, industry, exchange, and current S&P 500 membership status. Use this tool to resolve a company name to ticker/CIK before calling get_company_fundamentals, get_valuation_metrics, or other tools that require a ticker — they do not fuzzy-match company names.

Use this tool — NOT get_pit_universe — when the user asks about CURRENT S&P 500 members. To list current S&P 500 members, call search_companies({ is_sp500: true }) (the is_sp500 filter is itself a valid search parameter, so no other input is required). This returns the live snapshot as of query time. Example: "List 5 current S&P 500 members" → call search_companies({ is_sp500: true, limit: 5 }).

Use get_pit_universe ONLY when the user explicitly needs a survivorship-free historical universe as of a specific past date (e.g. "S&P 500 members as of March 2018"). If the user says "current," "today," "now," or gives no date, use search_companies instead.

One ticker can return two rows. A CIK identifies a registrant, not a company, so a reincorporation or holdco reorganisation moves the ticker to a NEW CIK while the filing history stays under the old one. Both rows are real. Use is_active to tell them apart: true is the current listing, false is the superseded one and carries listed_until. Prefer is_active over status — status is an entity-level flag that is unreliable in both directions.

Data details: sic_code is the 4-digit SIC; industry is the human-readable label. sector is SIC-derived with GICS-style labels — NOT licensed GICS, so industrial conglomerates may map differently from official GICS (e.g. 3M → 'Health Care' by SIC vs Industrials by GICS). S&P 500 membership is sourced from index_membership.parquet (current SP500 = index_name='SP500' AND removal_date IS NULL). Available on all plans.

CIK is the canonical, stable identifier — prefer it for backtests and archival work. A ticker can be retired and later RECYCLED to an unrelated company (DEC is now Diversified Energy, AMR is Alpha Metallurgical, ARC is a document company today), so a ticker-only reference can silently drift to the wrong issuer years later. A purely-numeric query (or the dedicated cik param) resolves by CIK. Every company-scoped tool (get_company_fundamentals, get_financial_ratios, get_stock_price, etc.) accepts the cik this tool returns in place of ticker — carry it forward across a multi-step workflow instead of re-resolving by ticker each call. include_inactive defaults to true: this is a survivorship-free product, so delisted/superseded listings are never hidden by default.

Input Schema

NameRequiredDescriptionDefault
cikNoSEC CIK identifier (exact match). E.g. '0000320193' for Apple.
limitNoMaximum number of results to return (1–50). Defaults to 25.
queryNoFree-text search over company name and ticker. Case-insensitive. E.g. 'Apple', 'AAPL', 'Microsoft', 'semiconductor'.
is_sp500NoFilter to current S&P 500 members only.
sic_codeNo4-digit SIC industry code. E.g. '7372' for Prepackaged Software.
is_activeNoFilter 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.
include_inactiveNoWhether 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.

Output Schema

NameRequiredDescriptionDefault
_metaYesProvenance envelope — data lineage for every MCP response
queryYes
companiesYes
results_returnedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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."
  2. Changed2 schema fields changed
    • 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)."
  3. Changed25 schema fields changed
    • changedInput schema / properties / cik / description
      Previous value: -"SEC CIK to match exactly, digits only, leading zeros optional, e.g. 0000320193."New value: +"SEC CIK identifier (exact match). E.g. '0000320193' for Apple."
    • addedInput schema / properties / include_inactive
      Added value: +{
+  "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.",
+  "type": "boolean"
+}
    • changedInput schema / properties / is_active / description
      Previous value: -"true for current listings only, false for delisted or superseded listings only; omit for both, e.g. true."New value: +"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."
    • changedInput schema / properties / is_sp500 / description
      Previous value: -"true to return current S&P 500 members only, e.g. true."New value: +"Filter to current S&P 500 members only."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of results, 1 to 50; defaults to 25, e.g. 10."New value: +"Maximum number of results to return (1–50). Defaults to 25."
    • changedInput schema / properties / query / description
      Previous value: -"Text matched against company names and tickers, case-insensitive; an all-digit value matches a CIK exactly, e.g. Apple."New value: +"Free-text search over company name and ticker. Case-insensitive. E.g. 'Apple', 'AAPL', 'Microsoft', 'semiconductor'."
    • changedInput schema / properties / sic_code / description
      Previous value: -"Four-digit SIC industry code to match exactly, e.g. 7372."New value: +"4-digit SIC industry code. E.g. '7372' for Prepackaged Software."
    • 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 / companies / items / properties / status / description
      Previous value: -"Entity-level flag from entity.status. Read `is_active` instead."New value: +"Entity-level flag from entity.status. Kept for back-compat and NOT a reliable liveness signal — it is wrong in both directions on real data (American Electric Power, a current S&P 500 member, reads 'INACTIVE'). Read `is_active` instead."
    • changedOutput schema / properties / companies / items / properties / valid_from / description
      Previous value: -"Date this listing became current, or null when unknown."New value: +"Date this listing became current, or null when unknown. Paired with valid_to/cik/is_active so an agent can disambiguate a RECYCLED ticker — two rows for one symbol, each covering a different window — without a second call."
    • removedOutput schema / properties / coverage_note
      Removed value: -{
-  "description": "Present only when no company matched: what this connector covers.",
-  "type": "string"
-}
  4. Changed2 schema fields changed
    • removedInput schema / properties / include_inactive
      Removed value: -{
-  "default": true,
-  "description": "Whether delisted or superseded listings may appear; defaults to true and is ignored when is_active is set, e.g. false.",
-  "type": "boolean"
-}
    • addedOutput schema / properties / coverage_note
      Added value: +{
+  "description": "Present only when no company matched: what this connector covers.",
+  "type": "string"
+}
  5. Changed24 schema fields changed
    • changedInput schema / properties / cik / description
      Previous value: -"SEC CIK identifier (exact match). E.g. '0000320193' for Apple."New value: +"SEC CIK to match exactly, digits only, leading zeros optional, e.g. 0000320193."
    • changedInput schema / properties / include_inactive / description
      Previous value: -"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."New value: +"Whether delisted or superseded listings may appear; defaults to true and is ignored when is_active is set, e.g. false."
    • changedInput schema / properties / is_active / description
      Previous value: -"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."New value: +"true for current listings only, false for delisted or superseded listings only; omit for both, e.g. true."
    • changedInput schema / properties / is_sp500 / description
      Previous value: -"Filter to current S&P 500 members only."New value: +"true to return current S&P 500 members only, e.g. true."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of results to return (1–50). Defaults to 25."New value: +"Maximum number of results, 1 to 50; defaults to 25, e.g. 10."
    • changedInput schema / properties / query / description
      Previous value: -"Free-text search over company name and ticker. Case-insensitive. E.g. 'Apple', 'AAPL', 'Microsoft', 'semiconductor'."New value: +"Text matched against company names and tickers, case-insensitive; an all-digit value matches a CIK exactly, e.g. Apple."
    • changedInput schema / properties / sic_code / description
      Previous value: -"4-digit SIC industry code. E.g. '7372' for Prepackaged Software."New value: +"Four-digit SIC industry code to match exactly, e.g. 7372."
    • 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 / companies / items / properties / status / description
      Previous value: -"Entity-level flag from entity.status. Kept for back-compat and NOT a reliable liveness signal — it is wrong in both directions on real data (American Electric Power, a current S&P 500 member, reads 'INACTIVE'). Read `is_active` instead."New value: +"Entity-level flag from entity.status. Read `is_active` instead."
    • changedOutput schema / properties / companies / items / properties / valid_from / description
      Previous value: -"Date this listing became current, or null when unknown. Paired with valid_to/cik/is_active so an agent can disambiguate a RECYCLED ticker — two rows for one symbol, each covering a different window — without a second call."New value: +"Date this listing became current, or null when unknown."
  6. Changed1 schema field changed
    • 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."
  7. Changed4 schema fields changed
    • addedInput schema / properties / include_inactive
      Added value: +{
+  "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.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / companies / items / properties / valid_from
      Added value: +{
+  "description": "Date this listing became current, or null when unknown. Paired with valid_to/cik/is_active so an agent can disambiguate a RECYCLED ticker — two rows for one symbol, each covering a different window — without a second call.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / companies / items / properties / valid_to
      Added value: +{
+  "description": "Same value as `listed_until`, under the CIK-first-resolution naming convention. Both are returned for back-compat.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / companies / items / required
      Previous value: -[
-  "cik",
-  "ticker",
-  "name",
-  "sector",
-  "industry",
-  "sic_code",
-  "exchange",
-  "status",
-  "is_active",
-  "listed_until",
-  "is_sp500"
-]New value: +[
+  "cik",
+  "ticker",
+  "name",
+  "sector",
+  "industry",
+  "sic_code",
+  "exchange",
+  "status",
+  "is_active",
+  "listed_until",
+  "valid_from",
+  "valid_to",
+  "is_sp500"
+]
  8. Changed5 schema fields changed
    • changedInput schema / properties / is_active / description
      Previous value: -"Filter to active (currently trading) companies only."New value: +"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."
    • addedOutput schema / properties / companies / items / properties / is_active
      Added value: +{
+  "description": "Whether THIS listing is the current one for its ticker. When a company reincorporates or forms a holdco, SEC issues a new CIK and moves the ticker to it, so one symbol can return two rows — the superseded listing (false, with `listed_until` set) and the current one (true).",
+  "type": "boolean"
+}
    • addedOutput schema / properties / companies / items / properties / listed_until
      Added value: +{
+  "description": "Date this listing stopped being current, or null while it still is. Non-null means the ticker moved to another registrant or the security was delisted.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / companies / items / properties / status / description
      Added value: +"Entity-level flag from entity.status. Kept for back-compat and NOT a reliable liveness signal — it is wrong in both directions on real data (American Electric Power, a current S&P 500 member, reads 'INACTIVE'). Read `is_active` instead."
    • changedOutput schema / properties / companies / items / required
      Previous value: -[
-  "cik",
-  "ticker",
-  "name",
-  "sector",
-  "industry",
-  "sic_code",
-  "exchange",
-  "status",
-  "is_sp500"
-]New value: +[
+  "cik",
+  "ticker",
+  "name",
+  "sector",
+  "industry",
+  "sic_code",
+  "exchange",
+  "status",
+  "is_active",
+  "listed_until",
+  "is_sp500"
+]
  9. Changed2 schema fields changed
    • 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"
+}
  10. Changed3 schema fields changed
    • 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"
+}
    • addedOutput schema / properties / companies / items / properties / match_confidence
      Added value: +{
+  "description": "How confidently this result matches your query text: exact = exact ticker/name match, high = name starts with query, medium = word-boundary or ticker-prefix match, low = bare substring match. Omitted for filter-only calls with no text query.",
+  "enum": [
+    "exact",
+    "high",
+    "medium",
+    "low"
+  ],
+  "type": "string"
+}
  11. Changed1 schema field changed
    • 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"
  12. Changed3 schema fields changed
    • addedOutput schema / properties / _meta / properties / payg_override / properties / entity_scope_hash
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / _meta / properties / payg_override / properties / ticker_count
      Added value: +{
+  "type": "number"
+}
    • changedOutput schema / properties / _meta / properties / payg_override / required
      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"
+]
  13. Changed1 schema field changed
    • 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"
+    },
+    "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"
+}
  14. Changed1 schema field changed
    • 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"
+}
  15. Changed1 schema field changed
    • addedOutput schema / properties / _meta / properties / truncation
      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"
+}
  16. Changed3 schema fields changed
    • addedOutput schema / properties / _meta / properties / data_quality
      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"
+}
    • 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"
+}
  17. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds substantive behavioral context the annotations cannot: the default `include_inactive: true` survivorship policy, the one-ticker-two-CIK-rows quirk with `is_active` vs the unreliable `status` flag, ticker recycling hazards, the SIC-derived (non-licensed GICS) sector caveat, and the underlying data source. That is exactly the beyond-annotations disclosure this dimension rewards.

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?

Well front-loaded and sectioned with bold leads (routing rule, row-duplication warning, data details, identifier guidance), and nearly every sentence carries actionable information. It is long for a search tool, and the CIK-recycling narrative could be tightened, keeping it just short of a 5.

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?

With 7 parameters, a 0-required schema, annotations, and an output schema (so return values needn't be described), the description covers everything an agent needs: routing vs siblings, filter semantics, defaults, and identifier-stability guidance for multi-step workflows.

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

Parameters5/5

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

Schema coverage is 100% (baseline 3), but the description still adds real meaning: a purely-numeric `query` resolves by CIK, `is_sp500` is itself sufficient as a lone filter, `limit` appears in a worked example, and the `is_active` vs `include_inactive` precedence ('is_active wins') is clarified. This goes materially beyond the schema text.

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 ('Search for US public companies') and enumerates the keyable identifiers (name, ticker, CIK, SIC) plus the exact return fields. It also explicitly differentiates itself from a sibling, `get_pit_universe`, so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use ('resolve a company name to ticker/CIK before calling get_company_fundamentals...'), when-not-to-use ('use get_pit_universe ONLY when the user explicitly needs a survivorship-free historical universe'), and a concrete call recipe with example payloads. Alternatives are named and the disambiguating condition ('current'/'today'/no date) is spelled out.

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

Resources