tradingview-mcp 26.0.0__py3-none-any.whl → 26.2.0__py3-none-any.whl

tradingview_mcp/server.py

@@ -52,39 +52,55 @@ from tradingview_mcp.docs_data import (
     get_screener_code_examples,
     get_screener_markets,
     get_screener_presets,
+    get_stock_screeners,
+    get_stock_screeners_failed,
+    get_stock_screener_presets,
+    get_valid_fields_for_market,
+    suggest_fields_for_error,
     paginate_data,
     search_fields,
     get_field_summary,
     estimate_tokens,
     truncate_for_tokens,
     MAX_ITEMS_DEFAULT,
+    # New fast lookup functions
+    get_quick_reference,
+    lookup_field,
+    get_filter_format,
+    get_market_fields_summary,
+    get_screener_preset_names,
+    get_code_example_names,
+    validate_market,
+    build_error_with_format,
+    ALL_MARKETS,
+    FIELD_CATEGORIES,
+    FILTER_OPS,
 )
 
 # Initialize MCP Server
 mcp = FastMCP(
     name="TradingView Screener MCP",
-    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
+    instructions="""TradingView Market Screener MCP
+
+Quick start:
+1. Call `get_help()` for usage
+2. Call `ai_get_reference()` for markets and fields
+
+Common tools:
+- `screen_market(market, limit)`
+- `get_top_gainers(market, limit)`
+- `get_top_losers(market, limit)`
+- `search_symbols(query, market)`
+- `get_symbol_info(symbol)`
+
+Notes:
+- `limit` default 25, max 500
+- Results include `description`
+
+Resources:
+- docs://ai-reference
+- markets://list
+- columns://list
 """,
 )
 
@@ -98,14 +114,34 @@ def _safe_json(value: Any) -> Any:
         return str(value)
 
 
-def _debug_hint(exc: Exception) -> str | None:
+def _debug_hint(exc: Exception, context: dict[str, Any] | None = None) -> dict[str, Any] | str | None:
+    """Generate helpful hints based on error type."""
     message = str(exc).lower()
+    
+    # Extract market from context if available
+    market = None
+    if context:
+        market = context.get("kwargs", {}).get("market") or context.get("market")
+    
     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 "column" in message or "unknown" in message or "field" in message:
+        # Return structured field suggestions
+        market_type = market or "stocks"
+        if market_type in ["crypto", "coin"]:
+            market_type = market_type
+        elif market_type in ["forex"]:
+            market_type = "forex"
+        else:
+            # Default to stocks for field suggestions
+            market_type = "stocks"
+        
+        return suggest_fields_for_error(str(exc), market_type)
+    
     if "http" in message or "status" in message:
         return "TradingView API may be rate-limiting or blocked. Retry with fewer requests."
+    
     return None
 
 
