Skip to main content
Glama

Secedgar Compare Companies

secedgar_compare_companies
Read-onlyIdempotent

Compare 2-10 named companies across 1-8 XBRL concepts, aligned on fiscal years (annual) or calendar quarters (quarterly). This is the middle shape between secedgar_get_financials (one company, one concept, full history) and secedgar_fetch_frames (one concept, one period, every reporting company) — reach for it when the question names the companies. One companyfacts read per company, resolved through the same frame dedup and tag priority as secedgar_get_financials so the numbers agree. Balance-sheet and entity-info concepts are filed as point-in-time values: an annual matrix takes each company’s fiscal-year-end snapshot and places it in the period of the fiscal year it closes, beside that year’s income-statement lines (interim and cover-date snapshots stay out), and a quarterly matrix aligns each snapshot on the calendar quarter it falls in. The inline matrix covers the most recent periods up to periods, trimmed further when companies x concepts x periods is too large to return in one response; the full aligned series is materialized as df_ for growth rates and spreads — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. A company that fails to resolve is reported in failed_companies and the comparison proceeds with the rest, and a company that does not report a concept is reported in gaps with the tags that were tried — never interpolated or zero-filled. A company named twice (a ticker and its CIK) is read once, under the first input. Where the schema accepts a longer list, companies past the first 10 and concepts past the first 8 distinct are not read; they come back in deferred_companies and deferred_concepts to re-call with. A company that reports a concept only for periods older than the inline window is named in caveats with its newest period. A concept that is neither a friendly name nor an XBRL tag is reported once in unknown_concepts with the closest supported names, and fails the call only when every concept is one. Off-calendar filers and unit mismatches are surfaced in caveats rather than silently mixed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "companies": "<companies>",
      "concepts": "<concepts>"
    },
    "name": "secedgar_compare_companies"
  }
}

Input Schema

NameRequiredDescriptionDefault
periodsNoUpper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query. Capped at 12: a larger value, up to 1000, returns what 12 returns.
conceptsYesConcepts to compare — friendly names like "revenue" or "net_income", in any spelling secedgar_get_financials accepts (discover them with secedgar_search_concepts), or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts.
taxonomyNoXBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy.us-gaap
companiesYesCompanies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs. The first 10 inputs are read; a longer list, up to 100, returns the rest unread in deferred_companies.
period_typeNoAlign on fiscal years, each under the calendar-year key SEC frames it as (annual), or on calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats.annual

Output Schema

