Upload app.py

app.py

@@ -23,10 +23,32 @@ financial_analyzer = FinancialAnalyzer(
     user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
 )
 
-# Define MCP tools
+# Define MCP tools with detailed descriptions for LLM
 @mcp.tool()
 def search_company(company_name: str) -> dict:
-    """Search for a company by name in SEC EDGAR database."""
+    """
+    **STEP 1: START HERE** - Search for a company by name to get its CIK code.
+    
+    IMPORTANT: You MUST call this tool FIRST when the user mentions a company name.
+    The CIK code returned by this tool is REQUIRED for all other financial data tools.
+    
+    When to use:
+    - User mentions a company name ("Tesla", "Apple", "Microsoft")
+    - Before calling ANY other tool that requires a CIK parameter
+    - User asks about a company without providing CIK
+    
+    Workflow:
+    1. User asks: "Show me Tesla's financials"
+    2. YOU MUST: Call search_company("Tesla") FIRST
+    3. Get CIK from result: {"cik": "0001318605", ...}
+    4. THEN use that CIK in other tools: extract_financial_metrics("0001318605")
+    
+    Args:
+        company_name: Company name (e.g., "Tesla", "Apple Inc", "Microsoft")
+    
+    Returns:
+        dict with cik (REQUIRED for other tools), name, ticker, sic, sic_description
+    """
     result = edgar_client.search_company_by_name(company_name)
     return result if result else {"error": f"No company found with name: {company_name}"}
 
@@ -58,7 +80,32 @@ def get_financial_data(cik: str, period: str) -> dict:
 
 @mcp.tool()
 def extract_financial_metrics(cik: str, years: int = 3) -> dict:
-    """Extract comprehensive financial metrics for multiple years."""
+    """
+    **RECOMMENDED TOOL** - Extract multi-year financial data (annual + quarterly).
+    
+    CRITICAL: This tool requires a valid 10-digit CIK code.
+    If you don't have the CIK, you MUST call search_company() or advanced_search_company() FIRST!
+    
+    When to use:
+    - User asks about financial trends, growth, or multi-period analysis
+    - "Show me [company]'s financials" (most common use case)
+    - Need comprehensive financial overview
+    
+    CORRECT Workflow:
+    1. User: "Show me Tesla's financial metrics"
+    2. YOU: Call search_company("Tesla") → get CIK "0001318605"
+    3. YOU: Call extract_financial_metrics("0001318605", 3)
+    
+    WRONG Workflow (DO NOT DO THIS):
+    ❌ extract_financial_metrics("0001198872") ← Wrong CIK! Will fail!
+    
+    Args:
+        cik: 10-digit CIK code (e.g., "0001318605") from search_company()
+        years: Number of years (1-10, default 3)
+    
+    Returns:
+        Multi-year financial data with annual and quarterly metrics
+    """
     if years < 1 or years > 10:
         return {"error": "Years parameter must be between 1 and 10"}
     
@@ -70,13 +117,51 @@ def extract_financial_metrics(cik: str, years: int = 3) -> dict:
 
 @mcp.tool()
 def get_latest_financial_data(cik: str) -> dict:
-    """Get the most recent financial data available."""
+    """
+    Get the most recent financial snapshot (latest annual report only).
+    
+    CRITICAL: This tool requires a valid 10-digit CIK code.
+    If you don't have the CIK, you MUST call search_company() or advanced_search_company() FIRST!
+    
+    When to use:
+    - User asks for "latest" or "most recent" financial data
+    - Quick snapshot of current financial status
+    
+    CORRECT Workflow:
+    1. User: "What's Tesla's latest financial data?"
+    2. YOU: Call search_company("Tesla") → get CIK "0001318605"
+    3. YOU: Call get_latest_financial_data("0001318605")
+    
+    WRONG Workflow (DO NOT DO THIS):
+    ❌ get_latest_financial_data("0001198872") ← Wrong CIK! Will fail!
+    
+    Args:
+        cik: 10-digit CIK code (e.g., "0001318605") from search_company()
+    
+    Returns:
+        Latest annual financial data
+    """
     result = financial_analyzer.get_latest_financial_data(cik)
     return result if result and "period" in result else {"error": f"No latest financial data found for CIK: {cik}"}
 
 @mcp.tool()
 def advanced_search_company(company_input: str) -> dict:
-    """Advanced search supporting both company name and CIK code."""
+    """
+    **ALTERNATIVE TO search_company** - Flexible search supporting company name or CIK.
+    
+    Use this when:
+    - You need to find a company's CIK before calling other tools
+    - User provides either a company name OR a CIK code
+    - You want a single tool that handles both search types
+    
+    This tool returns the SAME format as search_company(), including the CIK needed for other tools.
+    
+    Args:
+        company_input: Company name OR CIK code
+    
+    Returns:
+        dict with cik (REQUIRED for other tools), name, ticker
+    """
     result = financial_analyzer.search_company(company_input)
     return result if not result.get("error") else {"error": result["error"]}