@@ -117,9 +153,14 @@ def _build_error_response(tool_name: str, exc: Exception, context: dict[str, Any
         "context": _safe_json(context),
         "timestamp": datetime.utcnow().isoformat() + "Z",
     }
-    hint = _debug_hint(exc)
+    
+    hint = _debug_hint(exc, context)
     if hint:
-        payload["hint"] = hint
+        if isinstance(hint, dict):
+            payload["field_suggestions"] = hint
+        else:
+            payload["hint"] = hint
+    
     if DEBUG_MODE:
         payload["trace"] = traceback.format_exc()
     return payload
@@ -179,320 +220,107 @@ mcp.tool = _debug_mcp_tool
 
 
 # =============================================================================
-# MCP Resources
+# MCP Resources - Compact summaries only, use tools for full data
 # =============================================================================
 
 
 @mcp.resource("markets://list")
 def list_markets() -> str:
-    """List all available markets for screening."""
-    categories = {
-        "crypto": ["crypto", "coin"],
-        "instruments": ["forex", "futures", "bonds", "cfd", "options", "economics2"],
-        "americas": ["america", "argentina", "brazil", "canada", "chile", "colombia", "mexico", "peru", "venezuela"],
-        "europe": [
-            "austria",
-            "belgium",
-            "cyprus",
-            "czech",
-            "denmark",
-            "estonia",
-            "finland",
-            "france",
-            "germany",
-            "greece",
-            "hungary",
-            "iceland",
-            "italy",
-            "latvia",
-            "lithuania",
-            "luxembourg",
-            "netherlands",
-            "norway",
-            "poland",
-            "portugal",
-            "romania",
-            "russia",
-            "serbia",
-            "slovakia",
-            "spain",
-            "sweden",
-            "switzerland",
-            "turkey",
-            "uk",
-        ],
-        "asia_pacific": [
-            "australia",
-            "bangladesh",
-            "china",
-            "hongkong",
-            "india",
-            "indonesia",
-            "japan",
-            "korea",
-            "malaysia",
-            "newzealand",
-            "pakistan",
-            "philippines",
-            "singapore",
-            "srilanka",
-            "taiwan",
-            "thailand",
-            "vietnam",
-        ],
-        "middle_east_africa": [
-            "bahrain",
-            "egypt",
-            "israel",
-            "kenya",
-            "ksa",
-            "kuwait",
-            "morocco",
-            "nigeria",
-            "qatar",
-            "rsa",
-            "tunisia",
-            "uae",
-        ],
-    }
-
-    result = "# Available Markets\n\n"
-    for category, markets in categories.items():
-        result += f"## {category.replace('_', ' ').title()}\n"
-        result += ", ".join(sorted(markets)) + "\n\n"
-    return result
+    """Available markets summary."""
+    return json.dumps({
+        "stock_markets": ["america", "uk", "germany", "japan", "china", "hongkong", "taiwan", "korea", "india", "australia", "canada", "brazil", "france", "singapore"],
+        "other_markets": ["crypto", "coin", "forex", "futures", "bonds", "cfd", "options"],
+        "total_stock_markets": 68,
+        "hint": "Use validate_market(name) to check if a market is valid",
+    }, indent=2)
 
 
 @mcp.resource("columns://list")
 def list_columns() -> str:
-    """List all available columns/indicators for screening."""
-    result = "# Available Columns\n\n"
-
-    # Group columns by category
-    categories = {
-        "Price & Change": [
-            "close",
-            "open",
-            "high",
-            "low",
-            "volume",
-            "change",
-            "change_abs",
-            "gap",
-        ],
-        "Moving Averages": [
-            "SMA5",
-            "SMA10",
-            "SMA20",
-            "SMA50",
-            "SMA100",
-            "SMA200",
-            "EMA5",
-            "EMA10",
-            "EMA20",
-            "EMA50",
-            "EMA100",
-            "EMA200",
-        ],
-        "Oscillators": [
-            "RSI",
-            "RSI7",
-            "MACD.macd",
-            "MACD.signal",
-            "Stoch.K",
-            "Stoch.D",
-            "CCI20",
-            "Mom",
-            "AO",
-            "UO",
-        ],
-        "Volatility": ["BB.upper", "BB.lower", "ATR", "Volatility.D", "Volatility.W", "Volatility.M"],
-        "Trend": ["ADX", "ADX+DI", "ADX-DI", "Aroon.Up", "Aroon.Down", "P.SAR"],
-        "Volume": [
-            "volume",
-            "VWAP",
-            "VWMA",
-            "relative_volume_10d_calc",
-            "average_volume_10d_calc",
-            "average_volume_30d_calc",
-        ],
-        "Pre/Post Market": [
-            "premarket_change",
-            "premarket_volume",
-            "premarket_gap",
-            "postmarket_change",
-            "postmarket_volume",
-        ],
-        "Performance": ["Perf.W", "Perf.1M", "Perf.3M", "Perf.6M", "Perf.Y", "Perf.YTD", "Perf.All"],
-        "Fundamentals": [
-            "market_cap_basic",
-            "price_earnings_ttm",
-            "earnings_per_share_basic_ttm",
-            "dividend_yield_recent",
-            "price_book_fq",
-        ],
-        "Ratings": ["Recommend.All", "Recommend.MA", "Recommend.Other"],
-    }
-
-    for category, cols in categories.items():
-        result += f"## {category}\n"
-        result += ", ".join(cols) + "\n\n"
-
-    result += "\n## Full Column Mapping\n"
-    result += "Use human-readable names or API names:\n\n"
-    for human_name, api_name in sorted(COLUMNS.items())[:50]:  # First 50
-        result += f"- `{human_name}` → `{api_name}`\n"
-    result += f"\n... and {len(COLUMNS) - 50} more columns available."
-
-    return result
+    """Field categories summary."""
+    return json.dumps({
+        "categories": FIELD_CATEGORIES,
+        "hint": "Use lookup_field(name) or search_fields(query) for details",
+    }, indent=2)
 
 
 @mcp.resource("exchanges://crypto")
 def list_crypto_exchanges() -> str:
-    """List supported cryptocurrency exchanges."""
-    crypto_exchanges = [ex for ex, screener in EXCHANGE_SCREENER.items() if screener == "crypto"]
-    return f"# Supported Crypto Exchanges\n\n" + ", ".join(sorted(crypto_exchanges))
+    """Crypto exchanges."""
+    exchanges = [ex for ex, screener in EXCHANGE_SCREENER.items() if screener == "crypto"]
+    return json.dumps({"exchanges": sorted(exchanges)[:20], "total": len(exchanges)}, indent=2)
 
 
 @mcp.resource("scanners://presets")
 def list_scanner_presets() -> str:
-    """List available pre-built scanner presets."""
-    result = "# Scanner Presets\n\n"
-
-    result += "## Stock Scanners\n"
-    for name in Scanner.names():
-        result += f"- `{name}`\n"
-
-    result += "\n## Crypto Scanners\n"
-    for name in CryptoScanner.names():
-        result += f"- `{name}`\n"
-
-    return result
+    """Scanner presets summary."""
+    return json.dumps({
+        "stock_scanners": Scanner.names(),
+        "crypto_scanners": CryptoScanner.names(),
+        "hint": "Use run_scanner_preset(name) to execute",
+    }, indent=2)
 
 
 @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},
