> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Fundamentals Skills

> Reference for fundamentals.get, fundamentals.compare, fundamentals.pit, and analyst.ratings — the archive-backed fundamentals skills exposed to AI agents.

Fundamentals skills pull company financials snapshots, side-by-side comparisons, point-in-time data, and analyst consensus. Most are backed by **FMP**; `fundamentals.pit` uses **SEC** filings for as-of-date accuracy.

<Callout type="info">
  Every result includes the [provenance envelope](/skills/overview#the-provenance-envelope). Point-in-time calls are essential when backtesting — using current fundamentals for a historical date is lookahead bias.
</Callout>

## Skill summary

| Skill ID               | Tool name              | Source            | Runtime     | Description                                    |
| ---------------------- | ---------------------- | ----------------- | ----------- | ---------------------------------------------- |
| `fundamentals.get`     | `fundamentals_get`     | fmp               | interactive | Full fundamentals snapshot for a ticker        |
| `fundamentals.compare` | `fundamentals_compare` | fmp               | interactive | Side-by-side fundamentals for multiple tickers |
| `fundamentals.pit`     | `fundamentals_pit`     | sec               | interactive | Point-in-time fundamentals as of a date        |
| `analyst.ratings`      | `analyst_ratings`      | archive-community | interactive | Analyst ratings + price targets                |

***

## fundamentals.get

Returns a full fundamentals snapshot: valuation multiples, profitability ratios, growth rates, and balance-sheet summary.

**Arguments**

| Name                | Type     | Required | Default  | Description                                          |
| ------------------- | -------- | -------- | -------- | ---------------------------------------------------- |
| `symbol`            | string   | yes      | —        | Ticker symbol                                        |
| `period`            | string   | no       | `annual` | `annual` or `quarterly`                              |
| `statement`         | string   | no       | `all`    | `income`, `balance`, `cashflow`, `ratios`, or `all`  |
| `as_of`             | ISO date | no       | latest   | Snapshot date (uses most recent filing on or before) |
| `include_estimates` | bool     | no       | `false`  | Include consensus estimates                          |

**Source**: `fmp`

**Example**

```json theme={null}
fundamentals_get({ "symbol": "MSFT", "period": "annual", "statement": "ratios" })
```

```json theme={null}
{
  "skill_id": "fundamentals.get",
  "data": {
    "symbol": "MSFT",
    "period": "annual",
    "as_of": "2025-06-30",
    "ratios": {
      "pe_ttm": 36.2, "forward_pe": 32.1, "peg": 2.4,
      "ps": 11.8, "pb": 9.1, "ev_ebitda": 24.3,
      "roe": 0.39, "roa": 0.18, "gross_margin": 0.69,
      "net_margin": 0.36, "debt_to_equity": 0.22
    }
  },
  "provenance": { "source": "fmp", "freshness": { "as_of": "2025-06-27T22:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## fundamentals.compare

Side-by-side fundamentals for up to 10 tickers. Returns the same fields as `fundamentals.get` but pivoted by symbol.

**Arguments**

| Name      | Type      | Required | Default  | Description                                                     |
| --------- | --------- | -------- | -------- | --------------------------------------------------------------- |
| `symbols` | string\[] | yes      | —        | Tickers (max 10)                                                |
| `period`  | string    | no       | `annual` | `annual` or `quarterly`                                         |
| `fields`  | string\[] | no       | core set | Field names to include (e.g. `["pe_ttm","roe","gross_margin"]`) |
| `as_of`   | ISO date  | no       | latest   | Snapshot date                                                   |

**Source**: `fmp`

**Example**

```json theme={null}
fundamentals_compare({ "symbols": ["NVDA","AMD","INTC"], "fields": ["pe_ttm","roe","gross_margin","rev_growth_yoy"] })
```

```json theme={null}
{
  "skill_id": "fundamentals.compare",
  "data": {
    "as_of": "2025-06-30",
    "fields": ["pe_ttm","roe","gross_margin","rev_growth_yoy"],
    "rows": [
      { "symbol": "NVDA", "pe_ttm": 68.2, "roe": 0.91, "gross_margin": 0.75, "rev_growth_yoy": 2.08 },
      { "symbol": "AMD",  "pe_ttm": 152.4, "roe": 0.04, "gross_margin": 0.50, "rev_growth_yoy": 0.16 },
      { "symbol": "INTC", "pe_ttm": null,  "roe": -0.18, "gross_margin": 0.35, "rev_growth_yoy": -0.09 }
    ]
  },
  "provenance": { "source": "fmp", "freshness": { "as_of": "2025-06-27T22:00:00Z", "lag_seconds": 3600 }, "cost": { "credits": 6, "tier": "basic" }, "warnings": ["INTC: pe_ttm null (negative earnings)"] }
}
```

***

## fundamentals.pit

**Point-in-time** fundamentals — the values that were actually known on a given date. This is the lookahead-safe variant for backtests.

**Arguments**

| Name          | Type     | Required | Default     | Description                                                        |
| ------------- | -------- | -------- | ----------- | ------------------------------------------------------------------ |
| `symbol`      | string   | yes      | —           | Ticker symbol                                                      |
| `as_of`       | ISO date | yes      | —           | The date to snapshot (returns the most recent filing on or before) |
| `period`      | string   | no       | `annual`    | `annual` or `quarterly`                                            |
| `statement`   | string   | no       | `all`       | `income`, `balance`, `cashflow`, `ratios`, or `all`                |
| `filing_type` | string   | no       | `10-K,10-Q` | Restrict to specific filing types                                  |

**Source**: `sec`

<Callout type="warn">
  Use `fundamentals.pit` (not `fundamentals.get`) whenever you're computing something on historical dates. `fundamentals.get` with `as_of` returns the *current* values filtered by date, not the values known at that date.
</Callout>

**Example**

```json theme={null}
fundamentals_pit({ "symbol": "AAPL", "as_of": "2023-01-15", "statement": "income" })
```

```json theme={null}
{
  "skill_id": "fundamentals.pit",
  "data": {
    "symbol": "AAPL",
    "as_of": "2023-01-15",
    "filing_date": "2022-11-03",
    "filing_type": "10-K",
    "income": { "revenue": 394328000000, "net_income": 99803000000, "eps": 6.15 }
  },
  "provenance": { "source": "sec", "freshness": { "as_of": "2023-01-15T00:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 3, "tier": "basic" }, "warnings": [] }
}
```

***

## analyst.ratings

Analyst consensus ratings, price targets, and recent rating actions.

**Arguments**

| Name              | Type   | Required | Default | Description                              |
| ----------------- | ------ | -------- | ------- | ---------------------------------------- |
| `symbol`          | string | yes      | —       | Ticker symbol                            |
| `include_actions` | bool   | no       | `true`  | Include recent upgrade/downgrade actions |
| `include_targets` | bool   | no       | `true`  | Include price target distribution        |
| `lookback_days`   | int    | no       | `90`    | How far back to include actions          |
| `limit`           | int    | no       | `20`    | Max actions                              |

**Source**: `archive-community`

**Example**

```json theme={null}
analyst_ratings({ "symbol": "TSLA", "lookback_days": 30 })
```

```json theme={null}
{
  "skill_id": "analyst.ratings",
  "data": {
    "symbol": "TSLA",
    "consensus": { "rating": "Hold", "score": 2.8, "n_analysts": 38 },
    "price_target": { "mean": 218.40, "median": 215.00, "high": 310.00, "low": 85.00, "n": 38 },
    "actions": [
      { "date": "2025-06-24", "firm": "Morgan Stanley", "action": "downgrade", "from": "Overweight", "to": "Equal-Weight", "target": 250 },
      { "date": "2025-06-20", "firm": "Wedbush", "action": "maintain", "rating": "Outperform", "target": 275 }
    ]
  },
  "provenance": { "source": "archive-community", "freshness": { "as_of": "2025-06-27T18:00:00Z", "lag_seconds": 7200 }, "cost": { "credits": 2, "tier": "free" }, "warnings": [] }
}
```

## Next steps

<Card title="Financials & Earnings Skills" icon="file-invoice-dollar" href="/skills/financials">
  Income statements, balance sheets, cash flow, transcripts, earnings calendars, dividends, splits.
</Card>

<Card title="Congress & Insider Skills" icon="landmark" href="/skills/congress-insider">
  Congressional trades, late filings, insider Form 4 activity, and politician portfolios.
</Card>