Loading ToolBench
MCP server providing access to Financial Modeling Prep API for financial data, statements, ratios, and market data
This MCP server exposes 6 financial data retrieval tools via FastMCP/HTTP. All tools have descriptions (well above 20 chars) and explicit input schemas with parameter types and descriptions. Tool naming follows verb_noun convention (company_profile, income_statement, balance_sheet, cash_flow, financial_ratios, historical_price_eod_full). However, several quality gaps prevent a higher score: (1) Output schemas are NOT documented, the code calls fmp_api_request() but never specifies what fields the wrapped response contains or what the FMP API returns; (2) Tool names do not start with action verbs (get_, fetch_, retrieve_), they use domain nouns, which is less conventional for action tools; (3) No error recovery guidance, errors return a generic wrapper {success, error, message, data} without actionable next steps for the LLM; (4) No parameter validation or constraint documentation beyond type hints; (5) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being READ_ONLY; (6) Descriptions, while detailed and helpful, are quite long (200+ chars in most cases) and could be optimized for token efficiency. The server follows good patterns for secret injection (API key stored server-side via environment variable), stateless request handling, and clear parameter grouping.
Balance Sheet Statement API — assets, liabilities, and equity structure. Use this when: • You need capital structure, leverage, liquidity, or working-capital inputs. • You're comparing balance sheet strength across peers/time. Don't use when: • You want income/profitability flows (use income_statement). • You want cash generation/FCF (use cash_flow). Endpoint: `/stable/balance-sheet-statement` What it provides: • **Assets**: Current & noncurrent (e.g., `cashAndCashEquivalents`, `longTermInvestments`, `totalAssets`). • **Liabilities**: Short/long-term debts, `totalLiabilities`, deferred items. • **Equity**: `commonStock`, `retainedEarnings`, `totalStockholdersEquity`. • **Solvency/Liquidity Inputs**: Values to compute leverage and working-capital metrics. Example use: • Assess **liquidity & leverage** and compare structure across peers or over time. Args: symbol: Ticker symbol. limit: Number of periods to return. period: `annual` / `quarter` (also supports `Q1`..`Q4`, `FY`). Returns: A list of balance sheet rows (currency as reported).
Cash Flow Statement API — operating, investing, and financing cash flows. Use this when: • You need cash generation/usage details or to compute FCF. • You're analyzing sustainability of dividends/buybacks or financing activity. Don't use when: • You want margin/earnings lines (use income_statement). • You need capital structure snapshots (use balance_sheet). Endpoint: `/stable/cash-flow-statement` What it provides: • **Operating Cash Flow**: `netCashProvidedByOperatingActivities`, `operatingCashFlow`. • **Investing & Financing**: Capex, acquisitions, debt issuance/repayment, dividends, buybacks. • **Free Cash Flow**: `freeCashFlow` and components (`capitalExpenditure`). Example use: • Evaluate **cash generation** and **financial flexibility**, compare FCF across time. Args: symbol: Ticker symbol. limit: Number of periods to return. period: `annual` / `quarter` (also supports `Q1`..`Q4`, `FY`). Returns: A list of cash flow rows as in your example (currency as reported).
Output schemas are not documented. Tools return data wrapped in {success, data, count} but the structure of 'data' and field names are not specified. LLMs cannot plan downstream operations or extract specific fields without seeing the API response schema.
Tool names use domain nouns rather than action verbs. Conventional naming would be get_company_profile, fetch_income_statement, retrieve_balance_sheet, etc. Current names are less discoverable and don't immediately signal the action to LLMs.
Error responses lack recovery guidance. When fmp_api_request() fails, it returns {success: false, error, message, data: []} but does not tell the LLM whether the error is retryable, transient, or permanent, or what action to take next. Pattern requires 'what to do next' in error responses.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 59 | 2026-07-28+ | v2 |
Company Profile Data API — detailed fundamentals for a single symbol. Use this when: • You need a company's *current snapshot* (price, marketCap, beta, identifiers). • You're building a profile card or prepping context before deeper statement pulls. Don't use when: • You need periodized statements (use income_statement / balance_sheet / cash_flow). • You want multi-period ratios (use financial_ratios). Endpoint: `/stable/profile` What it provides (high-level): • **Stock Price & Market Cap**: Current `price` and `marketCap` for the symbol. • **Company Details**: `companyName`, long `description`, `CEO`, `industry`, `sector`, exchange info. • **Financial Metrics**: `beta`, `lastDividend`, trading `range` (e.g., 52-week), `volume`, `averageVolume`. • **Global Identifiers**: `cik`, `isin`, `cusip` to track the entity across platforms. • **Contact Information**: `address`, `city`, `state`, `zip`, `phone`, and `website`. • **IPO & Trading Flags**: `ipoDate`, `isActivelyTrading`, `isEtf`, `isAdr`, `isFund`. Typical uses: • Research a company's **current financial snapshot** (e.g., Apple) and extract key metrics for investment due diligence or profile cards. Args: symbol: Ticker symbol (e.g., "AAPL"). Returns: A 1-element list with the profile object as shown in your example.
Financial Ratios API — profitability, liquidity, efficiency, leverage. Use this when: • You want ready-made valuation, liquidity, efficiency, and leverage ratios. • You need quick multi-period ratio comparison for screening/peer comps. Don't use when: • You need raw statement lines (use income_statement / balance_sheet / cash_flow) to compute custom metrics. • You're requesting intraday/realtime multiples (daily snapshots only). Endpoint: `/stable/ratios` What it provides: • **Profitability**: `grossProfitMargin`, `netProfitMargin`, `ROE` proxies via margins and equity metrics. • **Liquidity**: `currentRatio`, `quickRatio`, `cashRatio`. • **Efficiency**: `assetTurnover`, `inventoryTurnover`, `receivablesTurnover`. • **Valuation & Debt**: `priceToEarningsRatio`, `priceToBookRatio`, `debtToEquityRatio`, `enterpriseValueMultiple`. Example use: • Cross-company **ratio comparisons** within a sector to evaluate stability and efficiency. Args: symbol: Ticker symbol. limit: Number of periods to return. period: `annual` / `quarter` (also supports `Q1`..`Q4`, `FY`). Returns: A list of ratio snapshots per period.
Stock Price & Volume Data API — full daily OHLCV + VWAP with changes. Use this when: • You need historical daily bars (OHLCV) and changes (with optional range). • You're doing backtests, trend analysis, or liquidity studies. Don't use when: • You need intraday/minute or realtime ticks (not provided here). • You're asking for corporate actions/adjustment events (use other endpoints).
Income Statement API — real-time & historical profitability view. Use this when: • You need revenue, cost, margins, EPS across periods (annual/quarterly). • You're computing profitability ratios or analyzing earnings trends. Don't use when: • You need assets/liabilities/equity (use balance_sheet). • You want cash flow specifics/FCF (use cash_flow). Endpoint: `/stable/income-statement` What it provides: • **Profitability Tracking**: `revenue`, `costOfRevenue`, `grossProfit`, `operatingIncome`, `netIncome`, `eps`, `epsDiluted`, etc., by period. • **Trend Identification**: Pull multiple periods (`limit`) to observe changes in revenue and expenses (e.g., FY vs. Q1–Q4). • **Comparative Analysis**: Use with peers to compare margins and earnings power. Example use: • Compute ratios like **P/E**, **gross margin**, or analyze **surprise vs. trend**. Args: symbol: Ticker symbol (e.g., "AAPL"). limit: Number of periods to return (max 1000 per request). period: One of `annual` / `quarter` or explicit tags like `Q1`..`Q4`, `FY`. Returns: A list of income statement rows as in your example (currency as reported).
No tool annotations despite all tools being READ_ONLY. The risk field in the specification indicates 'READ_ONLY' but the FastMCP tool decorator does not include readOnlyHint annotation, which would inform clients and LLMs that these tools are safe to call without user confirmation.
Parameter constraints are not validated or documented in descriptions. For example, 'limit' accepts any integer but FMP API has a max of 1000. The description states 'max 1000' but code does not enforce this, allowing LLMs to pass invalid values that the API will reject.
Descriptions are verbose (200+ characters). While detailed and helpful, they exceed the recommended 50-200 character range for optimal LLM token efficiency. Consider condensing to core guidance: what it does, when to use it, key caveats.