+    """Screener parameter format."""
+    return json.dumps({
+        "filter_format": {"column": "field_name", "operation": "op", "value": "value"},
+        "operations": ["gt", "gte", "lt", "lte", "eq", "neq", "between", "isin"],
+        "examples": [
+            {"column": "change", "operation": "gt", "value": 5},
+            {"column": "volume", "operation": "gt", "value": 1000000},
+            {"column": "RSI", "operation": "between", "value": [20, 30]},
         ],
-        "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)
+        "hint": "Use get_filter_format(type) for specific type formats",
+    }, 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)
+    """Screener presets (names only)."""
+    names = get_screener_preset_names()
+    return json.dumps({"presets": names, "hint": "Use get_screener_preset(name) for full details"}, indent=2)
+
+
+@mcp.resource("docs://stock-screeners")
+def docs_stock_screeners() -> str:
+    """Stock screener markets (summary)."""
+    data = get_stock_screeners()
+    markets = [{"market": d.get("market"), "title": d.get("title"), "group": d.get("group")} for d in data[:30]]
+    return json.dumps({"markets": markets, "total": len(data)}, indent=2)
+
+
+@mcp.resource("docs://stock-screeners-failed")
+def docs_stock_screeners_failed() -> str:
+    """Failed stock screener markets (summary)."""
+    data = get_stock_screeners_failed()
+    return json.dumps({"count": len(data), "markets": [d.get("market") for d in data][:20]}, 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)
+    """Field categories only."""
+    return json.dumps({
+        "categories": FIELD_CATEGORIES,
+        "hint": "Use lookup_field(name) or search_fields(query) for details",
+    }, 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,
-    )
+    """Markets summary."""
+    return json.dumps({
+        "stock_markets_count": 68,
+        "other_markets": ["crypto", "coin", "forex", "futures", "bonds", "cfd", "options"],
+        "hint": "Use validate_market(name) to check if a market is valid",
+    }, 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,
-    }
+    """Get display name and type for a field."""
+    return lookup_field(field)
 
 
 @mcp.tool()
@@ -504,303 +332,192 @@ def get_screener_preset(name: str) -> dict[str, Any]:
             return preset
     return {
         "error": f"Preset '{name}' not found.",
-        "available": [p.get("name") for p in presets],
+        "available": get_screener_preset_names(),
     }
 
 
 @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
