Skip to main content
Glama

Company Facts

company_facts
Read-onlyIdempotent

TYPED, DETERMINISTIC financial facts for a US public company for an EXPLICITLY NAMED reporting period, "Apple revenue for fiscal 2023", "Walmart net income FY2026 Q3", "Microsoft cash at the end of fiscal 2024". PREFER OVER entity_profile / get_company_financials whenever the period matters: those answer "the most recent figures" and will happily hand back FY2025 when you asked about FY2019, and neither separates a discrete quarter from a year-to-date figure. This one refuses instead, it NEVER substitutes the latest period for the period requested, NEVER returns 0 for missing data, NEVER lets a 9-month YTD number answer a quarterly question, and NEVER converts a currency. Every answer carries the exact us-gaap concept it came from, what that concept MEASURES (NetIncomeLoss excludes non-controlling interests, ProfitLoss includes them, not synonyms), the accession number and a link to the filing on sec.gov, the restatement trail of any superseded figures, and a contract + derivation version to pin against. Fiscal periods are the FILER'S OWN, anchored on their fiscal-year end, so Walmart's year ending 2026-01-31 is FY2026 and Apple's ending 2025-09-27 is FY2025. Attributes: revenue, net_income, cash, gross_profit, operating_income, eps_diluted, capex, operating_cash_flow, long_term_debt, shares_outstanding (the dei COVER-PAGE share count, so its period end is the cover date, after the quarter closed, that is the most current count the filing carries). Units are not all USD: shares_outstanding is in shares with currency null, eps_diluted in USD/shares. A discrete quarter the filer never filed, every Q4, and Q2/Q3 of cash-flow lines, which are filed year-to-date, is DERIVED as YTD(q) minus YTD(q-1) and comes back with reported: false, the subtraction named in derivation (fy_minus_9m / ytd_9m_minus_6m / ytd_6m_minus_3m) and both legs with their filings in derived_from; test reported if you will only accept a figure lifted from a filing. Per-share and balance-sheet figures are NEVER derived. Every non-answer is a named status, unavailable (the filer did not report it for that period; the periods that DO exist are listed, without values), unsupported (outside what v1 covers, a non-us-gaap filer, an unknown attribute, a non-USD unit), ambiguous (the company name matched two filers equally well; both are named), conflicting (two filings the same day disagree; both are returned and neither is picked), partial (a value with no accession behind it). Source: SEC EDGAR, XBRL financial facts, one publisher read once, see corroboration. Same response is served at POST https://gateway.pipeworx.io/v1/facts for non-MCP callers.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "period": {
        "type": "annual",
        "fiscal_year": 2023
      },
      "company": "AAPL",
      "attribute": "revenue"
    },
    "name": "company_facts"
  }
}

Input Schema

