Recipe: Compare companies

The task

You want revenue, net income, cash, and debt for 2-5 public companies side by side, without resolving and querying each one yourself.

Tool used: compare_entities. One call.

Copy-paste prompt

Compare <company1>, <company2>, and <company3> using Pipeworx: revenue, net income, cash, and
long-term debt, side by side. Note if their fiscal years end on different dates so I don't
compare mismatched periods. Cite pipeworx:// resource URIs.

What a good answer looks like

compare_entities({ type: "company", values: ["AAPL", "MSFT", "GOOGL"] })

returns (live call, 2026-08-06 — trimmed to one entity):

{
  "type": "company",
  "entities": [
    {
      "query": "AAPL",
      "resolved": true,
      "facts": {
        "Revenues": {
          "value": 364357000000, "unit": "USD", "period": "2026-06-27",
          "form": "2026-07-31", "concept_used": "RevenueFromContractWithCustomerExcludingAssessedTax"
        },
        "NetIncomeLoss": { "value": 101464000000, "period": "2026-06-27", "form": "2026-07-31" },
        "CashAndCashEquivalentsAtCarryingValue": { "value": 39544000000, "period": "2026-06-27" },
        "LongTermDebtNoncurrent": { "value": 71340000000, "period": "2026-06-27" }
      },
      "cik": "0000320193", "ticker": "AAPL", "company_name": "Apple Inc.",
      "resources": {
        "edgar_filings": "pipeworx://edgar/company/0000320193/filings",
        "edgar_facts": "pipeworx://edgar/company/0000320193/facts"
      }
    }
  ],
  "deltas": { "Revenues": [ { "entity": "AAPL", "value": 364357000000, "period": "2026-06-27" }, "..." ] },
  "notes": "Values are the latest reported for each concept. Periods may differ across entities — compare carefully when fiscal year-ends differ."
}

A trustworthy answer has:

  • concept_used on every fact — the actual XBRL tag the tool resolved to (companies that moved off a generic tag under ASC 606 are handled automatically; see the company financials recipe for why that matters).
  • an explicit resolved: false with a notes explanation when an input doesn’t resolve — passing a bare company name instead of a ticker/CIK (e.g. "Costco") returns resolved: false, facts: {}, notes: "compare_entities requires ticker or CIK (got name \"Costco\"). Resolve names with resolve_entity first." rather than guessing or erroring the whole call. Check resolved per entity before reading its facts.
  • a top-level notes flagging that periods may differ across entities.
  • resources with re-fetchable pipeworx:// citation URIs.

A plausible-sounding failure looks like a normal field with the wrong content — not a missing one. This is real, live, and currently shipping: every fact in the block above carries a form field, and it looks exactly like the form field in every other Pipeworx financials response ("10-K", "10-Q"). It isn’t. Read the value again: "form": "2026-07-31" — that’s a date, not a form type. Apple’s actual most recent form is a 10-Q; nothing here says so. Checked against the gateway source (workers/gateway/src/index.ts, compareCompanyOne): the code builds this field from latest.filed — the filing date — and just calls the output key form. The upstream data it draws from (edgar_company_concept’s annual_values) never carried a form-type field to begin with, so there was nothing correct to put there. Do not report compare_entities’ form field as “10-K” or “10-Q” in any output — it is the filed date, mislabeled. Filed as fleet task #160 for a fix (rename the field or populate it correctly); until that lands, get the actual form type from edgar_company_filings if you need it.

Step-by-step tool calls

Fast path

compare_entities({ type: "company", values: ["AAPL", "MSFT", "GOOGL"] })

One call, parallel, three sources of truth per company.

Manual path (full control)

If you need different concepts, time windows, or non-US companies:

const apple = await resolve_entity({ type: "company", value: "AAPL" })
// apple.ids.cik = "0000320193"

edgar_company_concept({ cik: apple.ids.cik, concept: "OperatingIncomeLoss" })
edgar_company_concept({ cik: apple.ids.cik, concept: "ResearchAndDevelopmentExpense" })
// repeat per company, in parallel

Unlike compare_entities, edgar_company_concept’s own response carries a correctly-populated form field ("10-K"/"10-Q") alongside filed — use the manual path if you need to cite the actual form type per figure today.

Or use fintech_company_deep_dive per company (compound — adds 8-K events, insider transactions, and CFPB complaints on top of the financials):

await Promise.all([
  fintech_company_deep_dive({ ticker: "AAPL" }),
  fintech_company_deep_dive({ ticker: "MSFT" }),
  fintech_company_deep_dive({ ticker: "GOOGL" }),
])

Citation pattern

AAPL (EDGAR) latest-quarter revenue $364.4B, net income $101.5B (period ending 2026-06-27). MSFT (EDGAR) latest-quarter revenue $331.8B (period ending 2026-06-30). Periods are close but not identical — Apple’s fiscal year ends in September, Microsoft’s in June.

Always disclose the period when comparing — it’s the most common analyst error in agent output.

Caveats

  • The form field is mislabeled — see above. It holds a filing date, not a form type (fleet task #160).
  • Period mismatch. Apple’s fiscal year ends in September, Microsoft’s in June. The latest reported figure for each may be close in calendar time but cover different fiscal quarters — read each entity’s period field rather than assuming alignment.
  • Tickers vs. CIKs. Both work as input. CIKs are stable across name changes; tickers change when companies rebrand.
  • Bare company names don’t resolve. compare_entities requires a ticker or CIK per entity — pass a name and you get resolved: false with an explanatory note, not a best-effort guess. Run resolve_entity first if you only have names.

Last reviewed August 6, 2026