Skip to main content
skill CX Codex

historical-financial-ratings — Claude Code skill: setup guide

historical-financial-ratings fetches historical ratings and core financial metric grades for public tickers via Octagon MCP.

MIT 265 installs ★ 132 updated 2026-06-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add OctagonAI/skills --skill historical-financial-ratings -a claude-code
Open on GitHub

What historical-financial-ratings does

This skill guides the AI assistant in querying the octagon-agent tool provided by octagon-mcp. It structures requests by taking an equity ticker like NVDA, AAPL, or MSFT alongside a record limit between 100 and 5000 entries. Data originates from the octagon-financials-agent service.

The resulting table maps dates against overall scores, letter grades from A+ to F, and metric ratings on a 1-to-5 scale (where 5 denotes peak health). Metrics cover Return on Assets (ROA), Return on Equity (ROE), Discounted Cash Flow (DCF), and Debt-to-Equity (D/E).

Without an active Octagon MCP server configured in your environment, queries cannot retrieve records.

What it helps with

  • inspect historical letter grade transitions for public equities
  • screen operational efficiency trends across ROA and ROE metrics
  • monitor leverage health changes using historical D/E scores
  • retrieve DCF valuation scores across hundreds of data points

Example prompts for the agent

  • Retrieve historical financial ratings and key metric scores over time for NVDA, limited to 2000 records.
  • Retrieve historical financial ratings and key metric scores over time for AAPL, limited to 100 records.
  • Retrieve historical financial ratings and key metric scores over time for MSFT, limited to 5000 records.

How to install historical-financial-ratings

1Skills CLI (Vercel)

npx skills add OctagonAI/skills --skill historical-financial-ratings -a claude-code

2Manually: put the files in place

~/.claude/skills/historical-financial-ratings/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/historical-financial-ratings/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about historical-financial-ratings

How to install historical-financial-ratings in Claude Code?

Run npx skills add OctagonAI/skills --skill historical-financial-ratings -a claude-code in your shell. The skill file is placed at ~/.claude/skills/historical-financial-ratings/SKILL.md.

What prerequisite does this skill require?

Your AI environment must have the octagon-mcp server configured. The skill communicates directly through the octagon-agent tool.

Which data points does the query return?

The response provides time-stamped records containing an overall numerical score (1 to 5), an overall letter rating (A+ through F), plus ROA, ROE, DCF, and D/E scores.

Source text

SKILL.md · MIT
---
name: historical-financial-ratings
description: Retrieve historical financial ratings and key metric scores over time using Octagon MCP. Use when analyzing overall ratings, return on assets, return on equity, discounted cash flow scores, debt-to-equity scores, and letter grades (A+, A, B, etc.) for any public company.
---

# Historical Financial Ratings

Retrieve and analyze historical financial ratings and key metric scores over time for public companies using the Octagon MCP server.

## Prerequisites

Ensure Octagon MCP is configured in your AI agent (Cursor, Claude Desktop, Windsurf, etc.). See [references/mcp-setup.md](references/mcp-setup.md) for installation instructions.

## Workflow

### 1. Identify Analysis Parameters

Determine the following before querying:
- **Ticker**: Stock symbol (e.g., NVDA, AAPL, MSFT)
- **Records**: Number of historical data points to retrieve (e.g., 100, 500, 2000)

### 2. Execute Query via Octagon MCP

Use the `octagon-agent` tool with a natural language prompt:

```
Retrieve historical financial ratings and key metric scores over time for <TICKER>, limited to <N> records.
```

**MCP Call Format:**

```json
{
  "server": "octagon-mcp",
  "toolName": "octagon-agent",
  "arguments": {
    "prompt": "Retrieve historical financial ratings and key metric scores over time for NVDA, limited to 2000 records."
  }
}
```

### 3. Expected Output

The agent returns historical ratings data including:

