tradingview-mcp 1.0.0__py3-none-any.whl → 1.0__py3-none-any.whl

tradingview_mcp/server.py

@@ -7,8 +7,12 @@ Provides comprehensive MCP tools and resources for TradingView market screening.
 from __future__ import annotations
 
 import argparse
+import inspect
 import json
 import os
+import traceback
+from datetime import datetime
+from functools import wraps
 from typing import Any, Optional
 
 from mcp.server.fastmcp import FastMCP
@@ -38,17 +42,141 @@ from tradingview_mcp.utils import (
     sanitize_timeframe,
     timeframe_to_resolution,
 )
+from tradingview_mcp.docs_data import (
+    get_ai_quick_reference,
+    get_column_display_names,
+    get_common_fields,
+    get_fields_by_market,
+    get_markets_data,
+    get_metainfo as load_metainfo,
+    get_screener_code_examples,
+    get_screener_markets,
+    get_screener_presets,
+    paginate_data,
+    search_fields,
+    get_field_summary,
+    estimate_tokens,
+    truncate_for_tokens,
+    MAX_ITEMS_DEFAULT,
+)
 
 # Initialize MCP Server
 mcp = FastMCP(
     name="TradingView Screener MCP",
-    instructions=(
-        "A comprehensive MCP server for TradingView market screening. "
-        "Provides tools for stock and cryptocurrency screening, technical analysis, "
-        "and market data retrieval. Supports 76+ markets and 250+ technical indicators."
-    ),
+    instructions="""TradingView Market Screener MCP - Stocks/Crypto screening tools
+
+🚀 Quick start:
+1. Call `get_help()` for the full usage guide
+2. Call `ai_get_reference()` for markets, fields, and filter references
+
+📊 Common tools:
+- `screen_market(market, limit)` - Market screening (stocks, crypto, etc.)
+- `get_top_gainers(market, limit)` - Top gainers
+- `get_top_losers(market, limit)` - Top losers
+- `search_symbols(query, market)` - 🔍 Search by name (e.g., "Apple", "Tesla")
+- `get_symbol_info(symbol)` - Get detailed symbol info
+
+⚠️ Important notes:
+- `limit` controls result count (default 25, max 500)
+- Results include the `description` field with full names (e.g., "Apple Inc.")
+- `market` examples: america (US stocks), crypto, uk, etc.
+
+📖 Resources (read-only):
+- docs://ai-reference - AI quick reference
+- markets://list - All markets
+- columns://list - Available fields
+""",
 )
 
