Financials Tools

These tools answer questions like:

• "Compare Apple, TSMC, and Samsung's financials"
• "What's Toyota's gross margin trend over 5 years?"
• "Which companies have grown revenue for 3 consecutive years?"
• "What does 'free cash flow yield' mean as a screener field?"
• "Find stocks where EBITDA margin is expanding"

---

Tools at a glance

Tool	What it does	Credits
financials	Income, balance sheet, cash flow for 1–8 companies	1 per call
find_fsconcept	Resolve a financial concept phrase to a field key	Free
find_fspattern	Resolve a temporal pattern phrase to a pattern key	Free

Coverage: ~25,000 public companies globally. TTM (trailing twelve months) figures normalized to USD for cross-market comparison.

---

financials — Statements and comparisons

Reads financial statements for one or more tickers. Returns ratios, TTM income, balance sheet, and cash flow — normalized and in a consistent shape across markets.

Up to 8 tickers in one call. Cross-currency comparison converts to USD automatically (margins and growth rates are currency-neutral regardless).

Key params:

Param	Description
tickers	1–8 comma-separated MarketDX tickers (AAPL.US, 7203.JP, 005930.KO)
period	Time range — see period formats below
fields	Scope: income, balance, cashflow, or all. Default is a key-metrics digest
currency	Target currency for absolute dollar amounts. Default USD
format	json (default) or text (compact text table — ~70% fewer tokens, useful for AI contexts)

Period formats

Format	Example	What it returns
Integer (years)	5	Last 5 annual periods
Year range	2022-2024	Annual periods 2022–2024
Comma list	2020,2022,2024	Specific years only
Quarterly count	5q	Last 5 quarters
Quarter spec	2024Q2	One specific quarter
Keyword	quarterly	All available quarters

When to use vs asset_pulse

asset_pulse already embeds a fundamentals summary (revenue, margins, FCF, anomaly flags) for any stock — you don't need a separate financials call for a plain "how is X doing?" question.

Reach for financials when you need:

• A dedicated multi-company comparison ("compare Apple vs TSMC vs Samsung")
• Full quarterly history or a specific period range
• Complete income/balance/cashflow statements
• The text format to fit a tight token budget

:::note Equities only ETFs, commodities, bonds, and crypto have no company financials — those tickers return no data, which is expected. :::

---

find_fsconcept — Resolve a financial concept phrase

Translates any natural-language financial concept into the canonical field key used by screen_unified's fundamental leg and financials' fields parameter. Accepts any language.

Example inputs → what comes back:

Input	Canonical key
"gross profit margin"	gross_margin
"debt to equity"	debt_to_equity
"free cash flow yield"	fcf_yield
"수익성" (profitability, Korean)	net_margin, roe, roa candidates
"利益率" (profit margin, Japanese)	gross_margin, net_margin candidates
"EBITDA margin"	ebitda_margin

Returns a ranked candidate list — the AI picks the best match and uses the key in subsequent calls.

Optional statement filter (income, balance, cashflow) narrows the candidate scope.

This resolver is free (0 credits).

---

find_fspattern — Resolve a temporal pattern phrase

Translates a description of how a metric changes over time into the pattern key used by screen_unified's fundamental leg. This is the shape axis — not what metric, but how it moves.

Example inputs → what comes back:

Input	Pattern key
"three consecutive years of growth"	consecutive_growth, N: 3
"turning profitable"	turning_positive
"margin expanding"	expanding
"compound annual growth above 15%"	compound_growth, threshold: 0.15
"above 40%"	above, threshold: 0.40
"is negative"	is_negative

Returns a ranked candidate list with the pattern key and any required operands (N, threshold).

This resolver is free (0 credits).

---

Building a financial screen

The typical flow using these tools together:

1. find_fsconcept("gross margin")           → concept: "gross_margin"
2. find_fspattern("above 40%")              → pattern: "above", threshold: 0.40
3. find_fsconcept("revenue")               → concept: "revenue"
4. find_fspattern("3 years consecutive")   → pattern: "consecutive_growth", N: 3
5. screen_unified(
     fundamental=[
       {concept: "gross_margin", pattern: "above", threshold: 0.40},
       {concept: "revenue", pattern: "consecutive_growth", N: 3}
     ],
     gics="45",           ← IT sector (from find_gics)
     country=["US"]
   )

For the full pattern reference and all available field keys, see the Fundamental Leg screener docs.

---

Routing guide

You want to…	Use
Read or compare company financials	financials
Quick fundamentals summary in a "how is X doing?"	asset_pulse (financials block included)
Resolve a concept phrase for a screen	find_fsconcept (free)
Resolve a pattern phrase for a screen	find_fspattern (free)
Screen by financial conditions	screen_unified with the fundamental leg