tradingview-mcp 1.1.0__tar.gz → 26.0.0__tar.gz

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/LICENSE

@@ -1,7 +1,5 @@
 MIT License
 
-Copyright (c) 2022 Shneor Elmaleh
-Copyright (c) 2025 Ahmet Taner Atila
 Copyright (c) 2026 Henrik (k73a)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: tradingview-mcp
-Version: 1.1.0
+Version: 26.0.0
 Summary: A comprehensive MCP server for TradingView market screening with integrated screener functionality
-Project-URL: Homepage, https://github.com/yourusername/tradingview-mcp
-Project-URL: Documentation, https://github.com/yourusername/tradingview-mcp#readme
-Project-URL: Repository, https://github.com/yourusername/tradingview-mcp
-Project-URL: Issues, https://github.com/yourusername/tradingview-mcp/issues
-Project-URL: Changelog, https://github.com/yourusername/tradingview-mcp/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/k73a/tradingview-mcp
+Project-URL: Documentation, https://github.com/k73a/tradingview-mcp#readme
+Project-URL: Repository, https://github.com/k73a/tradingview-mcp
+Project-URL: Issues, https://github.com/k73a/tradingview-mcp/issues
+Project-URL: Changelog, https://github.com/k73a/tradingview-mcp/blob/main/CHANGELOG.md
 Author: TradingView MCP Team
 License: MIT
 License-File: LICENSE
