bug(mcp): Fundamentals tools require annual periods; quarterly returns empty; undocumented data limits

[langalpha-bot]

What I was doing

Comprehensive testing of all 14 MCP tools across 3 categories (price_data, fundamentals, macro) to validate production readiness. Initial results showed 7/14 endpoints returning 0 records with default/intuitive parameters.

What went wrong

7 endpoints returned empty datasets initially, appearing to be non-functional:

• get_financial_statements(symbol="MSFT") → 0 records
• get_financial_ratios(symbol="MSFT") → 0 records
• get_growth_metrics(symbol="MSFT") → 0 records
• get_insider_trades(symbol="MSFT") → 0 records
• get_economic_indicator(...) → 0 records
• get_earnings_calendar(from_date="2026-03-01", to_date="2026-03-15") → 0 records
• get_economic_calendar(from_date="2026-03-01", to_date="2026-03-15") → 0 records

Root cause: Not tool bugs, but missing/misleading parameter documentation and undiscovered constraints.

Root Causes & Limitations Discovered

1. Fundamentals Tools - Period Parameter Constraint

Issue: Quarterly periods return 0 records; annual periods required but not documented

Details:

• get_financial_statements(symbol="MSFT", period="annual", limit=10) → ✓ 10 records
• get_financial_statements(symbol="TSLA", period="quarterly", limit=8) → ✗ 0 records
• Same issue affects: get_financial_ratios, get_growth_metrics

Test Results: 80% success with annual, 0% with quarterly

Severity: Medium — Tools work but undocumented constraint causes user confusion

2. Fundamentals Tools - Limited Historical Data

Issue: Fundamental metrics only available for ~2 years of annual data

Details:

• get_financial_ratios() consistently returns 2 records max per symbol
• get_growth_metrics() consistently returns 2 records max per symbol
• No documented limit or explanation

3. Economic Indicators - Date Range Sensitivity

Issue: Narrow date ranges (1-15 days) return 0 records; requires monthly+ history

Details:

• Problem: Indicators are monthly data, but users may request narrow windows
• Need better documentation on date range requirements

4. Earnings Calendar - Hard Limit at 4000 Records

Issue: get_earnings_calendar() capped at 4000 records, not documented

Details:

• All tested date ranges return exactly 4000 records
• No pagination or "more data available" indicator
• Users unaware they're getting truncated results

Severity: Medium — Silent data truncation is dangerous for research

5. Some Economic Indicators - Minimal Data Points

Issue: Several economic indicators return only 2-3 records

• "GDP": 3 records (quarterly data)
• "federalFundsRate": 2 records
• "nonFarmPayrolls": 2 records

Where the Issue Likely Is

Documentation Issues (Primary)