NameRequiredDescriptionDefault
as_ofNoPast ISO timestamp with timezone. Replay the latest answer actually recorded by that instant; no invented history or live fallback.
basisNoOnly "consolidated" in v1. Segment and product-level figures are XBRL-dimensioned and are not reachable through this contract at any concept.
periodYesThe reporting period, stated explicitly. There is no default and no "latest", that is the point of this tool.
companyYesTicker ("AAPL"), 10-digit CIK ("0000320193"), or company name. A name that matches two filers equally well returns status "ambiguous" with both named rather than guessing, pass a ticker or CIK to be certain.
max_ageNoMaximum age in seconds of the upstream publication, not our fetch. Older or undated facts are withheld.
attributeYesWhich figure. "revenue" = total consolidated revenue; "net_income" = net income (loss); "cash" = cash and cash equivalents at the period end; "gross_profit"; "operating_income"; "eps_diluted" (diluted EPS, unit USD/shares, never derived or summed); "capex" (cash paid for PP&E); "operating_cash_flow" (net cash from operating activities); "long_term_debt" (the noncurrent balance-sheet line where the filer tags it, else total long-term debt, `fact.measure` says which); "shares_outstanding" (dei cover-page common shares, unit "shares", as of the COVER DATE rather than the period end).
freshnessNocached (default) permits an eligible stored answer; fresh requires an upstream refresh and never silently falls back to stale data.
restatementNoDefault "as_amended", the latest filed figure for the period, with everything it superseded listed. "as_originally_reported" takes the first filing instead.
exclude_publishersNoPublisher ids forbidden for fact retrieval: sec, fmp, alphavantage. Case and surrounding whitespace are normalized; unknown ids are refused. Excluding sec currently leaves no eligible fact source and returns unavailable/sources_excluded with the selection reasons. Identity and fiscal-calendar lookups may still use SEC; no excluded financial concept is fetched.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / attribute / description
      Previous value: -"Which figure. \"revenue\" = total consolidated revenue; \"net_income\" = net income (loss); \"cash\" = cash and cash equivalents at the period end; \"gross_profit\"; \"operating_income\"; \"eps_diluted\" (diluted EPS, unit USD/shares, never derived or summed); \"capex\" (cash paid for PP&E); \"operating_cash_flow\" (net cash from operating activities); \"long_term_debt\" (the noncurrent balance-sheet line where the filer tags it, else total long-term debt — `fact.measure` says which); \"shares_outstanding\" (dei cover-page common shares, unit \"shares\", as of the COVER DATE rather than the period end)."New value: +"Which figure. \"revenue\" = total consolidated revenue; \"net_income\" = net income (loss); \"cash\" = cash and cash equivalents at the period end; \"gross_profit\"; \"operating_income\"; \"eps_diluted\" (diluted EPS, unit USD/shares, never derived or summed); \"capex\" (cash paid for PP&E); \"operating_cash_flow\" (net cash from operating activities); \"long_term_debt\" (the noncurrent balance-sheet line where the filer tags it, else total long-term debt, `fact.measure` says which); \"shares_outstanding\" (dei cover-page common shares, unit \"shares\", as of the COVER DATE rather than the period end)."
    • changedInput schema / properties / company / description
      Previous value: -"Ticker (\"AAPL\"), 10-digit CIK (\"0000320193\"), or company name. A name that matches two filers equally well returns status \"ambiguous\" with both named rather than guessing — pass a ticker or CIK to be certain."New value: +"Ticker (\"AAPL\"), 10-digit CIK (\"0000320193\"), or company name. A name that matches two filers equally well returns status \"ambiguous\" with both named rather than guessing, pass a ticker or CIK to be certain."
    • changedInput schema / properties / period / description
      Previous value: -"The reporting period, stated explicitly. There is no default and no \"latest\" — that is the point of this tool."New value: +"The reporting period, stated explicitly. There is no default and no \"latest\", that is the point of this tool."
    • changedInput schema / properties / period / properties / fiscal_year / description
      Previous value: -"The FILER'S fiscal year — the year the period ends in by their own calendar. Walmart's year ending 2026-01-31 is 2026."New value: +"The FILER'S fiscal year, the year the period ends in by their own calendar. Walmart's year ending 2026-01-31 is 2026."
    • changedInput schema / properties / restatement / description
      Previous value: -"Default \"as_amended\" — the latest filed figure for the period, with everything it superseded listed. \"as_originally_reported\" takes the first filing instead."New value: +"Default \"as_amended\", the latest filed figure for the period, with everything it superseded listed. \"as_originally_reported\" takes the first filing instead."
  2. Changed3 schema fields changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "attribute": "revenue",
      -    "company": "AAPL",
      -    "period": {
      -      "fiscal_year": 2023,
      -      "type": "annual"
      -    }
      -  }
      -]New value: +[
      +  {
      +    "attribute": "revenue",
      +    "company": "AAPL",
      +    "period": {
      +      "fiscal_year": 2023,
      +      "type": "annual"
      +    }
      +  },
      +  {
      +    "attribute": "shares_outstanding",
      +    "company": "TSLA",
      +    "period": {
      +      "fiscal_quarter": 2,
      +      "fiscal_year": 2026,
      +      "type": "quarterly"
      +    }
      +  },
      +  {
      +    "attribute": "capex",
      +    "company": "TSLA",
      +    "period": {
      +      "fiscal_quarter": 2,
      +      "fiscal_year": 2026,
      +      "type": "quarterly"
      +    }
      +  },
      +  {
      +    "attribute": "net_income",
      +    "company": "TSLA",
      +    "period": {
      +      "fiscal_quarter": 4,
      +      "fiscal_year": 2025,
      +      "type": "quarterly"
      +    }
      +  }
      +]
    • changedInput schema / properties / attribute / description
      Previous value: -"Which figure. \"revenue\" = total consolidated revenue; \"net_income\" = net income (loss); \"cash\" = cash and cash equivalents at the period end."New value: +"Which figure. \"revenue\" = total consolidated revenue; \"net_income\" = net income (loss); \"cash\" = cash and cash equivalents at the period end; \"gross_profit\"; \"operating_income\"; \"eps_diluted\" (diluted EPS, unit USD/shares, never derived or summed); \"capex\" (cash paid for PP&E); \"operating_cash_flow\" (net cash from operating activities); \"long_term_debt\" (the noncurrent balance-sheet line where the filer tags it, else total long-term debt — `fact.measure` says which); \"shares_outstanding\" (dei cover-page common shares, unit \"shares\", as of the COVER DATE rather than the period end)."
    • changedInput schema / properties / attribute / enum
      Previous value: -[
      -  "revenue",
      -  "net_income",
      -  "cash"
      -]New value: +[
      +  "revenue",
      +  "net_income",
      +  "cash",
      +  "gross_profit",
      +  "operating_income",
      +  "eps_diluted",
      +  "capex",
      +  "operating_cash_flow",
      +  "long_term_debt",
      +  "shares_outstanding"
      +]
  3. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavior: no substitution of latest period, never returning 0 for missing data, never converting currency, per-share and balance-sheet figures never derived, the derived-quarter rule with named subtraction keys, and the full status vocabulary (unavailable/unsupported/ambiguous/conflicting/partial). The only shortfall is that the return payload's shape is described prosaically (concept, measure, accession, link, restatement trail, version) without examples of the actual object. No annotation contradiction.

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?

