Compare Companies / Peers
compare_companiesCompare a company against peers across ~70 curated fundamental metrics (TTM by default; period_type FY or Q for each company's latest fiscal year or quarter), with percentile rankings and relative strengths/weaknesses.
Returns a side-by-side table covering valuation (P/E, P/B, EV/EBITDA, EV/Sales, FCF yield), profitability (gross/operating/net/EBITDA margins, ROE, ROA, ROIC), leverage & liquidity (debt/equity, net debt/EBITDA, interest coverage, current ratio), efficiency (asset/inventory turnover, DSO, cash conversion cycle), and capital returns (dividend yield, dividend payout ratio, buyback yield, shareholder yield). Sector-inapplicable metrics are omitted (e.g. gross margin / FCF leverage for banks).
Pass 'metrics' to focus the table on specific metric_ids. For one company's value in an older fiscal year/quarter use get_metric_history. Each company's row is dated: 'Data through' is its latest reported period, and valuation multiples are priced at the last close on/before that period end (period-end LOCF) — NOT today's price, and the dates can differ across peers by a quarter. For a multiple AS OF a specific date, or at the live price, or a CUSTOM definition (e.g. lease-adjusted EV), assemble it from get_stock_price (price leg) + get_metric_history primitives.
peer_mode controls peer selection:
'sector' (default): auto-selected from same sector + similar market cap
'tags': auto-selected by business model similarity (tag Jaccard) — better for cross-sector comparisons
Override with custom_peers for specific matchups. The number of custom_peers is capped by plan (Free: 3, Pro: 10); exceeding it returns the limit and the count you asked for, so retry with that many.
Use Cases:
"Compare AAPL vs MSFT" -> compare_companies("AAPL", custom_peers="MSFT")
"How does NVDA stack up in its sector?" -> compare_companies("NVDA")
"Dividend payout ratio: KO vs KDP/PEP/KHC" -> compare_companies("KO", custom_peers="KDP,PEP,KHC", metrics="dividend_payout_ratio,dividend_yield")
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | Primary company ticker symbol to compare (e.g., 'AAPL'). Must be exact. | |
| metrics | No | Optional comma-separated metric_ids to show instead of the default curated table (e.g. 'dividend_payout_ratio,dividend_yield,ev_ebitda,roa,interest_coverage'). Drawn from the ~70 curated fundamentals. A near-miss such as 'operating_margin' is read as 'oper_margin' and said so; any other unknown id is named in the response with its closest ids. Responses cap at ~20K chars — a subset here (or fewer custom_peers) keeps a large comparison whole. | |
| peer_mode | No | Peer selection method: 'sector' (same sector + similar market cap, default) or 'tags' (business model similarity — finds companies with overlapping classification tags). Use 'tags' for cross-sector business model comparisons, e.g. NVDA vs AMD/Broadcom instead of NVDA vs MSFT/GOOG. | sector |
| period_type | No | 'TTM' (default): trailing twelve months. 'FY': each company's latest reported fiscal year. 'Q': each company's latest reported fiscal quarter. Each company is at ITS OWN latest period (fiscal years end in different months, e.g. CRM January, ORCL May), and the 'YoY' rows compare it with the same period a year earlier ('Prior period' row). At 'Q' the ratios annualized from one quarter (P/E, EV multiples, ROE/ROA/ROIC, yields, turnover) are not shown. net_interest_income (banks) is served at FY and Q only. Example: compare_companies("JPM", custom_peers="BAC,WFC", period_type="Q", metrics="net_interest_income,net_income"). | TTM |
| custom_peers | No | Optional comma-separated peer tickers (e.g., 'MSFT,GOOG,AMZN'). Auto-selected if omitted. |