+DEBUG_MODE = os.getenv("TRADINGVIEW_MCP_DEBUG", "0").lower() in {"1", "true", "yes"}
+
+
+def _safe_json(value: Any) -> Any:
+    try:
+        return json.loads(json.dumps(value, default=str))
+    except Exception:
+        return str(value)
+
+
+def _debug_hint(exc: Exception) -> str | None:
+    message = str(exc).lower()
+    if "market" in message and "invalid" in message:
+        return "Check the market name using the markets://list or docs://screeners resources."
+    if "column" in message and "unknown" in message:
+        return "Check available columns via columns://list or docs://fields."
+    if "http" in message or "status" in message:
+        return "TradingView API may be rate-limiting or blocked. Retry with fewer requests."
+    return None
+
+
+def _build_error_response(tool_name: str, exc: Exception, context: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "tool": tool_name,
+        "error": {"type": exc.__class__.__name__, "message": str(exc)},
+        "context": _safe_json(context),
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+    }
+    hint = _debug_hint(exc)
+    if hint:
+        payload["hint"] = hint
+    if DEBUG_MODE:
+        payload["trace"] = traceback.format_exc()
+    return payload
+
+
+def _error_response(exc: Exception, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    frame = inspect.currentframe()
+    caller = frame.f_back.f_code.co_name if frame and frame.f_back else "unknown"
+    return _build_error_response(caller, exc, context or {})
+
+
+def debug_tool(fn):
+    """Decorator to return structured debug responses on failure."""
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            result = fn(*args, **kwargs)
+            if isinstance(result, dict) and "error" in result:
+                return _build_error_response(
+                    fn.__name__,
+                    Exception(str(result.get("error"))),
+                    {"args": args, "kwargs": kwargs, "note": "error returned by tool"},
+                )
+            if (
+                isinstance(result, list)
+                and len(result) == 1
+                and isinstance(result[0], dict)
+                and "error" in result[0]
+            ):
+                return _build_error_response(
+                    fn.__name__,
+                    Exception(str(result[0].get("error"))),
+                    {"args": args, "kwargs": kwargs, "note": "error returned by tool"},
+                )
+            return result
+        except Exception as exc:  # pragma: no cover - defensive guard
+            context = {"args": args, "kwargs": kwargs}
+            return _build_error_response(fn.__name__, exc, context)
+
+    return wrapper
+
+
+_original_mcp_tool = mcp.tool
+
+
+def _debug_mcp_tool(*args, **kwargs):
+    """Wrap FastMCP tool registration with debug handling."""
+
+    def decorator(fn):
+        return _original_mcp_tool(*args, **kwargs)(debug_tool(fn))
+
+    return decorator
+
+
+mcp.tool = _debug_mcp_tool
+
 
 # =============================================================================
 # MCP Resources
@@ -242,6 +370,623 @@ def list_scanner_presets() -> str:
     return result
 
 
+@mcp.resource("docs://params")
+def docs_params() -> str:
+    """TradingView screener parameter format and schema."""
+    schema = {
+        "markets": ["america"],
+        "columns": ["close", "volume", "market_cap_basic"],
+        "filter": [
+            {"left": "change", "operation": "gt", "right": 2},
+            {"left": "volume", "operation": "greater", "right": 1000000},
+        ],
+        "filter2": {
+            "operator": "and",
+            "operands": [
+                {
+                    "expression": {"left": "type", "operation": "equal", "right": "stock"}
+                },
+                {
+                    "expression": {"left": "is_primary", "operation": "equal", "right": True}
+                },
+            ],
+        },
+        "symbols": {"query": {"types": []}, "tickers": []},
+        "sort": {"sortBy": "market_cap_basic", "sortOrder": "desc"},
+        "range": [0, 50],
+        "options": {"lang": "en"},
+        "ignore_unknown_fields": False,
+        "price_conversion": {"to_symbol": False},
+    }
+
+    format_notes = (
+        "# Screener Params Format\n\n"
+        "## Core fields\n"
+        "- markets: list of market identifiers (e.g., america, crypto, forex)\n"
+        "- columns: list of fields to return\n"
+        "- filter: flat list of expressions\n"
+        "- filter2: nested boolean logic tree (and/or)\n"
+        "- symbols: optional tickers/types filter\n"
+        "- sort: {sortBy, sortOrder}\n"
+        "- range: [offset, limit]\n"
+        "- options: {lang}\n"
+        "- ignore_unknown_fields: boolean\n"
+        "- price_conversion: {to_symbol}\n\n"
+        "## Expression format\n"
+        "{left: <field>, operation: <op>, right: <value>}\n\n"
+        "Common operations: equal, ne, gt, gte, lt, lte, in_range, has, has_none_of\n\n"
+        "## Example schema\n"
+    )
+    return format_notes + json.dumps(schema, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://screeners")
+def docs_screeners() -> str:
+    """Predefined screener presets from docs data (compact overview)."""
+    presets = get_screener_presets()
+    overview = [
+        {"name": p.get("name"), "url": p.get("url"), "has_query": bool(p.get("query"))}
+        for p in presets
+    ]
+    return json.dumps(overview, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://fields")
+def docs_fields() -> str:
+    """Field display names (first 100). Use search_available_fields tool for more."""
+    mapping = get_column_display_names()
+    # Limit output to save tokens
+    limited = dict(list(mapping.items())[:100])
+    result = {
+        "fields": limited,
+        "total": len(mapping),
+        "note": "Showing first 100 fields. Use search_available_fields() tool to search for specific fields.",
+    }
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://markets")
+def docs_markets() -> str:
+    """Markets metadata (compact). Use ai_get_reference tool for categorized list."""
+    markets = get_markets_data()
+    screener_markets = get_screener_markets()
+    return json.dumps(
+        {
+            "markets_count": len(markets) if isinstance(markets, (list, dict)) else 0,
+            "screener_markets": screener_markets,
+            "hint": "Use ai_get_reference() tool for full categorized market list.",
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+
+
+@mcp.tool()
+def get_field_info(field: str) -> dict[str, Any]:
+    """Get display name, type, and related info for a field.
+    
+    Args:
+        field: Field/column name to look up
+        
+    Returns:
+        Field info including display name, type, and variants if available
+    """
+    # Try get_field_summary first (uses common_fields)
+    summary = get_field_summary(field)
+    if summary and summary.get("display_name"):
+        return summary
+    
+    # Fallback to display names mapping
+    mapping = get_column_display_names()
+    display = mapping.get(field)
+    if display:
+        return {"field": field, "display_name": display}
+
+    # Try case-insensitive or partial matches
+    normalized = field.lower()
+    suggestions = [
+        name for name in list(mapping.keys())[:500]
+        if normalized in name.lower() or normalized in str(mapping[name]).lower()
+    ][:10]
+    return {
+        "field": field,
+        "display_name": None,
+        "suggestions": suggestions,
+    }
+
+
+@mcp.tool()
+def get_screener_preset(name: str) -> dict[str, Any]:
+    """Return a full screener preset (query + code) by name."""
+    presets = get_screener_presets()
+    for preset in presets:
+        if preset.get("name", "").lower() == name.lower():
+            return preset
+    return {
+        "error": f"Preset '{name}' not found.",
+        "available": [p.get("name") for p in presets],
+    }
+
+
+@mcp.tool()
+def get_market_metainfo(
+    market: str,
+    limit: int = 50,
+    offset: int = 0,
+    confirm_large: bool = False,
+) -> dict[str, Any]:
+    """Return metainfo (field definitions and allowed values) for a market.
+    
+    Args:
+        market: Market type (stocks, crypto, forex, bond, etc.)
+        limit: Maximum fields to return (default 50, max 500)
+        offset: Starting offset for pagination
+        confirm_large: Set True to allow returning more than 100 items
+        
+    Returns:
+        Paginated metainfo with field definitions
+    """
+    limit = min(limit, 500)  # Hard cap
+    
+    try:
+        metainfo = load_metainfo(market)
+        
+        # Paginate if it's a list or large dict
+        if isinstance(metainfo, list):
+            return paginate_data(metainfo, offset, limit, confirm_large)
+        elif isinstance(metainfo, dict):
+            # Return summary if too large
+            total_fields = len(metainfo.get("fields", []))
+            if total_fields > MAX_ITEMS_DEFAULT and not confirm_large:
+                return {
+                    "market": market,
+                    "total_fields": total_fields,
+                    "warning": f"⚠️ Large data ({total_fields} fields). Use limit/offset to paginate or set confirm_large=True.",
+                    "sample_fields": list(metainfo.get("fields", {}).keys())[:20] if isinstance(metainfo.get("fields"), dict) else None,
+                }
+            return {"market": market, "metainfo": metainfo}
+        return {"market": market, "metainfo": metainfo}
+    except FileNotFoundError:
+        return {
+            "error": f"Metainfo for '{market}' not found.",
+            "available_markets": ["stocks", "crypto", "forex", "bond", "bonds", "cfd", "futures", "options", "coin", "economics2"],
+            "hint": "Use one of the available markets listed above.",
+        }
+
+
+# =============================================================================
+# AI-Friendly Tools - Quick Reference and Search
+# =============================================================================
+
+
+@mcp.resource("docs://ai-reference")
+def docs_ai_reference() -> str:
+    """AI quick reference guide with common patterns, markets, and filters."""
+    ref = get_ai_quick_reference()
+    return json.dumps(ref, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://code-examples")  
+def docs_code_examples() -> str:
+    """Python code examples for common screener queries."""
+    examples = get_screener_code_examples()
+    return json.dumps(examples, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def ai_get_reference() -> dict[str, Any]:
+    """Get AI-friendly quick reference for this MCP.
+    
+    Returns a compact guide with:
+    - Available markets by category
+    - Common columns by type  
+    - Filter operations
+    - Common filter patterns
+    - Timeframes
+    
+    This is the recommended starting point for AI agents to understand how to use this MCP.
+    """
+    return get_ai_quick_reference()
+
+
+@mcp.tool()
+def search_available_fields(
+    query: str,
+    market: str = "stocks",
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Search for fields/columns by name or description.
+    
+    Args:
+        query: Search term (e.g., "volume", "RSI", "market cap")
+        market: Market type to search in (stocks, crypto, forex, etc.)
+        limit: Maximum results (default 20, max 50)
+        
+    Returns:
+        Matching fields with their display names and types
+    """
+    limit = min(limit, 50)
+    results = search_fields(query, market, limit)
+    
+    return {
+        "query": query,
+        "market": market,
+        "count": len(results),
+        "fields": results,
+        "hint": "Use the 'name' field as the column name in queries." if results else "No matches found. Try a different search term.",
+    }
+
+
+@mcp.tool()
+def get_code_example(screener_name: str) -> dict[str, Any]:
+    """Get Python code example for a specific screener type.
+    
+    Args:
+        screener_name: Screener name (e.g., "Stocks (legacy)", "Crypto", "Forex", "ETFs", "Bonds")
+        
+    Returns:
+        Python code example for building that screener query
+    """
+    examples = get_screener_code_examples()
+    
+    # Try exact match first
+    if screener_name in examples:
+        return {
+            "name": screener_name,
+            "code": examples[screener_name],
+        }
+    
+    # Try case-insensitive match
+    for name, code in examples.items():
+        if name.lower() == screener_name.lower():
+            return {"name": name, "code": code}
+    
+    # Return available options
+    return {
+        "error": f"Example '{screener_name}' not found.",
+        "available": list(examples.keys()),
+        "hint": "Use one of the available screener names listed above.",
+    }
+
+
+@mcp.tool()
+def list_fields_for_market(
+    market: str = "stocks",
+    category: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    confirm_large: bool = False,
+) -> dict[str, Any]:
+    """List available fields for a specific market with pagination.
+    
+    Args:
+        market: Market type (stocks, crypto, forex, coin, bond, cfd, futures, options)
+        category: Optional filter by field type (price, volume, fundamental, technical)
+        limit: Maximum results (default 50, max 200)
+        offset: Starting offset for pagination
+        confirm_large: Set True to allow more than 100 results
+        
+    Returns:
+        Paginated list of field definitions
+    """
+    limit = min(limit, 200)
+    
+    fields = get_fields_by_market(market)
+    
+    if not fields:
+        return {
+            "error": f"No fields found for market '{market}'.",
+            "available_markets": ["stocks", "crypto", "forex", "coin", "bond", "bonds", "cfd", "futures", "options", "economics2", "ireland"],
+        }
+    
+    # Filter by category if specified
+    if category and isinstance(fields, list):
+        category_lower = category.lower()
+        fields = [f for f in fields if category_lower in f.get("type", "").lower()]
+    
+    return paginate_data(fields, offset, limit, confirm_large)
+
+
+@mcp.tool()
+def get_common_fields_summary(
+    category: str | None = None,
+    limit: int = 30,
+) -> dict[str, Any]:
+    """Get summary of commonly used fields across all markets.
+    
+    Args:
+        category: Optional filter (price, volume, fundamental, technical, rating)
+        limit: Maximum fields to return (default 30)
+        
+    Returns:
+        Dict with field names, display names, and types
+    """
+    ref = get_ai_quick_reference()
+    common_cols = ref.get("common_columns", {})
+    
+    if category:
+        category_lower = category.lower()
+        if category_lower in common_cols:
+            return {
+                "category": category,
+                "fields": common_cols[category_lower],
+            }
+        return {
+            "error": f"Category '{category}' not found.",
+            "available_categories": list(common_cols.keys()),
+        }
+    
+    # Return all categories with limited fields
+    result = {}
+    for cat, fields in common_cols.items():
+        result[cat] = fields[:limit] if len(fields) > limit else fields
+    
+    return {
+        "categories": result,
+        "total_categories": len(common_cols),
+        "hint": "Use category parameter to filter by type.",
+    }
+
+
+# =============================================================================
+# Help and Discovery Tools - Help AI understand usage
+# =============================================================================
+
+
+@mcp.tool()
+def get_help(topic: str | None = None) -> dict[str, Any]:
+    """📖 Usage guide - required reading for AI!
+    
+    Args:
+        topic: Optional topic: 'markets', 'columns', 'filters', 'examples', 'tools'
+               If omitted, returns the full guide
+    
+    Returns:
+        Usage guide and examples
+    """
+    guide = {
+        "overview": {
+            "description": "TradingView MCP is a market screener for stocks and crypto",
+            "key_points": [
+                "All results include the 'description' field (full name like 'Apple Inc.')",
+                "Use the limit parameter to control output size (default 25, max 500)",
+                "Symbols are returned in ticker format: 'EXCHANGE:SYMBOL' (e.g., 'NASDAQ:AAPL')",
+            ],
+        },
+        "quick_start": {
+            "step_1": "Call get_top_gainers('america', 10) for top 10 US stock gainers",
+            "step_2": "Call search_symbols('apple', 'america') to find symbols by name",
+            "step_3": "Call get_symbol_info('NASDAQ:AAPL') for Apple details",
+        },
+        "markets": {
+            "stocks": ["america (US)", "uk (UK)", "germany (DE)", "japan (JP)", "china (CN)", "hongkong (HK)", "taiwan (TW)"],
+            "crypto": ["crypto (pairs)", "coin (coins)",],
+            "others": ["forex", "futures", "bonds"],
+        },
+        "common_tools": {
+            "screen_market": "Custom screening - screen_market(market='america', limit=50, sort_by='volume')",
+            "get_top_gainers": "Top gainers - get_top_gainers(market='crypto', limit=25)",
+            "get_top_losers": "Top losers - get_top_losers(market='america', limit=25)",
+            "search_symbols": "🔍 Name search - search_symbols(query='tesla', market='america')",
+            "get_symbol_info": "Symbol info - get_symbol_info(symbol='NASDAQ:AAPL')",
+            "get_technical_analysis": "Technical analysis - get_technical_analysis(symbol='NASDAQ:AAPL')",
+        },
+        "important_columns": {
+            "name": "Ticker (e.g., 'NASDAQ:AAPL')",
+            "description": "Full name (e.g., 'Apple Inc.')",
+            "close": "Close/last price",
+            "change": "Change (%)",
+            "volume": "Volume",
+            "market_cap_basic": "Market cap",
+        },
+        "filters_example": {
+            "description": "Use filters to apply conditions",
+            "example": [
+                {"column": "change", "operation": "gt", "value": 5},
+                {"column": "volume", "operation": "gt", "value": 1000000},
+            ],
+            "operations": ["gt (>)", "gte (>=)", "lt (<)", "lte (<=)", "eq (=)", "neq (!=)", "between", "isin"],
+        },
+    }
+    
+    if topic:
+        topic_lower = topic.lower()
+        if topic_lower in guide:
+            return {"topic": topic, "content": guide[topic_lower]}
+        if topic_lower == "tools":
+            return {"topic": "tools", "content": guide["common_tools"]}
+        if topic_lower == "examples":
+            return {"topic": "examples", "content": guide["quick_start"]}
+        return {
+            "error": f"Topic '{topic}' not found",
+            "available_topics": list(guide.keys()) + ["tools", "examples"],
+        }
+    
+    return guide
+
+
+@mcp.tool()
+def search_symbols(
+    query: str,
+    market: str = "america",
+    limit: int = 25,
+) -> dict[str, Any]:
+    """🔍 Search symbols by name (fuzzy search)
+    
+    Supports company names or tickers, e.g., "Apple", "Tesla", "Microsoft".
+    
+    Args:
+        query: Search keyword (company name or ticker)
+        market: Market (america, crypto, uk, etc.)
+        limit: Max results (default 25, max 100)
+    
+    Returns:
+        Matching symbols with full names
+        
+    Examples:
+        search_symbols("apple", "america") -> Apple Inc., Applebee's, etc.
+        search_symbols("BTC", "crypto") -> BTC pairs
+    """
+    market = sanitize_market(market)
+    limit = max(1, min(limit, 100))
+    
+    # Search fields: name (ticker) and description (full name)
+    cols = ["name", "description", "close", "change", "volume", "market_cap_basic", "type", "exchange"]
+    
+    try:
+        # Use TradingView text search
+        # Search description (company name)
+        query_obj = (
+            Query()
+            .set_markets(market)
+            .select(*cols)
+            .where(Column("description").like(query))
+            .order_by("market_cap_basic", ascending=False)
+            .limit(limit)
+        )
+        
+        total, df = query_obj.get_scanner_data()
+        results = df.to_dict("records")
+        
+        # If nothing found, try searching the name (ticker) field
+        if not results:
+            query_obj2 = (
+                Query()
+                .set_markets(market)
+                .select(*cols)
+                .where(Column("name").like(query))
+                .order_by("market_cap_basic", ascending=False)
+                .limit(limit)
+            )
+            total, df = query_obj2.get_scanner_data()
+            results = df.to_dict("records")
+        
+        return {
+            "query": query,
+            "market": market,
+            "total_found": total,
+            "returned": len(results),
+            "results": results,
+            "hint": "Use 'name' field as symbol for other tools (e.g., get_symbol_info)" if results else "No matches found. Try different keywords.",
+        }
+    except Exception as e:
+        # If LIKE isn't supported, use fallback
+        return _search_symbols_fallback(query, market, limit, cols, str(e))
+
+
+def _search_symbols_fallback(
+    query: str, market: str, limit: int, cols: list[str], original_error: str
+) -> dict[str, Any]:
+    """Fallback search when LIKE is not supported."""
+    try:
+        # Fetch more data and filter locally
+        query_obj = (
+            Query()
+            .set_markets(market)
+            .select(*cols)
+            .order_by("market_cap_basic", ascending=False)
+            .limit(500)  # Fetch top 500
+        )
+        
+        total, df = query_obj.get_scanner_data()
+        
+        # Local filter
+        query_lower = query.lower()
+        filtered = df[
+            df["name"].str.lower().str.contains(query_lower, na=False) |
+            df["description"].str.lower().str.contains(query_lower, na=False)
+        ].head(limit)
+        
+        results = filtered.to_dict("records")
+        
+        return {
+            "query": query,
+            "market": market,
+            "total_found": len(results),
+            "returned": len(results),
+            "results": results,
+            "note": "Results from local filtering of top 500 by market cap",
+            "hint": "Use 'name' field as symbol for other tools" if results else "No matches found",
+        }
+    except Exception as e:
+        return {
+            "error": f"Search failed: {str(e)}",
+            "original_error": original_error,
+            "hint": "Try using screen_market with specific filters instead",
+        }
+
+
+@mcp.tool()
+def get_symbol_info(
+    symbol: str,
+    include_technical: bool = False,
+) -> dict[str, Any]:
+    """Get detailed information for a symbol.
+    
+    Args:
+        symbol: Ticker in 'EXCHANGE:SYMBOL' format (e.g., 'NASDAQ:AAPL')
+                or just a ticker (e.g., 'AAPL', auto-search)
+        include_technical: Whether to include technical indicators
+    
+    Returns:
+        Detailed symbol info including name, price, market cap, etc.
+        
+    Examples:
+        get_symbol_info("NASDAQ:AAPL") -> Apple Inc. details
+        get_symbol_info("AAPL") -> auto-search
+    """
+    cols = [
+        "name", "description", "close", "open", "high", "low", 
+        "change", "change_abs", "volume", "market_cap_basic",
+        "price_earnings_ttm", "earnings_per_share_basic_ttm",
+        "dividend_yield_recent", "sector", "industry", "exchange", "type",
+    ]
+    
+    if include_technical:
+        cols.extend([
+            "RSI", "RSI7", "MACD.macd", "MACD.signal",
+            "SMA20", "SMA50", "SMA200", "EMA20", "EMA50", "EMA200",
+            "BB.upper", "BB.lower", "ATR", "ADX",
+            "Recommend.All", "Recommend.MA", "Recommend.Other",
+        ])
+    
+    try:
+        # Determine market
+        if ":" in symbol:
+            exchange, ticker = symbol.split(":", 1)
+            market = EXCHANGE_SCREENER.get(exchange.lower(), "america")
+        else:
+            ticker = symbol
+            market = "america"
+        
+        query = (
+            Query()
+            .set_markets(market)
+            .select(*cols)
+            .where(Column("name").isin([symbol, ticker, symbol.upper(), ticker.upper()]))
+            .limit(5)
+        )
+        
+        total, df = query.get_scanner_data()
+        
+        if df.empty:
+            # Fallback to search
+            return search_symbols(ticker, market, 5)
+        
+        results = df.to_dict("records")
+        
+        if len(results) == 1:
+            return {"symbol": symbol, "found": True, "data": results[0]}
+        else:
+            return {"symbol": symbol, "found": True, "matches": results}
+            
+    except Exception as e:
+        return {
+            "error": f"Failed to get symbol info: {str(e)}",
+            "hint": "Try using search_symbols to find the correct symbol format",
+        }
+
+
 # =============================================================================
 # MCP Tools - Basic Screening
 # =============================================================================
@@ -253,27 +998,33 @@ def screen_market(
     columns: Optional[list[str]] = None,
     sort_by: str = "volume",
     ascending: bool = False,
-    limit: int = 50,
+    limit: int = 25,
     filters: Optional[list[dict[str, Any]]] = None,
-) -> list[dict[str, Any]]:
-    """
-    Execute a custom market screening query.
+) -> dict[str, Any]:
+    """Run a custom market screening query.
+    
+    ⚠️ Note: Default returns 25 rows. Increase `limit` for more.
 
     Args:
-        market: Market to screen (america, crypto, uk, etc.)
-        columns: Columns to return (default: name, close, volume, market_cap_basic)
-        sort_by: Column to sort by
-        ascending: Sort order (True=ascending, False=descending)
-        limit: Maximum results (1-500)
-        filters: List of filter conditions as dicts with keys: column, operation, value
-                 Operations: gt, gte, lt, lte, eq, neq, between, isin
+        market: Market (america=US stocks, crypto, uk, etc.)
+        columns: Columns to return (default includes name, description, close, change, volume, market_cap)
+        sort_by: Sort column
+        ascending: Sort order (True=asc, False=desc)
+        limit: Max results (1-500, default 25)
+        filters: Filter list, e.g. [{"column": "change", "operation": "gt", "value": 5}]
+                 Supported ops: gt, gte, lt, lte, eq, neq, between, isin
 
     Returns:
-        List of matching symbols with requested data
+        Dict with total_count, returned, data.
+        Each row includes description (full name like "Apple Inc.").
     """
     market = sanitize_market(market)
     limit = max(1, min(limit, 500))
+    
+    # Ensure description is always included
     cols = columns or DEFAULT_COLUMNS
+    if "description" not in cols:
+        cols = ["description"] + list(cols)
 
     query = Query().set_markets(market).select(*cols).order_by(sort_by, ascending=ascending).limit(limit)
 
@@ -309,27 +1060,38 @@ def screen_market(
         total_count, df = query.get_scanner_data()
         results = df.to_dict("records")
 
-        return [{"total_count": total_count, "returned": len(results), "data": results}]
+        return {
+            "total_count": total_count,
+            "returned": len(results),
+            "market": market,
+            "data": results,
+        }
     except Exception as e:
-        return [{"error": str(e)}]
+        return {"error": str(e), "market": market}
 
 
 @mcp.tool()
-def get_top_gainers(market: str = "america", limit: int = 25) -> list[dict[str, Any]]:
-    """
-    Get top gaining assets in a market.
+def get_top_gainers(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get top gainers for a market.
+    
+    ⚠️ Note: Default returns 25 rows. Increase `limit` for more.
 
     Args:
-        market: Market to scan (america, crypto, uk, etc.)
-        limit: Number of results (1-100)
+        market: Market (america=US stocks, crypto, uk, etc.)
+        limit: Result count (1-100, default 25)
 
     Returns:
-        List of top gainers with price and change data
+        Top gainers with description (full name).
+        
+    Example:
+        get_top_gainers("america", 10) -> Top 10 US gainers
+        get_top_gainers("crypto", 25) -> Top 25 crypto gainers
     """
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
-    cols = ["name", "close", "volume", "change", "change_abs", "market_cap_basic"]
+    # Ensure description is included
+    cols = ["name", "description", "close", "change", "change_abs", "volume", "market_cap_basic"]
 
     query = (
         Query()
@@ -342,27 +1104,39 @@ def get_top_gainers(market: str = "america", limit: int = 25) -> list[dict[str,
 
     try:
         total, df = query.get_scanner_data()
-        return df.to_dict("records")
+        results = df.to_dict("records")
+        return {
+            "market": market,
+            "type": "top_gainers",
+            "total_found": total,
+            "returned": len(results),
+            "data": results,
+        }
     except Exception as e:
-        return [{"error": str(e)}]
+        return {"error": str(e), "market": market}
 
 
 @mcp.tool()
-def get_top_losers(market: str = "america", limit: int = 25) -> list[dict[str, Any]]:
-    """
-    Get top losing assets in a market.
+def get_top_losers(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get top losers for a market.
+    
+    ⚠️ Note: Default returns 25 rows. Increase `limit` for more.
 
     Args:
-        market: Market to scan (america, crypto, uk, etc.)
-        limit: Number of results (1-100)
+        market: Market (america=US stocks, crypto, uk, etc.)
+        limit: Result count (1-100, default 25)
 
     Returns:
-        List of top losers with price and change data
+        Top losers with description (full name).
+        
+    Example:
+        get_top_losers("america", 10) -> Top 10 US losers
     """
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
-    cols = ["name", "close", "volume", "change", "change_abs", "market_cap_basic"]
+    # Ensure description is included
+    cols = ["name", "description", "close", "change", "change_abs", "volume", "market_cap_basic"]
 
     query = (
         Query()
@@ -375,47 +1149,61 @@ def get_top_losers(market: str = "america", limit: int = 25) -> list[dict[str, A
 
     try:
         total, df = query.get_scanner_data()
-        return df.to_dict("records")
+        results = df.to_dict("records")
+        return {
+            "market": market,
+            "type": "top_losers",
+            "total_found": total,
+            "returned": len(results),
+            "data": results,
+        }
     except Exception as e:
-        return [{"error": str(e)}]
+        return {"error": str(e), "market": market}
 
 
 @mcp.tool()
-def get_most_active(market: str = "america", limit: int = 25) -> list[dict[str, Any]]:
-    """
-    Get most actively traded assets by volume.
+def get_most_active(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get most active by volume.
+    
+    ⚠️ Note: Default returns 25 rows.
 
     Args:
-        market: Market to scan
-        limit: Number of results (1-100)
+        market: Market
+        limit: Result count (1-100)
 
     Returns:
-        List of most active assets by volume
+        Most active list with description (full name)
     """
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
-    cols = ["name", "close", "volume", "change", "relative_volume_10d_calc", "market_cap_basic"]
+    cols = ["name", "description", "close", "change", "volume", "relative_volume_10d_calc", "market_cap_basic"]
 
     query = Query().set_markets(market).select(*cols).order_by("volume", ascending=False).limit(limit)
 
     try:
         total, df = query.get_scanner_data()
-        return df.to_dict("records")
+        results = df.to_dict("records")
+        return {
+            "market": market,
+            "type": "most_active",
+            "total_found": total,
+            "returned": len(results),
+            "data": results,
+        }
     except Exception as e:
-        return [{"error": str(e)}]
+        return {"error": str(e), "market": market}
 
 
 @mcp.tool()
 def get_premarket_movers(
     scan_type: str = "gainers", limit: int = 25
-) -> list[dict[str, Any]]:
-    """
-    Get pre-market movers (US market only).
+) -> dict[str, Any]:
+    """Get pre-market movers (US only).
 
     Args:
-        scan_type: Type of scan - 'gainers', 'losers', 'most_active', 'gappers'
-        limit: Number of results (1-100)
+        scan_type: 'gainers', 'losers', 'most_active', 'gappers'
+        limit: Result count (1-100)
 
     Returns:
         List of pre-market movers