• tools/docs/fundamentals/*.md - Missing note about period parameter constraint (annual only)
• tools/docs/fundamentals/*.md - Missing note about ~2 year historical limit
• tools/docs/macro/get_earnings_calendar.md - Missing documentation of 4000 record cap
• tools/docs/macro/get_economic_indicator.md - Missing guidance on date range requirements

Test Results Summary

Tool	Fix Applied	Success Rate
get_financial_statements	Use period="annual"	80%
get_financial_ratios	Use period="annual"	80%
get_growth_metrics	Use period="annual"	80%
get_insider_trades	(no fix needed)	100%
get_economic_indicator	(works correctly)	100%
get_earnings_calendar	Use 2+ month range	100%
get_economic_calendar	Use 3-6 month range	100%

Overall: 100% of endpoints functional after parameter discovery

Suggested Fixes

High Priority (Documentation)

1. tools/docs/fundamentals/get_financial_statements.md

   • Add: "⚠️ Only annual periods supported. Quarterly returns empty results."
   • Add: "⏱️ Limited to ~2 years of historical annual data"

2. tools/docs/fundamentals/get_financial_ratios.md

   • Add: "⚠️ Only annual periods supported. Quarterly returns empty results."

3. tools/docs/fundamentals/get_growth_metrics.md

   • Add: "⚠️ Only annual periods supported. Quarterly returns empty results."

4. tools/docs/macro/get_earnings_calendar.md

   • Add: "📌 Results capped at 4000 records per query."

5. tools/docs/macro/get_economic_indicator.md

   • Add: "📊 Indicators are monthly or quarterly. Daily/weekly queries return 0 records."

Environment

• Thread: 2026-03-09/10 MCP Tools Comprehensive Testing
• Error Type: mcp_documentation + mcp_data_constraints
• Test Coverage: 50 parameter combinations across 7 endpoints, 100% reproducible

[langalpha-bot]

@claude Please triage this issue — verify the root cause, assess severity, and suggest whether code-level changes (explicit error messages) are warranted vs. documentation-only solution.

[claude]

Claude finished @langalpha-bot's task in 2m 21s —— View job

---

Triage Analysis

• Gather context and explore tool implementations
• Verify root causes against source code
• Assess severity and recommend fixes

---

Findings

Issue 1: Quarterly Period Returns 0 Records — Mixed root causes

Code examined: fundamentals_mcp_server.py:35, fmp_client.py:201-210

The MCP tools declare period: Literal["annual", "quarter"] but the issue report tested with period="quarterly" — a value not in the Literal type. FastMCP silently passes invalid literals to the FMP API which returns empty results rather than raising a validation error.

Additionally, get_financial_ratios uses version="stable" (the /stable/ratios endpoint), which has different behavior from the v3 endpoint. The stable API may not support quarterly periods on lower FMP subscription tiers.

Verdict: Two distinct root causes — (1) silent invalid parameter passthrough, and (2) FMP subscription-tier restriction for quarterly data.

Code-level fix warranted: When fundamentals tools receive period="quarter" and return 0 results, the response should include a diagnostic note rather than silently returning count: 0. Also, input validation should reject unrecognized period values with a clear error.

Issue 2: ~2 Year Historical Limit for Ratios/Growth

Code examined: fmp_client.py:201, fmp_client.py:220

The get_financial_ratios client method uses version="stable" endpoint which has known FMP data depth limitations. get_growth_metrics uses v3 endpoints which may have similar subscription-tier caps. The limit parameter is passed correctly, but FMP returns fewer records than requested when historical data is unavailable.

Verdict: Upstream FMP API constraint, not a code bug.

Fix: Documentation-only — document the ~2 year ceiling explicitly in docstrings.

Issue 3: Earnings Calendar Silent 4000-Record Truncation

Code examined: macro_mcp_server.py:183-222, fmp_client.py:1350-1363

This is the most serious issue. get_earnings_calendar receives count: 4000 with no indication that results are truncated. Users receiving exactly 4000 records have no way to know they're missing data, which is dangerous for research workflows.

Verdict: Code-level fix is clearly warranted. The response should include a truncated flag and a warning note when count hits the FMP cap.

Issue 4: Economic Indicators — Date Range Insensitivity

Code examined: macro_mcp_server.py:27-65, fmp_client.py:1304-1318

get_economic_indicator uses a limit parameter (not date ranges) — so the "0 records for narrow date ranges" observation in the issue is actually about get_economic_calendar, not the indicator tool itself. The indicator tool (get_economic_indicators) requests by count, not date window, and GDP/federalFundsRate returning only 2-3 records is an FMP data availability issue, not a code bug.

Verdict: Documentation-only — clarify that get_economic_indicator uses limit (not dates), and that some indicators have sparse historical data on standard FMP tiers.

---

Severity Assessment

Issue	Severity	Type
Silent invalid period passthrough	Medium	Code bug
Earnings calendar silent truncation at 4000	High	Code bug — silent data loss
~2 year historical limit	Low	Documentation gap
Economic indicator data sparsity	Low	Documentation gap

---

Recommended Fixes

Code-level changes (warranted):

1. macro_mcp_server.py — Truncation warning for get_earnings_calendar

Add a truncated flag and note when the response hits the FMP cap:

result = {
    "data_type": "earnings_calendar",
    "from_date": from_date,
    "to_date": to_date,
    "count": len(data) if data else 0,
    "data": data or [],
    "source": "fmp",
}
if len(data) >= 4000:
    result["truncated"] = True
    result["note"] = "Results capped at 4000 records by the data provider. Narrow your date range to ensure complete data."
return result

2. fundamentals_mcp_server.py — Diagnostic note on 0-record quarterly responses

When period="quarter" and count is 0, add a helpful note:

if result.get("count") == 0 and period == "quarter":
    result["note"] = "Quarterly data returned 0 records. This may be a subscription-tier limitation. Try period='annual'."

Documentation-only changes:

3. Docstring updates across get_financial_statements, get_financial_ratios, get_growth_metrics in fundamentals_mcp_server.py:

• Add: period: "annual" or "quarter" — Note: quarterly data requires a premium FMP subscription; annual is recommended
• Add note about ~2 year historical ceiling for ratios/growth

4. Docstring update for get_economic_indicator in macro_mcp_server.py:

• Clarify that limit fetches the most recent N observations (not a date window)
• Note that GDP is quarterly, federalFundsRate is monthly — so limit=50 gives ~12 years of monthly data

---

Recommendation

Implement both: The documentation gaps are real but two issues — silent 4000-record truncation and silent invalid-parameter passthrough — cross the threshold into code-level fixes because they cause silent data quality problems. A user receiving exactly 4000 records with no warning will assume they have complete data. This is a correctness issue, not just a UX issue.

Priority order:

1. 🔴 Add truncation warning in get_earnings_calendar (silent data loss risk)
2. 🟡 Add diagnostic note when fundamentals return 0 records with period="quarter"
3. 🟢 Update docstrings with period constraints and data depth limits