The purpose, the sibling routing, and the guarantee set are front-loaded, and nearly every sentence carries load-bearing information an agent cannot get from structured fields. It loses a point for a dense single block with heavy capitalization and for re-listing the ten attributes and their meanings that the schema enum already documents, which is redundancy against structured data.

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 9-parameter tool with a nested period object and no output schema, the description covers what an agent needs to interpret results: derivation flags and legs, the named non-answer statuses, provenance and restatement trail, and units. The named alternatives plus status semantics close the loop on how to react when the call does not return a figure.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics beyond the schema: fiscal periods are the filer's own anchored on fiscal-year end (Walmart's year ending 2026-01-31 is FY2026), shares_outstanding is measured at the cover date not period end, and units differ per attribute (shares with null currency, USD/shares for EPS). The attribute enumeration largely restates the schema enum descriptions, which caps this at 4 rather than 5.

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?

The opening sentence gives a specific verb + resource + scope: typed, deterministic financial facts for a US public company for an explicitly named period, with three concrete example queries. It also explicitly distinguishes itself from entity_profile and get_company_financials by naming the exact failure mode those have (returning FY2025 when asked about FY2019, and not separating discrete quarters from YTD). An agent can route correctly without opening the 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?

It states when to prefer this tool ("whenever the period matters") and names the alternatives to use otherwise, plus the operational rule to test `reported: true` if only filing-sourced figures are acceptable. It also lists when-not conditions implicitly through the status taxonomy (unsupported for non-us-gaap filers, non-USD units, segments).

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.