+def list_stock_screener_presets(market: str | None = None, limit: int = 20) -> dict[str, Any]:
+    """List stock screener presets."""
+    data = get_stock_screener_presets(market)
+    if isinstance(data, dict):
+        keys = list(data.keys())[:limit]
+        return {"presets": keys, "total": len(data), "market": market}
+    return {"data": data[:limit] if isinstance(data, list) else data, "market": market}
+
+
+@mcp.tool()
+def list_stock_screeners(limit: int = 30) -> dict[str, Any]:
+    """List stock screener markets."""
+    data = get_stock_screeners()
+    markets = [{"market": d.get("market"), "title": d.get("title")} for d in data[:limit]]
+    return {"markets": markets, "total": len(data)}
+
+
+@mcp.tool()
+def list_failed_stock_screeners() -> dict[str, Any]:
+    """List failed stock screener markets."""
+    data = get_stock_screeners_failed()
+    return {"markets": [d.get("market") for d in data], "total": len(data)}
+
+
+@mcp.tool()
+def get_market_metainfo(market: str, limit: int = 30) -> dict[str, Any]:
+    """Return metainfo summary for a market."""
+    validation = validate_market(market)
+    if not validation.get("valid"):
+        return validation
     
-    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.",
-        }
+    market = validation.get("market", market)
+    return get_market_fields_summary(market)
 
 
 # =============================================================================
-# AI-Friendly Tools - Quick Reference and Search
+# AI-Friendly Tools - Fast Lookup (no large data dumps)
 # =============================================================================
 
 
 @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)
+    """AI quick reference (compact)."""
+    return json.dumps({
+        "field_categories": FIELD_CATEGORIES,
+        "filter_operations": ["gt", "gte", "lt", "lte", "eq", "neq", "between", "isin"],
+        "common_markets": ["america", "crypto", "forex", "uk", "germany", "japan"],
+        "tools": ["lookup_field", "search_fields", "validate_market", "get_filter_format"],
+    }, 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)
+    """Code example names only."""
+    names = get_code_example_names()
+    return json.dumps({"examples": names, "hint": "Use get_code_example(name) for code"}, 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()
+    """Get quick reference for markets and fields."""
+    return get_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)
-    
+def search_available_fields(query: str, market: str = "stocks", limit: int = 15) -> dict[str, Any]:
+    """Search fields by name or display name."""
+    results = search_fields(query, market, min(limit, 30))
     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.",
+        "hint": "Use the 'name' field as the column name in queries." if results else "No matches. Try different keywords.",
     }
 
 
 @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
-    """
+    """Get code example for a screener type."""
     examples = get_screener_code_examples()
     
-    # Try exact match first
     if screener_name in examples:
-        return {
-            "name": screener_name,
-            "code": examples[screener_name],
-        }
+        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.",
-    }
+    return {"error": f"'{screener_name}' not found.", "available": list(examples.keys())}
 
 
 @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)
+def list_fields_for_market(market: str = "stocks", category: str | None = None, limit: int = 30) -> dict[str, Any]:
+    """List fields for a market."""
+    validation = validate_market(market)
+    if not validation.get("valid"):
+        return validation
     
+    fields = get_fields_by_market(validation.get("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"],
-        }
+        return {"error": f"No fields for '{market}'.", "use": "search_fields(query) instead"}
     
-    # 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()]
+        fields = [f for f in fields if category.lower() in f.get("type", "").lower()]
     
-    return paginate_data(fields, offset, limit, confirm_large)
+    if isinstance(fields, list):
+        return {"fields": [f.get("name") for f in fields[:limit]], "total": len(fields)}
+    return {"note": "Use search_fields() for this market"}
 
 
 @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", {})
-    
+def get_common_fields_summary(category: str | None = None) -> dict[str, Any]:
+    """Get common fields by category."""
     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.",
-    }
+        fields = FIELD_CATEGORIES.get(category.lower())
+        if fields:
+            return {"category": category, "fields": fields}
+        return {"error": f"Category '{category}' not found.", "available": list(FIELD_CATEGORIES.keys())}
+    return {"categories": FIELD_CATEGORIES}
 
 
 # =============================================================================
-# Help and Discovery Tools - Help AI understand usage
+# Fast Lookup Tools - Direct answers
+# =============================================================================
+
+
+@mcp.tool()
+def lookup_single_field(field_name: str) -> dict[str, Any]:
+    """Lookup a single field by exact name."""
+    return lookup_field(field_name)
+
+
+@mcp.tool()
+def get_filter_example(field_type: str = "number") -> dict[str, Any]:
+    """Get correct filter format for a field type."""
+    return get_filter_format(field_type)
+
+
+@mcp.tool()
+def check_market(market: str) -> dict[str, Any]:
+    """Validate market name and get correct format."""
+    return validate_market(market)
+
+
+# =============================================================================
+# Help Tool - Compact guide
 # =============================================================================
 
 
 @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
-    """
+    """Usage guide."""
     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",