NameRequiredDescriptionDefault
capNoThe periods cap applied.
gapsNoCompany-concept pairs with no value in any period, never zero-filled; a pair with values only before the inline window is in caveats instead.
cellsNoInline matrix values, covering the periods listed in periods[].
errorNoPresent when the call failed. Absent on success.
shownNoNumber of periods shown inline.
noticeNoGuidance on deferred inputs, periods the inline matrix dropped, or the staged dataframe.
caveatsNoComparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an annual instant with no fiscal-year-end value; differing period ends or units; values only before the inline window; merged inputs; how a ticker was read.
datasetNoDataframe of the full aligned series, every period, with cells[] columns. Absent when canvas is unavailable.
periodsNoInline period keys, newest first; fewer than requested when the cell count shrank the window (see notice).
conceptsNoConcepts covered, in input order; spellings of one concept appear once, under the first.
taxonomyNoTaxonomy the concepts were resolved under, echoed from input.
companiesNoCompanies included in the comparison.
truncatedNoTrue when the aligned series has more periods than the inline matrix shows.
period_typeNoPeriod alignment used, echoed from input.
failed_companiesNoCompanies excluded from the matrix; the rest still compare.
unknown_conceptsNoConcepts neither a supported name nor an XBRL tag, reported once rather than as per-company gaps; secedgar_search_concepts lists the supported names.
deferred_conceptsNoInputs naming a concept past the first 8 distinct, unread, as supplied.
deferred_companiesNoCompany inputs past the first 10, unread, as supplied.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / concepts / description
      Previous value: -"Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts."New value: +"Concepts to compare — friendly names like \"revenue\" or \"net_income\", in any spelling secedgar_get_financials accepts (discover them with secedgar_search_concepts), or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts."
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an instant with no fiscal-year-end value (annual); differing period ends or units; values only before the inline window; merged inputs."New value: +"Comparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an annual instant with no fiscal-year-end value; differing period ends or units; values only before the inline window; merged inputs; how a ticker was read."
    • changedOutput schema / properties / dataset / properties / name / description
      Previous value: -"Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."New value: +"Dataframe handle for secedgar_dataframe_describe, then secedgar_dataframe_query."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the company inputs read resolved to a CIK; inputs past the caps were not read and are named in deferred_companies and deferred_concepts. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type; any company or concept inputs past the caps are named, unread, in deferred_companies and deferred_concepts. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the company inputs read resolved to a CIK; inputs past the caps were not read and are named in deferred_companies and deferred_concepts. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type; any company or concept inputs past the caps are named, unread, in deferred_companies and deferred_concepts. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. `sec_unavailable`: SEC EDGAR answered HTTP 500, 502, 503, or 504 on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out). Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_companies_resolved",
      -  "no_comparable_data",
      -  "unknown_concept",
      -  "rate_limited",
      -  "sec_unreachable"
      -]New value: +[
      +  "no_companies_resolved",
      +  "no_comparable_data",
      +  "unknown_concept",
      +  "rate_limited",
      +  "sec_unreachable",
      +  "sec_unavailable"
      +]
  2. Changed1 schema field changed
    • changedOutput schema / properties / failed_companies / items / properties / reason / description
      Previous value: -"not_found: no CIK matched. ambiguous: several matched; the message lists them. no_company_facts: resolved, but the filer reports no XBRL. Match on this, not the message."New value: +"not_found: no CIK matched. ambiguous: several matched; the message lists up to 10. no_company_facts: resolved, but the filer reports no XBRL. Match on this, not the message."
  3. Changed16 schema fields changed
    • changedInput schema / properties / companies / description
      Previous value: -"Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs."New value: +"Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs. The first 10 inputs are read; a longer list, up to 100, returns the rest unread in deferred_companies."
    • changedInput schema / properties / companies / maxItems
      Previous value: -10New value: +100
    • changedInput schema / properties / concepts / description
      Previous value: -"Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags."New value: +"Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts."
    • changedInput schema / properties / concepts / maxItems
      Previous value: -8New value: +100
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings (company ones prefixed with the name), else empty: missing quarters; a concept 2+ years behind the company's other lines; an instant with no fiscal-year-end value (annual); differing period ends or units; values only before the inline window; merged inputs."New value: +"Comparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an instant with no fiscal-year-end value (annual); differing period ends or units; values only before the inline window; merged inputs."
    • changedOutput schema / properties / cells / items / properties / period_end / description
      Previous value: -"Period end date (YYYY-MM-DD). Differs across off-calendar filers within one aligned period."New value: +"Period end date (YYYY-MM-DD); differs across off-calendar filers in one aligned period."
    • changedOutput schema / properties / concepts / description
      Previous value: -"Concepts covered, in input order; inputs naming the same concept appear once, under the first spelling."New value: +"Concepts covered, in input order; spellings of one concept appear once, under the first."
    • addedOutput schema / properties / deferred_companies
      Added value: +{
      +  "description": "Company inputs past the first 10, unread, as supplied.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / deferred_concepts
      Added value: +{
      +  "description": "Inputs naming a concept past the first 8 distinct, unread, as supplied.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the company inputs read resolved to a CIK; inputs past the caps were not read and are named in deferred_companies and deferred_concepts. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type; any company or concept inputs past the caps are named, unread, in deferred_companies and deferred_concepts. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / gaps / description
      Previous value: -"Company-concept pairs with no value in any period (never zero-filled). A pair with values only before the inline window appears in caveats instead."New value: +"Company-concept pairs with no value in any period, never zero-filled; a pair with values only before the inline window is in caveats instead."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the inline matrix dropped periods, or the full series is staged as a dataframe."New value: +"Guidance on deferred inputs, periods the inline matrix dropped, or the staged dataframe."
    • changedOutput schema / properties / periods / description
      Previous value: -"Period keys in the inline matrix, newest first; shorter than requested when the cell count shrank it (see notice)."New value: +"Inline period keys, newest first; fewer than requested when the cell count shrank the window (see notice)."
    • changedOutput schema / properties / unknown_concepts / description
      Previous value: -"Concepts that are neither a supported name nor an XBRL tag, reported once instead of as per-company gaps; secedgar_search_concepts lists supported names. Empty when all resolved."New value: +"Concepts neither a supported name nor an XBRL tag, reported once rather than as per-company gaps; secedgar_search_concepts lists the supported names."
    • changedOutput schema / properties / unknown_concepts / items / description
      Previous value: -"One requested concept that was not queried for any company."New value: +"One concept not queried for any company."
    • changedOutput schema / properties / unknown_concepts / items / properties / derivation / description
      Previous value: -"How to build it from supported concepts, when it is a standard combination (e.g., \"operating_cash_flow − capex\")."New value: +"Formula over supported concepts, when it is a standard combination (e.g., \"operating_cash_flow − capex\")."
  4. Changed2 schema fields changed
    • changedInput schema / properties / periods / description
      Previous value: -"Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query."New value: +"Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query. Capped at 12: a larger value, up to 1000, returns what 12 returns."
    • changedInput schema / properties / periods / maximum
      Previous value: -12New value: +1000
  5. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
  6. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: The last of three attempts to reach SEC EDGAR got no HTTP response — the connection failed, or no response headers arrived within 15 seconds. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_companies_resolved",
      -  "no_comparable_data",
      -  "unknown_concept",
      -  "rate_limited"
      -]New value: +[
      +  "no_companies_resolved",
      +  "no_comparable_data",
      +  "unknown_concept",
      +  "rate_limited",
      +  "sec_unreachable"
      +]
  7. Changed2 schema fields changed
    • changedInput schema / properties / period_type / description
      Previous value: -"Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats."New value: +"Align on fiscal years, each under the calendar-year key SEC frames it as (annual), or on calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats."
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings (company-specific ones prefixed with the name), else empty: missing quarters; a concept stopping 2+ years behind the company's other reporting; period ends differing within a period; units differing across companies; values only before the inline window; merged inputs."New value: +"Comparability warnings (company ones prefixed with the name), else empty: missing quarters; a concept 2+ years behind the company's other lines; an instant with no fiscal-year-end value (annual); differing period ends or units; values only before the inline window; merged inputs."
  8. Changed17 schema fields changed
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, concepts whose unit differs across companies, and — one line per concept — the companies that report a concept but have no value inside the inline periods, each with its newest period (its values are in the dataframe), and the concept inputs merged because they name the same concept. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."New value: +"Comparability warnings (company-specific ones prefixed with the name), else empty: missing quarters; a concept stopping 2+ years behind the company's other reporting; period ends differing within a period; units differing across companies; values only before the inline window; merged inputs."
    • changedOutput schema / properties / cells / items / properties / frame / description
      Previous value: -"Underlying XBRL frame, which differs from period for point-in-time concepts (e.g. frame CY2024Q3I under period CY2024)."New value: +"Underlying XBRL frame; differs from period for point-in-time concepts (CY2024Q3I under CY2024)."
    • changedOutput schema / properties / cells / items / properties / tag / description
      Previous value: -"XBRL tag this value was reported under — one concept can walk several tags, so it can differ between periods of the same company."New value: +"XBRL tag this value was reported under; can differ between periods of one company."
    • changedOutput schema / properties / companies / items / description
      Previous value: -"One company that resolved and contributed to the matrix."New value: +"One company that contributed to the matrix."
    • changedOutput schema / properties / concepts / description
      Previous value: -"Concepts covered, in the order supplied. Inputs that name the same concept (revenue and Revenue, or one raw tag spelled twice) appear once, under the first spelling."New value: +"Concepts covered, in input order; inputs naming the same concept appear once, under the first spelling."
    • changedOutput schema / properties / concepts / items / properties / units / description
      Previous value: -"Distinct units this concept resolved to across the companies. More than one means the values are not directly comparable — see caveats."New value: +"Units this concept resolved to across companies; more than one means values are not directly comparable."
    • changedOutput schema / properties / dataset / description
      Previous value: -"Canvas dataframe holding the full aligned series across every period, not just the inline window. Columns match cells[]. Absent when canvas is unavailable."New value: +"Dataframe of the full aligned series, every period, with cells[] columns. Absent when canvas is unavailable."
    • changedOutput schema / properties / dataset / properties / name / description
      Previous value: -"Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query."New value: +"Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
    • changedOutput schema / properties / failed_companies / description
      Previous value: -"Companies excluded from the matrix. The comparison proceeds with the rest rather than failing the whole call."New value: +"Companies excluded from the matrix; the rest still compare."
    • changedOutput schema / properties / failed_companies / items / description
      Previous value: -"One company that could not be included, with a machine-readable reason."New value: +"One company that could not be included."
    • changedOutput schema / properties / failed_companies / items / properties / reason / description
      Previous value: -"Machine-readable failure. not_found: the input matched no CIK. ambiguous: it matched several, and the message lists them. no_company_facts: it resolved but the filer reports no XBRL. Match on this rather than the message."New value: +"not_found: no CIK matched. ambiguous: several matched; the message lists them. no_company_facts: resolved, but the filer reports no XBRL. Match on this, not the message."
    • changedOutput schema / properties / gaps / description
      Previous value: -"Company-concept pairs with no value in any period. Deliberately explicit — a missing value is never interpolated or zero-filled. A pair with values only in periods older than the inline window is not a gap; caveats names it."New value: +"Company-concept pairs with no value in any period (never zero-filled). A pair with values only before the inline window appears in caveats instead."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the inline matrix dropped periods, or when the full aligned series is staged as a dataframe."New value: +"Guidance when the inline matrix dropped periods, or the full series is staged as a dataframe."
    • changedOutput schema / properties / periods / description
      Previous value: -"Calendar period keys covered by the inline matrix, newest first. Shorter than the requested periods when the cell count forced the window to shrink — the enrichment trailer reports the drop."New value: +"Period keys in the inline matrix, newest first; shorter than requested when the cell count shrank it (see notice)."
    • changedOutput schema / properties / unknown_concepts / description
      Previous value: -"Requested concepts that are neither a supported friendly name nor an XBRL tag (UpperCamelCase, e.g. NetIncomeLoss), reported once each rather than as a gap per company — secedgar_search_concepts lists every supported name. Empty when every concept resolved."New value: +"Concepts that are neither a supported name nor an XBRL tag, reported once instead of as per-company gaps; secedgar_search_concepts lists supported names. Empty when all resolved."
    • changedOutput schema / properties / unknown_concepts / items / properties / concept / description
      Previous value: -"Concept as supplied (trimmed) — neither a supported friendly name nor an XBRL tag."New value: +"Concept as supplied, trimmed."
    • changedOutput schema / properties / unknown_concepts / items / properties / derivation / description
      Previous value: -"How to build it from supported concepts when it is a standard combination, e.g. \"operating_cash_flow − capex\"."New value: +"How to build it from supported concepts, when it is a standard combination (e.g., \"operating_cash_flow − capex\")."
  9. Changed8 schema fields changed
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "period_type",
      -      "taxonomy",
      -      "periods",
      -      "companies",
      -      "failed_companies",
      -      "concepts",
      -      "cells",
      -      "gaps",
      -      "caveats"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "period_type",
      +      "taxonomy",
      +      "periods",
      +      "companies",
      +      "failed_companies",
      +      "concepts",
      +      "cells",
      +      "gaps",
      +      "unknown_concepts",
      +      "caveats"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, and concepts whose unit differs across companies. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."New value: +"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, concepts whose unit differs across companies, and — one line per concept — the companies that report a concept but have no value inside the inline periods, each with its newest period (its values are in the dataframe), and the concept inputs merged because they name the same concept. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."
    • changedOutput schema / properties / cells / items / properties / tag / description
      Previous value: -"XBRL tag that produced the value."New value: +"XBRL tag this value was reported under — one concept can walk several tags, so it can differ between periods of the same company."
    • changedOutput schema / properties / concepts / description
      Previous value: -"Concepts covered, in the order supplied."New value: +"Concepts covered, in the order supplied. Inputs that name the same concept (revenue and Revenue, or one raw tag spelled twice) appear once, under the first spelling."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_companies_resolved",
      -  "no_comparable_data",
      -  "rate_limited"
      -]New value: +[
      +  "no_companies_resolved",
      +  "no_comparable_data",
      +  "unknown_concept",
      +  "rate_limited"
      +]
    • changedOutput schema / properties / gaps / description
      Previous value: -"Company-concept pairs with no data. Deliberately explicit — a missing value is never interpolated or zero-filled."New value: +"Company-concept pairs with no value in any period. Deliberately explicit — a missing value is never interpolated or zero-filled. A pair with values only in periods older than the inline window is not a gap; caveats names it."
    • addedOutput schema / properties / unknown_concepts
      Added value: +{
      +  "description": "Requested concepts that are neither a supported friendly name nor an XBRL tag (UpperCamelCase, e.g. NetIncomeLoss), reported once each rather than as a gap per company — secedgar_search_concepts lists every supported name. Empty when every concept resolved.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One requested concept that was not queried for any company.",
      +    "properties": {
      +      "concept": {
      +        "description": "Concept as supplied (trimmed) — neither a supported friendly name nor an XBRL tag.",
      +        "type": "string"
      +      },
      +      "derivation": {
      +        "description": "How to build it from supported concepts when it is a standard combination, e.g. \"operating_cash_flow − capex\".",
      +        "type": "string"
      +      },
      +      "suggestions": {
      +        "description": "Up to three closest supported friendly names. Empty when a derivation applies or no name is close.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "concept",
      +      "suggestions"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  10. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "no_companies_resolved",
      -  "no_comparable_data"
      -]New value: +[
      +  "no_companies_resolved",
      +  "no_comparable_data",
      +  "rate_limited"
      +]
  11. Changed2 schema fields changed
    • changedOutput schema / properties / dataset / properties / name / description
      Previous value: -"Dataframe handle (df_XXXXX_XXXXX) — pass to secedgar_dataframe_query."New value: +"Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Guidance when the inline matrix dropped periods, or when the full aligned series is staged as a dataframe.",
      +  "type": "string"
      +}
  12. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "period_type",
      +      "taxonomy",
      +      "periods",
      +      "companies",
      +      "failed_companies",
      +      "concepts",
      +      "cells",
      +      "gaps",
      +      "caveats"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "no_companies_resolved",
      +            "no_comparable_data"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "period_type",
      -  "taxonomy",
      -  "periods",
      -  "companies",
      -  "failed_companies",
      -  "concepts",
      -  "cells",
      -  "gaps",
      -  "caveats"
      -]
  13. Changed1 schema field changed
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept that resolved to an XBRL tag SEC has retired (so that company's values may stop years short of the others'), period ends that differ inside one aligned period, and concepts whose unit differs across companies. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."New value: +"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, and concepts whose unit differs across companies. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."
  14. Changed2 schema fields changed
    • changedInput schema / properties / period_type / description
      Previous value: -"Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing one calendar quarter per year — see caveats."New value: +"Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats."
    • changedOutput schema / properties / caveats / description
      Previous value: -"Comparability warnings: a filer missing a calendar quarter from the frame-tagged series, period ends that differ inside one aligned period, and concepts whose unit differs across companies. Empty when nothing needs flagging."New value: +"Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept that resolved to an XBRL tag SEC has retired (so that company's values may stop years short of the others'), period ends that differ inside one aligned period, and concepts whose unit differs across companies. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging."
  15. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare read-only, idempotent, and open-world, so the safety profile is covered; the description still adds substantial behavior: per-company failure is isolated into failed_companies, unreported concepts go to gaps with the tags attempted, and nothing is interpolated or zero-filled. Deferral of inputs past 10 companies / 8 concepts, deduplication of a ticker-plus-CIK pair under the first input, and surfacing of off-calendar filers and unit mismatches in caveats are all disclosed.

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 correctly — what it does and where it sits among siblings comes first, edge-case behavior trails. It is dense and long, and a few clauses (periods capping, deferral limits) restate the parameter descriptions nearly verbatim, so it loses a point for mild redundancy rather than for waste.

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 five-parameter tool with an output schema, it covers the deciding concerns an agent would otherwise have to probe: failure isolation, missing-data reporting, inline-vs-dataframe window split, and concept-name resolution errors. Nothing material to calling it correctly is left implicit.

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 description coverage is 100%, so the baseline is 3; the description earns above that by explaining alignment semantics that the schema cannot: fiscal-year-end balance-sheet snapshots are placed in the year they close, interim and cover-date snapshots excluded, and quarterly matrices align on calendar quarter. It also clarifies dedup behavior of the companies list, which the schema does not state.

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, and hard scope bounds ("Compare 2-10 named companies across 1-8 XBRL concepts, aligned on fiscal years (annual) or calendar quarters"). It then explicitly locates itself as "the middle shape between secedgar_get_financials ... and secedgar_fetch_frames," so an agent can pick it out of the sibling set without opening any 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 an explicit selection rule ("reach for it when the question names the companies") plus the two alternatives it sits between, each described by their shape (one company/one concept/full history vs. one concept/one period/every company). It also states follow-on routing to secedgar_dataframe_describe and secedgar_dataframe_query for the materialized series, and a taxonomy restriction for IFRS mixed lists.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.