@@ -39,7 +39,6 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/tradingview-mcp.svg)](https://badge.fury.io/py/tradingview-mcp)
 [![Python](https://img.shields.io/pypi/pyversions/tradingview-mcp.svg)](https://pypi.org/project/tradingview-mcp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://github.com/yourusername/tradingview-mcp/workflows/Test/badge.svg)](https://github.com/yourusername/tradingview-mcp/actions)
 
 A comprehensive Model Context Protocol (MCP) server for TradingView market screening with fully integrated screener functionality. This server provides powerful tools for cryptocurrency and stock market analysis directly through the MCP interface.
 
@@ -58,6 +57,26 @@ Use `uvx` to run directly without installing:
 }
 ```
 
+## 🤖 For AI Agents
+
+**📖 Read [AI.md](AI.md) for the complete guide!** You can copy the entire AI.md file to understand all capabilities.
+
+**Quick Start:**
+1. Call `get_help()` to understand how to use this MCP
+2. Call `ai_get_reference()` for markets, columns, and filter references
+
+Key points:
+- All results include `description` field with full names (e.g., "Apple Inc." not just "AAPL")
+- Use `limit` parameter to control result count (default: 25)
+- Use `search_symbols("apple", "america")` to search by company name
+
+```
+# Quick examples:
+get_top_gainers("america", 10)       # Top 10 US stock gainers
+search_symbols("tesla", "america")    # Search for Tesla
+get_symbol_info("NASDAQ:AAPL")       # Apple Inc. details
+```
+
 ## Features
 
 ### Core Screener Functionality
@@ -65,14 +84,21 @@ Use `uvx` to run directly without installing:
 - **Multi-Market Support**: 76+ markets including crypto, stocks, forex, futures, and bonds
 - **SQL-like Query Interface**: Build complex queries with filtering, sorting, and pagination
 - **250+ Technical Indicators**: Access a comprehensive set of technical analysis columns
-- **AI-Friendly Design**: Token-saving output limits, paginated responses, and quick reference tools
+- **AI-Friendly Design**: Includes `description` (full name), token-saving limits, and help tools
 
 ### MCP Tools
 
+#### 🔍 Discovery & Help Tools (AI Start Here!)
+- `get_help(topic)`: **📖 Required reading!** Get usage guide and examples
+- `search_symbols(query, market)`: 🔍 Search by company name (e.g., "Apple", "Tesla")
+- `get_symbol_info(symbol)`: Get detailed symbol information
+- `ai_get_reference()`: AI quick reference guide
+
 #### Screening Tools
 - `screen_market`: Execute custom market screening queries
-- `get_top_gainers`: Find top gaining assets in any market
-- `get_top_losers`: Find top losing assets in any market
+- `get_top_gainers`: Find top gaining assets (includes full company names)
+- `get_top_losers`: Find top losing assets (includes full company names)
+- `get_most_active`: Most traded by volume
 - `get_premarket_movers`: Pre-market gainers, losers, and most active
 - `get_postmarket_movers`: Post-market activity analysis
 - `get_technical_analysis`: Detailed technical analysis for specific symbols
@@ -84,7 +110,6 @@ Use `uvx` to run directly without installing:
 - `advanced_query`: Execute advanced queries with AND/OR logic
 
 #### AI-Friendly Reference Tools
-- `ai_get_reference`: **Start here!** Get quick reference guide with markets, columns, filters
 - `search_available_fields`: Search for fields/columns by name or description
 - `get_field_info`: Get display name and type for a specific field
 - `get_code_example`: Get Python code examples for screener types
@@ -131,7 +156,7 @@ pip install tradingview-mcp
 
 ### From Source
 ```bash
-git clone https://github.com/your-repo/tradingview-mcp.git
+git clone https://github.com/k73a/tradingview-mcp.git
 cd tradingview-mcp
 uv sync
 ```
@@ -239,7 +264,7 @@ See `columns://list` resource for the complete list.
 
 ### Setup Development Environment
 ```bash
-git clone https://github.com/yourusername/tradingview-mcp.git
+git clone https://github.com/k73a/tradingview-mcp.git
 cd tradingview-mcp
 uv sync --all-extras
 ```

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/README.md

@@ -3,7 +3,6 @@
 [![PyPI version](https://badge.fury.io/py/tradingview-mcp.svg)](https://badge.fury.io/py/tradingview-mcp)
 [![Python](https://img.shields.io/pypi/pyversions/tradingview-mcp.svg)](https://pypi.org/project/tradingview-mcp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://github.com/yourusername/tradingview-mcp/workflows/Test/badge.svg)](https://github.com/yourusername/tradingview-mcp/actions)
 
 A comprehensive Model Context Protocol (MCP) server for TradingView market screening with fully integrated screener functionality. This server provides powerful tools for cryptocurrency and stock market analysis directly through the MCP interface.
 
@@ -22,6 +21,26 @@ Use `uvx` to run directly without installing:
 }
 ```
 
+## 🤖 For AI Agents
+
+**📖 Read [AI.md](AI.md) for the complete guide!** You can copy the entire AI.md file to understand all capabilities.
+
+**Quick Start:**
+1. Call `get_help()` to understand how to use this MCP
+2. Call `ai_get_reference()` for markets, columns, and filter references
+
+Key points:
+- All results include `description` field with full names (e.g., "Apple Inc." not just "AAPL")
+- Use `limit` parameter to control result count (default: 25)
+- Use `search_symbols("apple", "america")` to search by company name
+
+```
+# Quick examples:
+get_top_gainers("america", 10)       # Top 10 US stock gainers
+search_symbols("tesla", "america")    # Search for Tesla
+get_symbol_info("NASDAQ:AAPL")       # Apple Inc. details
+```
+
 ## Features
 
 ### Core Screener Functionality
@@ -29,14 +48,21 @@ Use `uvx` to run directly without installing:
 - **Multi-Market Support**: 76+ markets including crypto, stocks, forex, futures, and bonds
 - **SQL-like Query Interface**: Build complex queries with filtering, sorting, and pagination
 - **250+ Technical Indicators**: Access a comprehensive set of technical analysis columns
-- **AI-Friendly Design**: Token-saving output limits, paginated responses, and quick reference tools
+- **AI-Friendly Design**: Includes `description` (full name), token-saving limits, and help tools
 
 ### MCP Tools
 
+#### 🔍 Discovery & Help Tools (AI Start Here!)
+- `get_help(topic)`: **📖 Required reading!** Get usage guide and examples
+- `search_symbols(query, market)`: 🔍 Search by company name (e.g., "Apple", "Tesla")
+- `get_symbol_info(symbol)`: Get detailed symbol information
+- `ai_get_reference()`: AI quick reference guide
+
 #### Screening Tools
 - `screen_market`: Execute custom market screening queries
-- `get_top_gainers`: Find top gaining assets in any market
-- `get_top_losers`: Find top losing assets in any market
+- `get_top_gainers`: Find top gaining assets (includes full company names)
+- `get_top_losers`: Find top losing assets (includes full company names)
+- `get_most_active`: Most traded by volume
 - `get_premarket_movers`: Pre-market gainers, losers, and most active
 - `get_postmarket_movers`: Post-market activity analysis
 - `get_technical_analysis`: Detailed technical analysis for specific symbols
@@ -48,7 +74,6 @@ Use `uvx` to run directly without installing:
 - `advanced_query`: Execute advanced queries with AND/OR logic
 
 #### AI-Friendly Reference Tools
-- `ai_get_reference`: **Start here!** Get quick reference guide with markets, columns, filters
 - `search_available_fields`: Search for fields/columns by name or description
 - `get_field_info`: Get display name and type for a specific field
 - `get_code_example`: Get Python code examples for screener types
@@ -95,7 +120,7 @@ pip install tradingview-mcp
 
 ### From Source
 ```bash
-git clone https://github.com/your-repo/tradingview-mcp.git
+git clone https://github.com/k73a/tradingview-mcp.git
 cd tradingview-mcp
 uv sync
 ```
@@ -203,7 +228,7 @@ See `columns://list` resource for the complete list.
 
 ### Setup Development Environment
 ```bash
-git clone https://github.com/yourusername/tradingview-mcp.git
+git clone https://github.com/k73a/tradingview-mcp.git
 cd tradingview-mcp
 uv sync --all-extras
 ```

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tradingview-mcp"
-version = "1.1.0"
+version = "26.0.0"
 description = "A comprehensive MCP server for TradingView market screening with integrated screener functionality"
 readme = "README.md"
 license = { text = "MIT" }
@@ -28,11 +28,11 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/yourusername/tradingview-mcp"
-Documentation = "https://github.com/yourusername/tradingview-mcp#readme"
-Repository = "https://github.com/yourusername/tradingview-mcp"
-Issues = "https://github.com/yourusername/tradingview-mcp/issues"
-Changelog = "https://github.com/yourusername/tradingview-mcp/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/k73a/tradingview-mcp"
+Documentation = "https://github.com/k73a/tradingview-mcp#readme"
+Repository = "https://github.com/k73a/tradingview-mcp"
+Issues = "https://github.com/k73a/tradingview-mcp/issues"
+Changelog = "https://github.com/k73a/tradingview-mcp/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = [

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/src/tradingview_mcp/constants.py

@@ -393,16 +393,18 @@ COLUMNS = {
 }
 
 # Default columns for different query types
-DEFAULT_COLUMNS = ["name", "close", "volume", "market_cap_basic"]
+# Always include 'description' for full name (e.g., "Apple Inc." instead of just "AAPL")
+DEFAULT_COLUMNS = ["name", "description", "close", "change", "volume", "market_cap_basic"]
 
-PREMARKET_COLUMNS = ["name", "close", "volume", "premarket_change", "premarket_change_abs", "premarket_volume"]
+PREMARKET_COLUMNS = ["name", "description", "close", "volume", "premarket_change", "premarket_change_abs", "premarket_volume"]
 
-POSTMARKET_COLUMNS = ["name", "close", "volume", "postmarket_change", "postmarket_change_abs", "postmarket_volume"]
+POSTMARKET_COLUMNS = ["name", "description", "close", "volume", "postmarket_change", "postmarket_change_abs", "postmarket_volume"]
 
-CRYPTO_COLUMNS = ["name", "close", "volume", "change", "market_cap_basic", "24h_vol|5"]
+CRYPTO_COLUMNS = ["name", "description", "close", "change", "volume", "market_cap_basic", "24h_vol|5"]
 
 TECHNICAL_COLUMNS = [
     "name",
+    "description",
     "close",
     "volume",
     "change",

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/src/tradingview_mcp/scanner.py

@@ -10,7 +10,8 @@ from tradingview_mcp.column import Column
 from tradingview_mcp.query import Query
 
 
-DEFAULT_COLUMNS = ["name", "close", "volume", "market_cap_basic"]
+# Always include 'description' for full name (e.g., "Apple Inc." instead of just "AAPL")
+DEFAULT_COLUMNS = ["name", "description", "close", "change", "volume", "market_cap_basic"]
 
 
 class Scanner:

{tradingview_mcp-1.1.0 → tradingview_mcp-26.0.0}/src/tradingview_mcp/server.py

@@ -63,13 +63,29 @@ from tradingview_mcp.docs_data import (
 # 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. "
-        "Docs resources: docs://params, docs://screeners, docs://fields, docs://markets. "
-        "Set TRADINGVIEW_MCP_DEBUG=1 for detailed debug responses on errors."
-    ),
+    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"}
@@ -712,6 +728,265 @@ def get_common_fields_summary(
     }
 
 
+# =============================================================================
+# 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
 # =============================================================================
@@ -723,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)
 
@@ -779,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()
@@ -812,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()
@@ -845,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