+            "1": "get_top_gainers('america', 10) - top gainers",
+            "2": "search_symbols('apple', 'america') - find symbols",
+            "3": "get_symbol_info('NASDAQ:AAPL') - symbol details",
         },
         "markets": {
-            "stocks": ["america (US)", "uk (UK)", "germany (DE)", "japan (JP)", "china (CN)", "hongkong (HK)", "taiwan (TW)"],
-            "crypto": ["crypto (pairs)", "coin (coins)",],
+            "stocks": ["america", "uk", "germany", "japan", "china"],
+            "crypto": ["crypto", "coin"],
             "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')",
+        "tools": {
+            "screening": ["screen_market", "get_top_gainers", "get_top_losers", "get_most_active"],
+            "lookup": ["search_symbols", "get_symbol_info", "get_technical_analysis"],
+            "reference": ["lookup_field", "search_fields", "check_market", "get_filter_example"],
         },
-        "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"],
+        "columns": FIELD_CATEGORIES,
+        "filters": {
+            "format": {"column": "field", "operation": "op", "value": "val"},
+            "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"],
-        }
+        t = topic.lower()
+        if t in guide:
+            return {topic: guide[t]}
+        return {"error": f"Topic '{topic}' not found", "available": list(guide.keys())}
     
     return guide
 
