yahoo-finance-mcp-server 1.2.2 → 1.2.5

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.5] - 2026-08-06
+
+### Added
+
+- Troubleshooting entry for running behind a non-Anthropic model or proxy
+  (LiteLLM, OpenRouter, NVIDIA NIM, local models). The server never talks to a
+  model, so the usual causes are a model without function calling, or a proxy
+  dropping unsupported parameters and silently stripping tool definitions.
+
+### Changed
+
+- README section order now matches the other servers in this family:
+  Troubleshooting comes before Manual Installation.
+
+## [1.2.4] - 2026-07-30
+
+### Fixed
+
+- Fresh installs no longer crash on startup. `requirements.txt` had no upper
+  bound on `mcp`, so after the MCP Python SDK 2.0.0 release (2026-07-28)
+  `pip install -r requirements.txt` pulled 2.x, which removed
+  `mcp.server.fastmcp` and made the server die with
+  `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`. The requirement
+  is now `mcp>=1.2.0,<2`. Existing installs were unaffected (the launcher
+  caches its virtualenv per requirements hash).
+
+## [1.2.3] - 2026-06-06
+
+### Changed
+
+- Enriched every tool description with purpose, when-to-use/disambiguation
+  guidance, and return/error behavior. This raises self-describing quality for
+  AI agents (and Glama's Tool Definition Quality score) while staying lean
+  (~140 tokens per tool); parameters remain self-documented via their field
+  descriptions.
+
+### Added
+
+- `Dockerfile`, `.dockerignore`, and `glama.json` to support a containerized
+  Glama release (builds `python:3.12-slim`, runs the server over stdio as a
+  non-root user). Verified locally: the image builds and `tools/list` returns
+  all 13 tools.
+
 ## [1.2.2] - 2026-06-04
 
 ### Fixed

package/README.md

@@ -1,200 +1,209 @@
-# Yahoo Finance MCP Server 📈
-
-[![npm version](https://img.shields.io/npm/v/yahoo-finance-mcp-server.svg)](https://www.npmjs.com/package/yahoo-finance-mcp-server)
-[![npm downloads](https://img.shields.io/npm/dm/yahoo-finance-mcp-server.svg)](https://www.npmjs.com/package/yahoo-finance-mcp-server)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-Real-time stock market data for Claude Desktop and any MCP-compatible client, powered by Yahoo Finance. Get quotes, historical prices, company profiles, financial statements, analyst ratings, and multi-stock comparisons, all from natural language.
-
-> **npm package:** [`yahoo-finance-mcp-server`](https://www.npmjs.com/package/yahoo-finance-mcp-server)  ·  **GitHub repo:** [`danishashko/yahoo-finance-mcp`](https://github.com/danishashko/yahoo-finance-mcp). The repo name is shorter than the package name; both refer to this project.
-
-## 🎯 What You Get
-
-- 📊 **Real-time stock quotes** with full market data
-- 📈 **Historical prices** (OHLCV) with summary statistics
-- 🏢 **Company profiles**, officers, and key statistics
-- 💰 **Financial statements** (income, balance sheet, cash flow)
-- 🎯 **Analyst ratings**, price targets, and the recent recommendation trend
-- ⚖️ **Multi-stock comparisons** side by side
-- 📰 **Latest financial news** per ticker
-- 🧾 **Options chains** (calls/puts, strikes, IV, open interest)
-- 🏦 **Ownership data** — institutional, mutual fund, and insider activity
-- 💵 **Dividend & split history**
-- 🔮 **Forward analyst estimates** (price targets, EPS/revenue, growth)
-- 🔎 **Symbol search** by company name or keyword
-- 🕒 **Market status** (open/closed) and index summary
-
-Every tool returns human-readable **markdown** by default, or structured **JSON** on request (`response_format: "json"`). Requests share a single browser-impersonating HTTP session to reduce Yahoo Finance rate-limiting.
-
-## 🚀 Quick Start
-
-Add this to your Claude Desktop config and restart Claude:
-
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "yahoo-finance": {
-      "command": "npx",
-      "args": ["-y", "yahoo-finance-mcp-server"]
-    }
-  }
-}
-```
-
-That is it. On first launch the npx wrapper creates an isolated Python environment and installs the dependencies for you (a one-time step that can take a minute). You only need **Python 3.10+** and **Node.js 16+** on your machine.
-
-### Prefer a global install?
-
-```bash
-npm install -g yahoo-finance-mcp-server
-```
-
-```json
-{
-  "mcpServers": {
-    "yahoo-finance": {
-      "command": "yahoo-finance-mcp-server"
-    }
-  }
-}
-```
-
-## 🔧 Available Tools
-
-| Tool | What it returns | Parameters |
-|------|-----------------|------------|
-| `get_stock_quote` | Current price, change, day and 52-week range, volume, market cap, P/E, EPS, dividend yield | `ticker` |
-| `get_historical_prices` | OHLCV history with summary stats and total return | `ticker`, `period`, `interval` |
-| `get_company_info` | Business summary, key executives, valuation and financial highlights | `ticker` |
-| `get_financial_statements` | Annual income statement, balance sheet, and cash flow | `ticker` |
-| `compare_stocks` | Key metrics for multiple tickers side by side, plus quick insights | `tickers` (2 to 10) |
-| `get_analyst_recommendations` | Price targets, consensus, recommendation trend, and recent upgrades/downgrades | `ticker` |
-| `get_market_news` | Latest news headlines with source, date, summary, and link | `ticker`, `count` |
-| `get_options_chain` | Expiration dates, or the calls/puts chain (strike, bid/ask, volume, OI, IV) | `ticker`, `expiration_date`, `option_type` |
-| `get_holders` | Institutional, mutual-fund, or major holders, or insider transactions | `ticker`, `holder_type` |
-| `get_dividends_splits` | Dividend payment history (with summary) and stock-split history | `ticker` |
-| `get_analyst_estimates` | Forward price targets, EPS/revenue estimates by period, and growth estimates | `ticker` |
-| `search_symbols` | Find ticker symbols by company name or keyword | `query`, `count` |
-| `get_market_status` | Whether a market is open/closed, with timing and a major-index summary | `region` |
-
-Every tool also accepts `response_format` (`"markdown"`, the default, or `"json"`).
-
-**`get_historical_prices` options:**
-
-- `period`: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max`
-- `interval`: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, `1wk`, `1mo`, `3mo`
-
-**`get_options_chain`:** call without `expiration_date` to list available dates, then again with a date. `option_type` is `calls`, `puts`, or `both`.
-
-**`get_holders`:** `holder_type` is `institutional`, `mutualfund`, `major`, or `insider_transactions`.
-
-## 💬 Example Prompts
-
-Once the server is connected, just ask Claude:
-
-- "What's the current price of Apple stock?"
-- "Show me Amazon's stock performance over the last year"
-- "Tell me about Tesla as a company and who runs it"
-- "Show me Apple's income statement"
-- "Compare AAPL, MSFT, and GOOGL"
-- "What do analysts think about Amazon, and what's the price target?"
-- "What's the latest news on NVIDIA?"
-- "Show me the SPY call options expiring next month"
-- "Who are the biggest institutional holders of Apple?"
-- "What's Coca-Cola's dividend history?"
-
-## 🛠️ Manual Installation (Alternative)
-
-If you would rather run the Python file directly instead of via npx:
-
-**1. Download the server**
-
-Save `yahoo_finance_mcp.py` somewhere on your machine and install the dependencies:
-
-```bash
-pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
-```
-
-(or `pip3` on macOS/Linux)
-
-**2. Point Claude Desktop at it**
-
-```json
-{
-  "mcpServers": {
-    "yahoo-finance": {
-      "command": "python3",
-      "args": ["/absolute/path/to/yahoo_finance_mcp.py"]
-    }
-  }
-}
-```
-
-On Windows use `"command": "python"` and a path like `"C:\\path\\to\\yahoo_finance_mcp.py"` (double backslashes or forward slashes).
-
-**3. Restart Claude Desktop.**
-
-## 🐛 Troubleshooting
-
-**"Command not found" / "Python not found"**
-Make sure Python and Node.js are installed and on your PATH. On macOS/Linux, try `python3` instead of `python` in the config.
-
-**"Module not found: yfinance" (manual install only)**
-Install the dependencies:
-
-```bash
-pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
-```
-
-**Tools not showing up in Claude**
-1. Confirm the config file is valid JSON (no trailing commas).
-2. Fully quit and reopen Claude Desktop.
-3. Check the path in your config actually exists.
-
-**"Error fetching data"**
-- Check your internet connection.
-- Verify the ticker symbol (for example `AAPL`, not `Apple`).
-- Some smaller companies have limited data, and Yahoo Finance can be briefly unavailable.
-
-## 🔒 Privacy & Rate Limits
-
-- Uses the free Yahoo Finance API via the `yfinance` library.
-- Requests go straight to Yahoo Finance. Nothing is stored or proxied.
-- Yahoo Finance rate-limits roughly 2,000 requests/hour per IP.
-- Intended for personal, educational, and research use.
-
-## 📝 Notes
-
-- Use ticker symbols in uppercase (`AAPL`, `MSFT`, `TSLA`).
-- Some quotes may be delayed 15 to 20 minutes.
-- Financial statements are generally available for larger public companies.
-
-## 📋 Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for the full version history. The core fixes (tool input validation, analyst recommendations, dividend yield, working `npx` install) landed in **v1.1.0**.
-
-## 📚 Resources
-
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [yfinance documentation](https://ranaroussi.github.io/yfinance/)
-- [Python downloads](https://www.python.org/downloads/)
-- [Claude Desktop](https://claude.ai/download)
-
-## ⚖️ Legal Disclaimer
-
-This tool uses Yahoo Finance's publicly available data through the `yfinance` library. Yahoo!, Y!Finance, and Yahoo! Finance are registered trademarks of Yahoo, Inc. This tool is not affiliated with, endorsed by, or vetted by Yahoo, Inc. Please refer to Yahoo!'s terms of use for details on your rights to use the data.
-
-## 👤 Author
-
-**Daniel Shashko**
-- GitHub: [@danishashko](https://github.com/danishashko)
-- LinkedIn: [daniel-shashko](https://linkedin.com/in/daniel-shashko)
-- npm: [danielshashko](https://www.npmjs.com/~danielshashko)
-
-## 📄 License
-
-MIT © Daniel Shashko
+# Yahoo Finance MCP Server 📈
+
+[![npm version](https://img.shields.io/npm/v/yahoo-finance-mcp-server.svg)](https://www.npmjs.com/package/yahoo-finance-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/yahoo-finance-mcp-server.svg)](https://www.npmjs.com/package/yahoo-finance-mcp-server)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Real-time stock market data for Claude Desktop and any MCP-compatible client, powered by Yahoo Finance. Get quotes, historical prices, company profiles, financial statements, analyst ratings, and multi-stock comparisons, all from natural language.
+
+> **npm package:** [`yahoo-finance-mcp-server`](https://www.npmjs.com/package/yahoo-finance-mcp-server)  ·  **GitHub repo:** [`danishashko/yahoo-finance-mcp`](https://github.com/danishashko/yahoo-finance-mcp). The repo name is shorter than the package name; both refer to this project.
+
+## 🎯 What You Get
+
+- 📊 **Real-time stock quotes** with full market data
+- 📈 **Historical prices** (OHLCV) with summary statistics
+- 🏢 **Company profiles**, officers, and key statistics
+- 💰 **Financial statements** (income, balance sheet, cash flow)
+- 🎯 **Analyst ratings**, price targets, and the recent recommendation trend
+- ⚖️ **Multi-stock comparisons** side by side
+- 📰 **Latest financial news** per ticker
+- 🧾 **Options chains** (calls/puts, strikes, IV, open interest)
+- 🏦 **Ownership data** — institutional, mutual fund, and insider activity
+- 💵 **Dividend & split history**
+- 🔮 **Forward analyst estimates** (price targets, EPS/revenue, growth)
+- 🔎 **Symbol search** by company name or keyword
+- 🕒 **Market status** (open/closed) and index summary
+
+Every tool returns human-readable **markdown** by default, or structured **JSON** on request (`response_format: "json"`). Requests share a single browser-impersonating HTTP session to reduce Yahoo Finance rate-limiting.
+
+## 🚀 Quick Start
+
+Add this to your Claude Desktop config and restart Claude:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "yahoo-finance": {
+      "command": "npx",
+      "args": ["-y", "yahoo-finance-mcp-server"]
+    }
+  }
+}
+```
+
+That is it. On first launch the npx wrapper creates an isolated Python environment and installs the dependencies for you (a one-time step that can take a minute). You only need **Python 3.10+** and **Node.js 16+** on your machine.
+
+### Prefer a global install?
+
+```bash
+npm install -g yahoo-finance-mcp-server
+```
+
+```json
+{
+  "mcpServers": {
+    "yahoo-finance": {
+      "command": "yahoo-finance-mcp-server"
+    }
+  }
+}
+```
+
+## 🔧 Available Tools
+
+| Tool | What it returns | Parameters |
+|------|-----------------|------------|
+| `get_stock_quote` | Current price, change, day and 52-week range, volume, market cap, P/E, EPS, dividend yield | `ticker` |
+| `get_historical_prices` | OHLCV history with summary stats and total return | `ticker`, `period`, `interval` |
+| `get_company_info` | Business summary, key executives, valuation and financial highlights | `ticker` |
+| `get_financial_statements` | Annual income statement, balance sheet, and cash flow | `ticker` |
+| `compare_stocks` | Key metrics for multiple tickers side by side, plus quick insights | `tickers` (2 to 10) |
+| `get_analyst_recommendations` | Price targets, consensus, recommendation trend, and recent upgrades/downgrades | `ticker` |
+| `get_market_news` | Latest news headlines with source, date, summary, and link | `ticker`, `count` |
+| `get_options_chain` | Expiration dates, or the calls/puts chain (strike, bid/ask, volume, OI, IV) | `ticker`, `expiration_date`, `option_type` |
+| `get_holders` | Institutional, mutual-fund, or major holders, or insider transactions | `ticker`, `holder_type` |
+| `get_dividends_splits` | Dividend payment history (with summary) and stock-split history | `ticker` |
+| `get_analyst_estimates` | Forward price targets, EPS/revenue estimates by period, and growth estimates | `ticker` |
+| `search_symbols` | Find ticker symbols by company name or keyword | `query`, `count` |
+| `get_market_status` | Whether a market is open/closed, with timing and a major-index summary | `region` |
+
+Every tool also accepts `response_format` (`"markdown"`, the default, or `"json"`).
+
+**`get_historical_prices` options:**
+
+- `period`: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max`
+- `interval`: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `90m`, `1h`, `1d`, `5d`, `1wk`, `1mo`, `3mo`
+
+**`get_options_chain`:** call without `expiration_date` to list available dates, then again with a date. `option_type` is `calls`, `puts`, or `both`.
+
+**`get_holders`:** `holder_type` is `institutional`, `mutualfund`, `major`, or `insider_transactions`.
+
+## 💬 Example Prompts
+
+Once the server is connected, just ask Claude:
+
+- "What's the current price of Apple stock?"
+- "Show me Amazon's stock performance over the last year"
+- "Tell me about Tesla as a company and who runs it"
+- "Show me Apple's income statement"
+- "Compare AAPL, MSFT, and GOOGL"
+- "What do analysts think about Amazon, and what's the price target?"
+- "What's the latest news on NVIDIA?"
+- "Show me the SPY call options expiring next month"
+- "Who are the biggest institutional holders of Apple?"
+- "What's Coca-Cola's dividend history?"
+
+## 🐛 Troubleshooting
+
+**"Command not found" / "Python not found"**
+Make sure Python and Node.js are installed and on your PATH. On macOS/Linux, try `python3` instead of `python` in the config.
+
+**"Module not found: yfinance" (manual install only)**
+Install the dependencies:
+
+```bash
+pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
+```
+
+**Tools not showing up in Claude**
+1. Confirm the config file is valid JSON (no trailing commas).
+2. Fully quit and reopen Claude Desktop.
+3. Check the path in your config actually exists.
+
+**"Error fetching data"**
+- Check your internet connection.
+- Verify the ticker symbol (for example `AAPL`, not `Apple`).
+- Some smaller companies have limited data, and Yahoo Finance can be briefly unavailable.
+
+**Using a different model or provider (LiteLLM, OpenRouter, NVIDIA NIM, a local model)**
+This server never talks to a model. Your client starts it as a local process and
+speaks JSON-RPC over stdin/stdout, so changing `ANTHROPIC_BASE_URL` or swapping the
+model behind your client has no effect on it. If tools stop firing after a switch
+like that, check two things: the model has to support function calling, and a proxy
+configured to drop unsupported parameters can silently strip your tool definitions,
+which produces no error at all. Run `/mcp` in your client (or `claude mcp list`) to
+confirm the server is connected before suspecting the server.
+
+## 🛠️ Manual Installation (Alternative)
+
+If you would rather run the Python file directly instead of via npx:
+
+**1. Download the server**
+
+Save `yahoo_finance_mcp.py` somewhere on your machine and install the dependencies:
+
+```bash
+pip install yfinance curl_cffi pandas tabulate mcp pydantic httpx
+```
+
+(or `pip3` on macOS/Linux)
+
+**2. Point Claude Desktop at it**
+
+```json
+{
+  "mcpServers": {
+    "yahoo-finance": {
+      "command": "python3",
+      "args": ["/absolute/path/to/yahoo_finance_mcp.py"]
+    }
+  }
+}
+```
+
+On Windows use `"command": "python"` and a path like `"C:\\path\\to\\yahoo_finance_mcp.py"` (double backslashes or forward slashes).
+
+**3. Restart Claude Desktop.**
+
+## 🔒 Privacy & Rate Limits
+
+- Uses the free Yahoo Finance API via the `yfinance` library.
+- Requests go straight to Yahoo Finance. Nothing is stored or proxied.
+- Yahoo Finance rate-limits roughly 2,000 requests/hour per IP.
+- Intended for personal, educational, and research use.
+
+## 📝 Notes
+
+- Use ticker symbols in uppercase (`AAPL`, `MSFT`, `TSLA`).
+- Some quotes may be delayed 15 to 20 minutes.
+- Financial statements are generally available for larger public companies.
+
+## 📋 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history. The core fixes (tool input validation, analyst recommendations, dividend yield, working `npx` install) landed in **v1.1.0**.
+
+## 📚 Resources
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [yfinance documentation](https://ranaroussi.github.io/yfinance/)
+- [Python downloads](https://www.python.org/downloads/)
+- [Claude Desktop](https://claude.ai/download)
+
+## ⚖️ Legal Disclaimer
+
+This tool uses Yahoo Finance's publicly available data through the `yfinance` library. Yahoo!, Y!Finance, and Yahoo! Finance are registered trademarks of Yahoo, Inc. This tool is not affiliated with, endorsed by, or vetted by Yahoo, Inc. Please refer to Yahoo!'s terms of use for details on your rights to use the data.
+
+## 👤 Author
+
+**Daniel Shashko**
+- GitHub: [@danishashko](https://github.com/danishashko)
+- LinkedIn: [daniel-shashko](https://linkedin.com/in/daniel-shashko)
+- npm: [danielshashko](https://www.npmjs.com/~danielshashko)
+
+## 📄 License
+
+MIT © Daniel Shashko

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yahoo-finance-mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.5",
   "mcpName": "io.github.danishashko/yahoo-finance-mcp",
   "description": "Yahoo Finance MCP Server - Real-time stock data, company info, financial statements, and market analysis via Model Context Protocol",
   "main": "bin/cli.js",

package/requirements.txt

@@ -1,10 +1,11 @@
-# Yahoo Finance MCP Server Requirements
-# Install all dependencies with: pip install -r requirements.txt
-
-yfinance>=0.2.61
-curl_cffi>=0.7.0
-pandas>=1.5.0
-tabulate>=0.9.0
-mcp>=1.2.0
-pydantic>=2.0.0
-httpx>=0.24.0
+# Yahoo Finance MCP Server Requirements
+# Install all dependencies with: pip install -r requirements.txt
+
+yfinance>=0.2.61
+curl_cffi>=0.7.0
+pandas>=1.5.0
+tabulate>=0.9.0
+# Pinned below 2.0: the v2 SDK removed mcp.server.fastmcp, which this server uses.
+mcp>=1.2.0,<2
+pydantic>=2.0.0
+httpx>=0.24.0

package/server.json

@@ -1,21 +1,23 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.danishashko/yahoo-finance-mcp",
-  "description": "Real-time stock market data from Yahoo Finance: quotes, history, financials, analyst ratings, options, holders, dividends, news, and market status.",
+  "description": "Real-time Yahoo Finance data: quotes, history, financials, analyst ratings, options, and news.",
   "title": "Yahoo Finance",
   "repository": {
     "url": "https://github.com/danishashko/yahoo-finance-mcp",
     "source": "github"
   },
-  "version": "1.2.2",
+  "version": "1.2.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "yahoo-finance-mcp-server",
-      "version": "1.2.2",
+      "version": "1.2.5",
       "runtimeHint": "npx",
-      "transport": { "type": "stdio" }
+      "transport": {
+        "type": "stdio"
+      }
     }
   ]
 }

package/yahoo_finance_mcp.py

@@ -302,7 +302,12 @@ async def get_stock_quote(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Current stock quote: price, change, day/52-week range, volume, market cap, P/E, EPS, dividend yield. Use for "what's the price of [stock]"."""
+    """Real-time quote snapshot for ONE stock: last price, day change ($ and %), open, previous close, day range, 52-week range, volume and average volume, market cap, beta, trailing P/E, EPS, dividend yield, and sector/industry/website.
+
+    Use for "what's the price of X" or a quick single-stock snapshot. For several stocks side by side use compare_stocks; for the full company profile use get_company_info; for a past price series use get_historical_prices.
+
+    Returns Markdown by default, or structured JSON when response_format='json'. An unknown ticker or an upstream/rate-limit error returns a short error message rather than raising.
+    """
     ticker = _norm_ticker(ticker)
     try:
         ticker_obj = make_ticker(ticker)
@@ -439,7 +444,12 @@ async def get_historical_prices(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Historical OHLCV price data with summary stats and total return, for trends/charting. Use for "how has [stock] performed over [period]"."""
+    """Historical OHLCV price series for one stock over a chosen period/interval, plus summary stats (highest/lowest/average close, average volume) and total return over the window.
+
+    Use for performance, trends, or charting ("how has X done over the last year"). For a single current price use get_stock_quote; for dividend/split events use get_dividends_splits. Note: intraday intervals (1m-90m) are only available for short recent periods, and long periods return many rows, so prefer JSON or a shorter period if the output is truncated.
+
+    Returns Markdown (summary stats plus the last 10 rows) by default, or the full series as JSON when response_format='json'. An empty or unsupported period/interval combination returns a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         ticker_obj = make_ticker(ticker)
@@ -533,7 +543,12 @@ async def get_company_info(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Company profile: business summary, executives, valuation and financial-highlight stats. Use for "what does [company] do" or company background."""
+    """Detailed company profile for one stock: long business summary, sector/industry, key executives, headquarters/website/employee count, and valuation & financial-highlight stats (market cap, P/E, margins, and similar).
+
+    Use for "what does X do", company background, or a business overview. For the statement-level numbers (income/balance/cash flow) use get_financial_statements; for just the live price use get_stock_quote.
+
+    Returns Markdown by default, or JSON when response_format='json'. An unknown ticker or upstream error returns a short error message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         ticker_obj = make_ticker(ticker)
@@ -655,7 +670,12 @@ async def get_financial_statements(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Annual income statement, balance sheet, and cash flow. Use for revenue, earnings, assets/liabilities, or fundamental analysis."""
+    """Annual financial statements for one company: income statement, balance sheet, and cash flow statement, each with multiple years of data.
+
+    Use for revenue, earnings, assets/liabilities, cash flow, or fundamental analysis. For headline ratios only use get_company_info; for forward projections use get_analyst_estimates. Quarterly data is not returned; request JSON for the complete machine-readable export.
+
+    Returns Markdown by default, or JSON when response_format='json'. Companies without filed statements (for example some ETFs or ADRs) return empty sections or a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         ticker_obj = make_ticker(ticker)
@@ -740,7 +760,12 @@ async def compare_stocks(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Compare key metrics for 2-10 stocks side by side, with quick insights. Use for "which is better, X or Y" or relative performance."""
+    """Side-by-side comparison of 2-10 stocks across key metrics (price, market cap, P/E, EPS, dividend yield, 52-week range, and period performance) with brief auto-generated insights.
+
+    Use for "which is better, X or Y", peer/relative comparison, or screening a small set. For a deep dive on a single name use get_stock_quote or get_company_info.
+
+    Pass 2-10 tickers in the tickers list. Returns a Markdown comparison table by default, or JSON when response_format='json'. A ticker that fails to resolve is reported per-symbol rather than failing the whole call.
+    """
     tickers = [_norm_ticker(t) for t in tickers]
     try:
         comparison_data = []
@@ -841,7 +866,12 @@ async def get_analyst_recommendations(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Analyst price targets, consensus rating, recommendation trend, and recent upgrades/downgrades. Use for "what do analysts think of [stock]". For forward EPS/revenue estimates use get_analyst_estimates."""
+    """Wall Street analyst view on one stock: price targets (high/mean/low), consensus rating, the buy/hold/sell recommendation-trend breakdown, and recent upgrades/downgrades.
+
+    Use for "what do analysts think of X", ratings, or sentiment. For forward EPS/revenue/growth projections use get_analyst_estimates instead: this tool is ratings and targets, that one is the numeric estimates.
+
+    Returns Markdown by default, or JSON when response_format='json'. A stock with no analyst coverage returns the available fields as N/A; errors return a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         ticker_obj = make_ticker(ticker)
@@ -981,7 +1011,12 @@ async def get_market_news(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Latest news headlines for a stock (source, date, summary, link). Use for "what's the latest news on [stock]"."""
+    """Latest news articles for one stock; each item has a title, publisher/source, publish date, a short summary, and a link.
+
+    Use for "what's the latest news on X", recent headlines, or catalysts. Returns news only: for price use get_stock_quote, for fundamentals use the financials tools.
+
+    count sets how many articles to return (1-20, default 10). Returns Markdown by default, or JSON when response_format='json'. No recent news returns a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         articles = make_ticker(ticker).get_news(count=count) or []
@@ -1085,7 +1120,12 @@ async def get_options_chain(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Options chain (strike, bid/ask, volume, open interest, IV) for an expiration. Call with no expiration_date first to list available dates, then again with a date."""
+    """Equity options data for one underlying, in two modes: call with no expiration_date to LIST every available expiration date; call again with a specific 'YYYY-MM-DD' to get that expiration's chain (strike, bid/ask, last, volume, open interest, implied volatility).
+
+    Use for options pricing, implied volatility, or open-interest analysis. option_type selects 'calls', 'puts', or 'both'. Always discover the valid dates first (call with no date) before requesting a chain, since only listed expirations work.
+
+    Returns Markdown by default, or JSON when response_format='json'. A ticker with no listed options returns a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         t = make_ticker(ticker)
@@ -1178,7 +1218,12 @@ async def get_holders(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Stock ownership and insider activity by holder_type: institutional, mutualfund, major (insider-vs-institutional %), or insider_transactions."""
+    """Ownership and insider activity for one stock, selected by holder_type: 'institutional' (top institutional holders), 'mutualfund' (top fund holders), 'major' (insider-vs-institutional ownership % breakdown), or 'insider_transactions' (recent insider buys and sells).
+
+    Use for "who owns X", institutional ownership, or insider trading activity. One holder_type per call: call again to get a different view.
+
+    Returns Markdown by default, or JSON when response_format='json'. Missing data for the chosen category returns a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         t = make_ticker(ticker)
@@ -1249,7 +1294,12 @@ async def get_dividends_splits(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Dividend payment history (with trailing summary) and stock-split history for a stock."""
+    """Full dividend payment history (with a trailing-period summary) and the stock-split history for one stock.
+
+    Use for dividend-income analysis, payment dates and amounts, dividend growth, or past split events. For the current/forward dividend yield use get_stock_quote; for price history use get_historical_prices.
+
+    Returns Markdown by default, or JSON when response_format='json'. A stock that pays no dividend or has never split returns a short message noting that none exist.
+    """
     ticker = _norm_ticker(ticker)
     try:
         t = make_ticker(ticker)
@@ -1344,7 +1394,12 @@ async def get_analyst_estimates(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Forward analyst estimates: price targets, EPS/revenue estimates by period, and growth. Complements get_analyst_recommendations (ratings/trend) with projected numbers."""
+    """Forward-looking analyst estimates for one stock: price targets, EPS and revenue estimates by period (current and next quarter and year), and growth estimates.
+
+    Use for projected/expected numbers and forecasts. This complements get_analyst_recommendations: that tool returns ratings and the recommendation trend, this one returns the numeric forward estimates.
+
+    Returns Markdown by default, or JSON when response_format='json'. A stock without analyst coverage returns the available fields as N/A or a short message.
+    """
     ticker = _norm_ticker(ticker)
     try:
         t = make_ticker(ticker)
@@ -1447,7 +1502,12 @@ async def search_symbols(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Find ticker symbols by company name or keyword. Use to resolve a name to a ticker before calling other tools."""
+    """Resolve a company name or keyword to ticker symbols; each match returns the symbol, name, exchange, and instrument type (equity, ETF, and so on).
+
+    Use this first when you have a company or brand name but not its ticker, then pass the resolved symbol to the other tools. Not for fetching prices or fundamentals.
+
+    query is the name/keyword to search; count caps the number of matches (1-20, default 8). Returns Markdown by default, or JSON when response_format='json'. No matches returns a short message.
+    """
     query = query.strip()
     try:
         session = _get_session()
@@ -1523,7 +1583,12 @@ async def get_market_status(
         ),
     ] = ResponseFormat.MARKDOWN,
 ) -> str:
-    """Whether a market (by region code, e.g. US/GB/JP) is open or closed, with timing and a major-index summary."""
+    """Whether a stock market is currently open or closed for a given region, with trading-session timing and a summary of that region's major indices.
+
+    Use for "is the US market open", market hours, or a quick index overview. region is a country code (US, GB, CA, DE, FR, IN, JP, HK, AU; default US). This is market-wide, not per-stock: use get_stock_quote for an individual price.
+
+    Returns Markdown by default, or JSON when response_format='json'. An unrecognized region returns a short message.
+    """
     region = region.strip().upper()
     try:
         session = _get_session()