| Date | Overall Score | Overall Rating | ROA Score | ROE Score | DCF Score | D/E Score |
|------|---------------|----------------|-----------|-----------|-----------|-----------|
| 2024-01-15 | 5 | A+ | 4 | 4 | 3 | 3 |
| 2024-01-08 | 5 | A+ | 4 | 4 | 3 | 3 |
| 2023-12-29 | 5 | A | 4 | 3 | 3 | 3 |
| ... | ... | ... | ... | ... | ... | ... |

**Data Sources**: octagon-financials-agent

### 4. Interpret Results

See [references/interpreting-results.md](references/interpreting-results.md) for guidance on:
- Understanding overall scores and ratings
- Analyzing individual metric scores
- Identifying rating trends and changes
- Spotting financial health improvements or deterioration

## Example Queries

**Standard Historical Analysis:**
```
Retrieve historical financial ratings and key metric scores over time for NVDA, limited to 2000 records.
```

**Recent Ratings Focus:**
```
Retrieve historical financial ratings and key metric scores over time for AAPL, limited to 100 records.
```

**Extended Historical View:**
```
Retrieve historical financial ratings and key metric scores over time for MSFT, limited to 5000 records.
```

## Key Metrics Explained

| Metric | Definition | Score Range |
|--------|------------|-------------|
| Overall Score | Composite financial health rating | 1-5 (5 = best) |
| Overall Rating | Letter grade for financial health | A+ to F |
| ROA Score | Return on Assets efficiency | 1-5 (5 = best) |
| ROE Score | Return on Equity efficiency | 1-5 (5 = best) |
| DCF Score | Discounted Cash Flow valuation score | 1-5 (5 = best) |
| D/E Score | Debt-to-Equity health | 1-5 (5 = lowest debt) |

## Analysis Tips

1. **Consistent high scores**: Companies maintaining 5-star overall scores and A+ ratings over extended periods demonstrate stable financial excellence.

2. **Score improvements**: Watch for upward trends in individual metrics (ROA, ROE) as indicators of improving operational efficiency.

3. **Debt management**: A stable or improving D/E score suggests the company is managing leverage responsibly.

4. **Rating downgrades**: Sudden drops in overall rating (e.g., A+ to B) warrant deeper investigation into financials.

5. **Diverging metrics**: If ROE is high but ROA is low, the company may be using significant leverage to boost returns.

## Use Cases

- **Investment screening**: Filter for companies with consistently high ratings
- **Risk monitoring**: Track rating changes for portfolio holdings
- **Due diligence**: Review historical financial health before investment decisions
- **Peer comparison**: Compare rating trajectories across competitors

© OctagonAI · MIT · OctagonAI/skills

Similar skills

All skills for Finance and business →

From the same set67

The whole set →
balance-sheet-growth balance-sheet-growth fetches year-over-year changes for major balance-sheet lines. Use it to examine liquidity, leverage, assets, equity, cash, and inventories. CX Codex +1 266installs stock-price-change Fetches stock price changes across ten periods — from one day to ten years. Builds a picture of momentum and trends on all horizons. CX Codex +1 266installs company-market-cap company-market-cap fetches the market capitalization of one publicly traded company through Octagon MCP. Use it to check company size or put a valuation in context. CX Codex +1 266installs earnings-product-pipeline earnings-product-pipeline extracts product development data from earnings calls: clinical trial status, regulatory submissions, launch timelines. CX Codex +1 265installs batch-market-cap batch-market-cap — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that pulls market capitalization data for a list of tickers in one call via Octagon MCP. CX Codex +1 265installs stock-performance The stock-performance skill retrieves daily closing prices, trading volumes, and performance metrics via Octagon MCP. Analyze trends, compare stocks, or assess volatility. CX Codex +1 265installs earnings-capital-allocation The earnings-capital-allocation skill pulls capital plans, shareholder returns, M&A signals, and investment priorities from earnings call transcripts. CX Codex +1 264installs earnings-analyst-questions earnings-analyst-questions is a Claude Code skill that analyzes questions from company earnings calls. It groups analyst concerns by topic and identifies who raised them. CX Codex +1 264installs

Project sponsors

Companies that keep this analytics open