@@ -811,22 +528,7 @@ def search_symbols(
     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
-    """
+    """Search symbols by name or ticker."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
     
@@ -921,20 +623,7 @@ 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
-    """
+    """Get detailed information for a symbol."""
     cols = [
         "name", "description", "close", "open", "high", "low", 
         "change", "change_abs", "volume", "market_cap_basic",
@@ -1001,23 +690,7 @@ def screen_market(
     limit: int = 25,
     filters: Optional[list[dict[str, Any]]] = None,
 ) -> dict[str, Any]:
-    """Run a custom market screening query.
-    
-    ⚠️ Note: Default returns 25 rows. Increase `limit` for more.
-
-    Args:
-        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:
-        Dict with total_count, returned, data.
-        Each row includes description (full name like "Apple Inc.").
-    """
+    """Run a custom market screening query."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 500))
     
@@ -1072,21 +745,7 @@ def screen_market(
 
 @mcp.tool()
 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 (america=US stocks, crypto, uk, etc.)
-        limit: Result count (1-100, default 25)
-
-    Returns:
-        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
-    """
+    """Get top gainers for a market."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1118,20 +777,7 @@ def get_top_gainers(market: str = "america", limit: int = 25) -> dict[str, Any]:
 
 @mcp.tool()
 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 (america=US stocks, crypto, uk, etc.)
-        limit: Result count (1-100, default 25)
-
-    Returns:
-        Top losers with description (full name).
-        
-    Example:
-        get_top_losers("america", 10) -> Top 10 US losers
-    """
+    """Get top losers for a market."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1163,17 +809,7 @@ def get_top_losers(market: str = "america", limit: int = 25) -> dict[str, Any]:
 
 @mcp.tool()
 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
-        limit: Result count (1-100)
-
-    Returns:
-        Most active list with description (full name)
-    """
+    """Get most active by volume."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1199,15 +835,7 @@ def get_most_active(market: str = "america", limit: int = 25) -> dict[str, Any]:
 def get_premarket_movers(
     scan_type: str = "gainers", limit: int = 25
 ) -> dict[str, Any]:
-    """Get pre-market movers (US only).
-
-    Args:
-        scan_type: 'gainers', 'losers', 'most_active', 'gappers'
-        limit: Result count (1-100)
-
-    Returns:
-        List of pre-market movers
-    """
+    """Get pre-market movers (US only)."""
     limit = max(1, min(limit, 100))
 
     scanner_map = {
@@ -1231,16 +859,7 @@ def get_premarket_movers(
 def get_postmarket_movers(
     scan_type: str = "gainers", limit: int = 25
 ) -> list[dict[str, Any]]:
-    """
-    Get post-market movers (US market only).
-
-    Args:
-        scan_type: Type of scan - 'gainers', 'losers', 'most_active'
-        limit: Number of results (1-100)
-
-    Returns:
-        List of post-market movers
-    """
+    """Get post-market movers (US only)."""
     limit = max(1, min(limit, 100))
 
     scanner_map = {
@@ -1271,18 +890,7 @@ def scan_rsi_extremes(
     threshold: float = 30,
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for RSI overbought/oversold conditions.
-
-    Args:
-        market: Market to scan
-        condition: 'oversold' or 'overbought'
-        threshold: RSI threshold (default 30 for oversold, 70 for overbought)
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols matching RSI criteria
-    """
+    """Scan for RSI overbought/oversold conditions."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1326,17 +934,7 @@ def scan_macd_crossover(
     crossover_type: str = "bullish",
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for MACD crossover signals.
-
-    Args:
-        market: Market to scan
-        crossover_type: 'bullish' (MACD crosses above signal) or 'bearish'
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols with MACD crossover
-    """
+    """Scan for MACD crossover signals."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1374,17 +972,7 @@ def scan_bollinger_bands(
     condition: str = "squeeze",
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for Bollinger Band conditions.
-
-    Args:
-        market: Market to scan
-        condition: 'squeeze' (low volatility), 'above_upper', 'below_lower'
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols matching BB criteria
-    """
+    """Scan for Bollinger Band conditions."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1430,18 +1018,7 @@ def scan_volume_breakout(
     min_price_change: float = 3.0,
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for volume breakout candidates.
-
-    Args:
-        market: Market to scan
-        volume_multiplier: Minimum relative volume vs 10-day average (default 2.0)
-        min_price_change: Minimum absolute price change % (default 3.0)
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols with volume breakouts
-    """
+    """Scan for volume breakout candidates."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
     volume_multiplier = max(1.2, min(10.0, volume_multiplier))
@@ -1493,19 +1070,7 @@ def scan_moving_average_crossover(
     crossover_type: str = "golden_cross",
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for moving average crossovers.
-
-    Args:
-        market: Market to scan
-        crossover_type: 'golden_cross' (SMA50 crosses above SMA200),
-                       'death_cross' (SMA50 crosses below SMA200),
-                       'above_all_mas', 'below_all_mas'
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols with MA crossovers
-    """
+    """Scan for moving average crossovers."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
 
@@ -1552,18 +1117,7 @@ def scan_52_week_levels(
     threshold_pct: float = 5.0,
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan for stocks near 52-week highs or lows.
-
-    Args:
-        market: Market to scan
-        level_type: 'near_high', 'near_low', 'new_high', 'new_low'
-        threshold_pct: How close to the level (default 5%)
-        limit: Number of results (1-100)
-
-    Returns:
-        List of symbols near 52-week extremes
-    """
+    """Scan for stocks near 52-week highs or lows."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 100))
     threshold_pct = max(1.0, min(20.0, threshold_pct))
@@ -1622,16 +1176,7 @@ def get_symbol_analysis(
     symbol: str,
     include_fundamentals: bool = True,
 ) -> dict[str, Any]:
-    """
-    Get comprehensive technical analysis for a specific symbol.
-
-    Args:
-        symbol: Symbol in format 'EXCHANGE:SYMBOL' (e.g., 'NASDAQ:AAPL', 'BINANCE:BTCUSDT')
-        include_fundamentals: Include fundamental data if available
-
-    Returns:
-        Comprehensive analysis with indicators, signals, and recommendations
-    """
+    """Get comprehensive technical analysis for a symbol."""
     # Select columns based on what we want
     cols = [
         "name",
@@ -1770,16 +1315,7 @@ def compare_symbols(
     symbols: list[str],
     columns: Optional[list[str]] = None,
 ) -> list[dict[str, Any]]:
-    """
-    Compare multiple symbols side by side.
-
-    Args:
-        symbols: List of symbols (e.g., ['NASDAQ:AAPL', 'NASDAQ:MSFT', 'NASDAQ:GOOGL'])
-        columns: Columns to compare (default: standard comparison set)
-
-    Returns:
-        Comparison data for all symbols
-    """
+    """Compare multiple symbols side by side."""
     if not symbols:
         return [{"error": "No symbols provided"}]
 
@@ -1821,15 +1357,7 @@ def compare_symbols(
 
 @mcp.tool()
 def get_all_market_symbols(market: str = "america") -> dict[str, Any]:
-    """
-    Get all available symbols for a market.
-
-    Args:
-        market: Market identifier (america, crypto, uk, etc.)
-
-    Returns:
-        Dictionary with symbol count and list of symbols
-    """
+    """Get available symbols for a market."""
     market = sanitize_market(market)
 
     try:
@@ -1850,17 +1378,7 @@ def run_scanner_preset(
     market: Optional[str] = None,
     limit: int = 50,
 ) -> list[dict[str, Any]]:
-    """
-    Run a pre-built scanner preset.
-
-    Args:
-        preset_name: Name of the preset (see scanners://presets resource)
-        market: Override market (optional)
-        limit: Number of results (1-100)
-
-    Returns:
-        Scanner results
-    """
+    """Run a pre-built scanner preset."""
     limit = max(1, min(limit, 100))
 
     # Try stock scanners first
@@ -1897,31 +1415,7 @@ def advanced_query(
     ascending: bool = False,
     limit: int = 50,
 ) -> list[dict[str, Any]]:
-    """
-    Execute an advanced query with complex AND/OR logic.
-
-    Args:
-        market: Market to scan
-        select_columns: Columns to return
-        conditions: List of conditions, each with:
-                   - column: Column name
-                   - op: Operation (gt, gte, lt, lte, eq, neq, between, isin, crosses_above, crosses_below)
-                   - value: Value or [min, max] for between
-        logic: 'and' or 'or' to combine conditions
-        sort_by: Column to sort by
-        ascending: Sort order
-        limit: Maximum results (1-500)
-
-    Returns:
-        Query results
-
-    Example:
-        conditions=[
-            {"column": "RSI", "op": "lt", "value": 30},
-            {"column": "volume", "op": "gt", "value": 1000000},
-            {"column": "change", "op": "between", "value": [-5, 5]}
-        ]
-    """
+    """Execute an advanced query with AND/OR logic."""
     market = sanitize_market(market)
     limit = max(1, min(limit, 500))
     cols = select_columns or TECHNICAL_COLUMNS
@@ -1981,16 +1475,7 @@ def advanced_query(
 
 @mcp.tool()
 def get_crypto_gainers(exchange: Optional[str] = None, limit: int = 25) -> list[dict[str, Any]]:
-    """
-    Get top gaining cryptocurrencies.
-
-    Args:
-        exchange: Specific exchange (binance, coinbase, etc.) or None for all
-        limit: Number of results (1-100)
-
-    Returns:
-        List of top crypto gainers
-    """
+    """Get top gaining cryptocurrencies."""
     limit = max(1, min(limit, 100))
 
     cols = ["name", "close", "volume", "change", "change_abs", "market_cap_basic", "24h_vol|5"]
@@ -2016,16 +1501,7 @@ def get_crypto_gainers(exchange: Optional[str] = None, limit: int = 25) -> list[
 
 @mcp.tool()
 def get_crypto_losers(exchange: Optional[str] = None, limit: int = 25) -> list[dict[str, Any]]:
-    """
-    Get top losing cryptocurrencies.
-
-    Args:
-        exchange: Specific exchange (binance, coinbase, etc.) or None for all
-        limit: Number of results (1-100)
-
-    Returns:
-        List of top crypto losers
-    """
+    """Get top losing cryptocurrencies."""
     limit = max(1, min(limit, 100))
 
     cols = ["name", "close", "volume", "change", "change_abs", "market_cap_basic", "24h_vol|5"]
@@ -2055,17 +1531,7 @@ def scan_crypto_technicals(
     exchange: Optional[str] = None,
     limit: int = 25,
 ) -> list[dict[str, Any]]:
-    """
-    Scan cryptocurrencies based on technical indicators.
-
-    Args:
-        scan_type: Type of scan - 'oversold', 'overbought', 'macd_bullish', 'macd_bearish', 'high_volume'
-        exchange: Specific exchange or None for all
-        limit: Number of results (1-100)
-
-    Returns:
-        Crypto technical scan results
-    """
+    """Scan cryptocurrencies based on technical indicators."""
     limit = max(1, min(limit, 100))
 
     scanner_map = {