roic.ai on this account returns only 2 years of history, not the 20-40 the Tool Hierarchy assumes

Claim

CLAUDE.md → Tool Hierarchy → tier 2 describes roic.ai as supplying "20-40yr statement history" and names it the escalation when fin.py's ~4 annual periods are not deep enough for the framework's 5–8yr CAGRs.

On the account currently authorized, it does not. Requests return a single fiscal year; anything reaching further back is refused. The account is on the Free plan, which caps history at 2 years. CLAUDE.md itself notes the free tier is "AAPL-only" and that a real portfolio needs the $29/mo Individual plan — the history cap is a second, separate consequence of the same plan level, and it is the one that silently breaks the analysis.

Why it is a trap rather than an inconvenience

The failure is not a permission error or an empty response. It returns valid data for a short window. An agent that asks for FY2019 and receives FY2025 has no error state to notice, and a CAGR computed across whatever came back is well-formed and wrong. This is the same shape as [[pitfall-stale-entry-zone-suppresses-a-name]]: the tool produces a plausible answer, so nothing prompts a second look.

Evidence

TEAM, 2026-08-07. The framework requires a 5–8yr FCF CAGR. fin.py carried FY22–FY25 only (and no FY26 at all, the 10-K being unfiled). Escalating to roic.ai per the Tool Hierarchy returned one year. The entire FY19–FY21 history in that analysis came from SEC XBRL companyfacts (CIK 0001650372) instead.

Note what did NOT go wrong: [[pitfall-roicai-fcf-field-returns-ocf]] was checked on the same call and passed — cf_free_cash_flow reconciled exactly to the filing for FY25. The data roic.ai returns is accurate. There is just almost none of it.

Rule

Do not escalate to roic.ai for multi-year history on this account. For anything older than fin.py's ~4 annual periods, go directly to SEC XBRL companyfacts: https://data.sec.gov/api/xbrl/companyfacts/CIK{10-digit-zero-padded}.json It is free, unauthenticated, covers the full filing history, and is the primary source rather than a vendor's rendering of it — see [[principle-primary-source-beats-vendor]].

roic.ai remains correct and useful for what it still does within its window: pre-computed ratios, earnings call transcripts, and cross-validating a suspect Yahoo figure for the current and prior year.

A CLAUDE.md edit is warranted if the plan is not upgraded — the Tool Hierarchy currently promises a capability the configured account does not have.

What would falsify this

Upgrading to the roic.ai Individual plan ($29/mo), which should restore the documented 20–40yr history. Re-test before trusting the tier-2 escalation again — this is an account-state property, not a vendor limitation, and it flips the moment the plan changes.

[[principle-primary-source-beats-vendor]] · [[pitfall-roicai-fcf-field-returns-ocf]] — the other known roic.ai trap, which was checked in the same session and did not fire.

History