@etsquare/mcp-server-sec 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 /**
- * @etsquare/mcp-server-sec
+ * @etsquare/mcp-server-sec  v0.3.0
  * MCP server for SEC Intelligence: search SEC filings,
- * resolve company tickers, and execute financial metrics templates.
+ * resolve company tickers, execute financial metrics templates,
+ * compare companies, and access weekly briefs.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { ETSquareClient } from './etsquare-client.js';
-// Guardrail keywords to detect prompt injection attempts
+// ─── Guardrails ─────────────────────────────────────────────────────────────
 const GUARDRAIL_KEYWORDS = [
     'reset guardrails',
     'disable guardrails',
@@ -40,8 +41,8 @@ function guardrailViolationResponse() {
         isError: true,
     };
 }
-// Environment configuration
-const baseUrl = process.env.ETSQUARE_BASE_URL || 'https://www.etsquare.ai';
+// ─── Environment ────────────────────────────────────────────────────────────
+const baseUrl = process.env.ETSQUARE_BASE_URL || 'https://sec-intelligence-api-4mk2on5fga-uc.a.run.app';
 const apiKey = process.env.ETSQUARE_API_KEY;
 const DEBUG = process.env.DEBUG === 'true';
 function log(level, message, data) {
@@ -51,20 +52,277 @@ function log(level, message, data) {
     const logData = data ? ` ${JSON.stringify(data)}` : '';
     console.error(`[${timestamp}] [${level.toUpperCase()}] ${message}${logData}`);
 }
-// Validate API key
 if (!apiKey) {
     console.error('ERROR: ETSQUARE_API_KEY environment variable is required');
     process.exit(1);
 }
-// Initialize client
 const client = new ETSquareClient({ baseUrl, apiKey });
-log('info', `ETSquare MCP Server starting with backend: ${baseUrl}`);
-// Initialize MCP Server
+log('info', `ETSquare MCP Server v0.3.0 starting with backend: ${baseUrl}`);
+// ─── Item Code Labels ───────────────────────────────────────────────────────
+const ITEM_CODE_LABELS = {
+    // 10-K
+    '10k_item_1': 'Business Description',
+    '10k_item_1a': 'Risk Factors',
+    '10k_item_1_a': 'Risk Factors',
+    '10k_item_2': 'Properties',
+    '10k_item_3': 'Legal Proceedings',
+    '10k_item_5': 'Market for Equity',
+    '10k_item_6': 'Selected Financial Data',
+    '10k_item_7': 'MD&A',
+    '10k_item_7a': 'Market Risk Disclosures',
+    '10k_item_7_a': 'Market Risk Disclosures',
+    '10k_item_8': 'Financial Statements',
+    '10k_item_9a': 'Controls & Procedures',
+    // 10-Q
+    '10q_item_1': 'Financial Statements (Quarterly)',
+    '10q_item_1a': 'Risk Factors (Quarterly)',
+    '10q_item_1_a': 'Risk Factors (Quarterly)',
+    '10q_item_2': 'MD&A (Quarterly)',
+    '10q_item_3': 'Market Risk (Quarterly)',
+    // 8-K
+    '8k_item_1_01': 'Entry into Material Agreement',
+    '8k_item_1_02': 'Termination of Material Agreement',
+    '8k_item_1_05': 'Material Cybersecurity Incident',
+    '8k_item_2_01': 'Completion of Acquisition/Disposition',
+    '8k_item_2_02': 'Results of Operations (Earnings)',
+    '8k_item_2_03': 'Creation of Direct Financial Obligation',
+    '8k_item_2_04': 'Triggering Events (Acceleration/Default)',
+    '8k_item_2_05': 'Costs Associated with Exit/Disposal',
+    '8k_item_2_06': 'Material Impairments',
+    '8k_item_4_01': 'Change in Accountant',
+    '8k_item_4_02': 'Non-Reliance on Financial Statements',
+    '8k_item_5_01': 'Change in Control',
+    '8k_item_5_02': 'Director/Officer Changes',
+    '8k_item_5_03': 'Amendments to Articles/Bylaws',
+    '8k_item_7_01': 'Regulation FD Disclosure',
+    '8k_item_8_01': 'Other Events',
+    '8k_item_9_01': 'Financial Statements and Exhibits',
+};
+function mapItemCodeToLabel(itemCode) {
+    if (!itemCode)
+        return 'Unknown';
+    return ITEM_CODE_LABELS[itemCode] || itemCode;
+}
+// Visualization hints are stored in each template's tags_json.visualization_hint
+// in the database and flow through the API. No static registry needed.
+// ─── Column Type / Role Inference Helpers ───────────────────────────────────
+const TIME_FIELDS = new Set([
+    'fiscal_year', 'fiscal_period', 'period', 'period_end',
+    'filing_date', 'quarter', 'year', 'data_as_of',
+]);
+const GROUP_FIELDS = new Set(['ticker', 'company_name', 'sic_code', 'sic', 'sector', 'industry', 'name']);
+const SIGNAL_FIELDS = new Set(['trend_direction', 'signal', 'flag']);
+function inferColumnType(col, rows) {
+    if (rows.length === 0)
+        return 'string';
+    const sample = rows[0][col];
+    if (typeof sample === 'number')
+        return Number.isInteger(sample) ? 'int' : 'float';
+    return 'string';
+}
+function inferColumnRole(col) {
+    if (TIME_FIELDS.has(col))
+        return 'time';
+    if (GROUP_FIELDS.has(col))
+        return 'group';
+    if (SIGNAL_FIELDS.has(col))
+        return 'signal';
+    return 'measure';
+}
+function inferColumnUnit(col) {
+    if (col.endsWith('_pct') || col.includes('margin') || col.includes('growth'))
+        return 'pct';
+    if (col.endsWith('_b') || col.includes('revenue') || col.includes('income')
+        || col.includes('profit') || col.includes('expense'))
+        return 'USD_B';
+    if (col.includes('ratio') || col.includes('multiple'))
+        return 'ratio';
+    if (col.includes('eps') || col.includes('per_share'))
+        return 'USD';
+    return null;
+}
+function humanizeColumnName(col) {
+    return col
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase())
+        .replace('Pct', '%')
+        .replace('Yoy', 'YoY')
+        .replace('Qoq', 'QoQ');
+}
+// ─── Structured Response Builders ───────────────────────────────────────────
+function buildSearchContext(apiResponse, originalQuery) {
+    const results = apiResponse.narrative_results || [];
+    const ec = apiResponse.execution_contract || {};
+    return {
+        query_received: originalQuery,
+        query_type: apiResponse.query_type || null,
+        scope_confidence: apiResponse.scope_confidence || null,
+        tickers_resolved: [...new Set(results.map((r) => r.ticker).filter(Boolean))],
+        scope_effective: ec.scope_effective || null,
+        mode_effective: ec.mode_effective || null,
+        mode_source: ec.mode_source || null,
+        scope_source: ec.scope_source || null,
+        intent_matched: apiResponse.intent_matched || null,
+        results_returned: results.length,
+        unique_tickers: new Set(results.map((r) => r.ticker)).size,
+        unique_forms: [...new Set(results.map((r) => r.form_type).filter(Boolean))],
+        template_match: ec.template_match || null,
+        relaxations_applied: ec.relaxations_applied || [],
+        execution_id: apiResponse.execution_id || null,
+        processing_time_ms: apiResponse.processing_time_ms || null,
+    };
+}
+function deriveLayoutHint(apiResponse) {
+    const results = apiResponse.narrative_results || [];
+    const tickers = new Set(results.map((r) => r.ticker));
+    const ec = apiResponse.execution_contract || {};
+    const scopeEffective = ec.scope_effective || '';
+    const hasMetrics = Array.isArray(apiResponse.xbrl_metrics) && apiResponse.xbrl_metrics.length > 0;
+    if (tickers.size >= 2 && hasMetrics) {
+        return {
+            suggested: 'comparison_dashboard',
+            reason: 'multi_ticker_with_metrics',
+            panels: ['metrics_chart', 'narrative_side_by_side'],
+            tone: 'comparative',
+        };
+    }
+    if (tickers.size >= 2) {
+        return {
+            suggested: 'comparison_grid',
+            reason: 'multi_ticker_narrative',
+            panels: ['narrative_by_ticker'],
+            tone: 'comparative',
+        };
+    }
+    if (tickers.size === 1 && hasMetrics) {
+        return {
+            suggested: 'company_profile',
+            reason: 'single_ticker_hybrid',
+            panels: ['metrics_chart', 'evidence_cards'],
+            tone: 'analytical',
+        };
+    }
+    if (scopeEffective === 'MACRO') {
+        return {
+            suggested: 'cross_company_theme',
+            reason: 'macro_scope',
+            panels: ['theme_summary', 'evidence_by_ticker'],
+            tone: 'analytical',
+        };
+    }
+    if (scopeEffective === 'INDUSTRY') {
+        return {
+            suggested: 'industry_overview',
+            reason: 'industry_scope',
+            panels: ['sector_summary', 'evidence_by_ticker'],
+            tone: 'analytical',
+        };
+    }
+    return {
+        suggested: 'evidence_cards',
+        reason: 'single_company_narrative',
+        alternatives: ['evidence_timeline', 'risk_factor_summary'],
+        tone: 'analytical',
+    };
+}
+function deriveMetricsVizHint(rows, schema) {
+    const columns = schema?.columns || [];
+    if (columns.length === 0)
+        return { chart_type: 'table' };
+    const timeCol = columns.find((c) => c.role === 'time');
+    const measureCols = columns.filter((c) => c.role === 'measure');
+    const groupCol = columns.find((c) => c.role === 'group');
+    if (!timeCol || measureCols.length === 0)
+        return { chart_type: 'table' };
+    const tickerCol = groupCol?.name || 'ticker';
+    const tickers = new Set(rows.map((r) => r[tickerCol]).filter(Boolean));
+    const primaryMeasure = measureCols[0];
+    const secondaryMeasure = measureCols.find((c) => c.unit === 'pct' && c.name !== primaryMeasure.name);
+    return {
+        chart_type: tickers.size > 1 ? 'grouped_bar' : 'line',
+        x: { field: timeCol.name, order: 'chronological', label: timeCol.label },
+        y_primary: {
+            field: primaryMeasure.name,
+            label: primaryMeasure.label,
+            format: primaryMeasure.unit === 'USD_B' ? 'currency_b'
+                : primaryMeasure.unit === 'pct' ? 'pct' : 'number',
+        },
+        y_secondary: secondaryMeasure ? {
+            field: secondaryMeasure.name,
+            label: secondaryMeasure.label,
+            chart_type: 'bar',
+            opacity: 0.3,
+            format: 'pct',
+        } : undefined,
+        group_by: tickers.size > 1 ? tickerCol : undefined,
+        color_palette: tickers.size > 1 ? 'comparison_diverging' : 'single_accent',
+        formats: {
+            currency_b: { prefix: '$', suffix: 'B', decimals: 1 },
+            pct: { suffix: '%', decimals: 1, sign: true },
+            number: { decimals: 0, comma_separated: true },
+        },
+    };
+}
+function computeSummaryStats(columnNames, rows) {
+    if (rows.length === 0)
+        return null;
+    const numericCols = columnNames.filter(c => typeof rows[0]?.[c] === 'number'
+        && !['fiscal_year', 'year'].includes(c));
+    if (numericCols.length === 0)
+        return null;
+    const primary = numericCols[0];
+    const values = rows.map(r => r[primary]).filter((v) => v != null);
+    if (values.length === 0)
+        return null;
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    return {
+        row_count: rows.length,
+        primary_measure: primary,
+        min,
+        max,
+        range_pct: min !== 0
+            ? Math.round(((max - min) / Math.abs(min)) * 1000) / 10
+            : null,
+    };
+}
+function buildColumnMeta(apiColumns, rows) {
+    const columnNames = apiColumns.length > 0
+        ? apiColumns.map((c) => typeof c === 'string' ? c : c.name)
+        : (rows.length > 0 ? Object.keys(rows[0]) : []);
+    return columnNames.map((col) => ({
+        name: col,
+        type: inferColumnType(col, rows),
+        role: inferColumnRole(col),
+        unit: inferColumnUnit(col),
+        label: humanizeColumnName(col),
+    }));
+}
+// ─── Text Formatting Helpers (existing behavior) ────────────────────────────
+function formatNumberForTable(val) {
+    if (val === null || val === undefined)
+        return 'N/A';
+    if (typeof val === 'number')
+        return Number.isInteger(val) ? String(val) : val.toFixed(2);
+    return String(val);
+}
+function buildMarkdownTable(colNames, rows, maxRows = 20) {
+    const header = colNames.join(' | ');
+    const separator = colNames.map(() => '---').join(' | ');
+    const displayRows = rows.slice(0, maxRows);
+    const tableRows = displayRows.map((row) => colNames.map((col) => formatNumberForTable(row[col])).join(' | '));
+    const table = [header, separator, ...tableRows].join('\n');
+    const suffix = rows.length > maxRows
+        ? `\n(Showing ${maxRows} of ${rows.length} rows)`
+        : '';
+    return `${table}${suffix}`;
+}
+// ─── MCP Server ─────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'etsquare-mcp-sec',
-    version: '0.2.0',
+    version: '0.3.0',
 });
-// Tool 1: Company Lookup
+// ─── Tool 1: Company Lookup ─────────────────────────────────────────────────
 server.registerTool('etsquare_lookup_company', {
     title: 'Look Up Company Ticker',
     description: 'Resolve a company name or partial ticker to its official SEC ticker symbol and CIK number. ' +
@@ -107,17 +365,20 @@ server.registerTool('etsquare_lookup_company', {
         };
     }
 });
-// Tool 2: SEC Filing Search
+// ─── Tool 2: SEC Filing Search ──────────────────────────────────────────────
 server.registerTool('etsquare_search', {
     title: 'Search SEC Filings',
-    description: 'Search 1.2M+ SEC filing sections (10-K, 10-Q, 8-K) with hybrid retrieval. ' +
+    description: 'Search 3.4M+ SEC filing sections (10-K, 10-Q, 8-K) with hybrid retrieval. ' +
         'Returns verbatim filing text with citations — best for qualitative research.\n\n' +
         'Execution contract (required):\n' +
         '- mode_lock: NARRATIVE (recommended) | HYBRID\n' +
         '- scope_lock: COMPANY (specific tickers) | INDUSTRY (SIC sector) | MACRO (cross-market)\n\n' +
-        'For structured financial data (revenue, margins, ratios), use etsquare_discover_metrics + etsquare_execute_metrics instead.\n\n' +
+        'For canonical financial statements (income statement, balance sheet, cash flow), use etsquare_financial_statements.\n' +
+        'For custom financial queries or peer comparisons, use etsquare_discover_metrics + etsquare_execute_metrics.\n\n' +
+        'For INDUSTRY scope, use sector to target a specific industry (e.g., sector="semiconductors"). ' +
         'Use tickers to scope to specific companies (resolve names first with etsquare_lookup_company). ' +
-        'Results include verbatim filing text, similarity scores, and SEC source URLs.',
+        'Results include filing text plus safe citation metadata such as chunk_id, accession number, and SEC URL for follow-up retrieval.\n\n' +
+        'Set response_format="structured" for typed JSON with search_context, layout hints, and chart-ready data.',
     inputSchema: {
         query: z.string().min(3).describe('What to search for in SEC filings (e.g., "customer concentration risk", "Show NVDA revenue trend")'),
         mode_lock: z.enum(['NARRATIVE', 'HYBRID']).describe('NARRATIVE for text search, HYBRID for text + any available metrics'),
@@ -125,7 +386,15 @@ server.registerTool('etsquare_search', {
         top_k: z.number().min(1).max(50).default(5).describe('Number of results to return (default: 5)'),
         tickers: z.array(z.string()).optional().describe('Limit to specific companies by ticker (e.g., ["AAPL", "MSFT"])'),
         doc_types: z.array(z.string()).optional().describe('Limit by SEC form type: "10-k", "10-q", "8-k"'),
-        sic_codes: z.array(z.string()).optional().describe('Limit by SIC industry code (e.g., "7372", "3674")'),
+        sector: z.string().optional().describe('Industry/sector hint for INDUSTRY-scope queries. Resolved internally to SIC codes. ' +
+            'Examples: "software", "fintech", "energy", "semiconductors", "biotech", "REITs", "banks", ' +
+            '"defense", "utilities", "oil and gas", "healthcare", "cloud", "cybersecurity". ' +
+            'If sic_codes is also provided, sic_codes takes precedence.'),
+        sic_codes: z.array(z.string()).optional().describe('Expert override: limit by SIC industry code (e.g., "7372", "3674"). Takes precedence over sector.'),
+        response_format: z.enum(['text', 'structured']).default('text')
+            .describe('"text" returns numbered citations (default). "structured" returns JSON with search_context, typed results, and layout hints.'),
+        include_context: z.boolean().default(false)
+            .describe('Auto-expand top 2 truncated results with surrounding context'),
     },
 }, async (input) => {
     if (containsGuardrailBypass(input))
@@ -136,6 +405,7 @@ server.registerTool('etsquare_search', {
             mode_lock: input.mode_lock,
             scope_lock: input.scope_lock,
             top_k: input.top_k,
+            response_format: input.response_format,
         });
         const result = await client.search(input);
         const searchResults = Array.isArray(result.narrative_results)
@@ -147,12 +417,78 @@ server.registerTool('etsquare_search', {
             ? result.xbrl_metrics
             : [];
         const resultCount = searchResults.length;
+        const executionId = typeof result.execution_id === 'string'
+            ? result.execution_id
+            : null;
+        const researchRunId = typeof result.research_run_id === 'string'
+            ? result.research_run_id
+            : null;
         if (resultCount === 0 && xbrlMetrics.length === 0) {
             let text = `No results found for: "${input.query}"`;
             text += '\nTry broadening your query or removing filters.';
             return { content: [{ type: 'text', text }] };
         }
-        // Format narrative citations
+        // Auto-expand truncated chunks with surrounding context
+        if (input.include_context) {
+            const truncatedChunks = searchResults
+                .filter((r) => r.chunk_text_truncated)
+                .slice(0, 2);
+            for (const chunk of truncatedChunks) {
+                try {
+                    const ctx = await client.getChunkContext({
+                        chunk_id: chunk.chunk_id,
+                        neighbor_span: 1,
+                        window: 1200,
+                    });
+                    const ctxData = ctx.context || {};
+                    chunk._expanded_context = {
+                        before: ctxData.before || null,
+                        highlight: ctxData.highlight || null,
+                        after: ctxData.after || null,
+                    };
+                }
+                catch {
+                    // Non-fatal — skip context expansion on failure
+                }
+            }
+        }
+        // ── Structured response path ──
+        if (input.response_format === 'structured') {
+            const metricsColumnMeta = xbrlMetrics.length > 0
+                ? buildColumnMeta(result.xbrl_output_schema?.columns || [], xbrlMetrics)
+                : null;
+            const structured = {
+                search_context: buildSearchContext(result, input.query),
+                results: searchResults
+                    .slice(0, input.top_k || 5)
+                    .map((r, i) => ({
+                    index: i + 1,
+                    chunk_id: r.chunk_id,
+                    ticker: r.ticker,
+                    company_name: r.company_name,
+                    form_type: r.form_type,
+                    filing_date: r.filing_date,
+                    item_code: r.item_code,
+                    section_label: mapItemCodeToLabel(r.item_code),
+                    score: r.similarity_score,
+                    chunk_text: r.chunk_text,
+                    truncated: r.chunk_text_truncated || false,
+                    chunk_text_length: r.chunk_text_length || null,
+                    accession_number: r.accession_number,
+                    sec_url: r.sec_url,
+                    expanded_context: r._expanded_context || undefined,
+                })),
+                metrics: xbrlMetrics.length > 0 ? {
+                    rows: xbrlMetrics,
+                    columns: metricsColumnMeta,
+                    visualization_hint: deriveMetricsVizHint(xbrlMetrics, { columns: metricsColumnMeta }),
+                } : null,
+                layout_hint: deriveLayoutHint(result),
+            };
+            log('info', `Search returned ${resultCount} citations, ${xbrlMetrics.length} metrics [structured]`);
+            return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }] };
+        }
+        // ── Text response path (existing behavior) ──
         const sections = [];
         if (resultCount > 0) {
             const formatted = searchResults
@@ -167,10 +503,29 @@ server.registerTool('etsquare_search', {
                 if (r.fiscal_year && r.fiscal_period) {
                     lines[1] += ` | ${r.fiscal_period} FY${r.fiscal_year}`;
                 }
+                const metaParts = [];
+                if (r.chunk_id)
+                    metaParts.push(`Chunk ID: ${r.chunk_id}`);
+                if (r.accession_number)
+                    metaParts.push(`Accession: ${r.accession_number}`);
+                if (r.chunk_text_truncated)
+                    metaParts.push('Truncated: yes');
+                if (metaParts.length > 0) {
+                    lines.push(`    ${metaParts.join(' | ')}`);
+                }
                 if (r.chunk_text) {
                     const snippet = r.chunk_text.substring(0, 600);
                     lines.push(`    ${snippet}${r.chunk_text.length > 600 ? '...' : ''}`);
                 }
+                // Include expanded context if available
+                if (r._expanded_context) {
+                    if (r._expanded_context.before) {
+                        lines.push(`    [Context before]: ${r._expanded_context.before.substring(0, 300)}...`);
+                    }
+                    if (r._expanded_context.after) {
+                        lines.push(`    [Context after]: ${r._expanded_context.after.substring(0, 300)}...`);
+                    }
+                }
                 const url = r.sec_url || r.source_url;
                 if (url) {
                     lines.push(`    SEC URL: ${url}`);
@@ -178,27 +533,18 @@ server.registerTool('etsquare_search', {
                 return lines.join('\n');
             })
                 .join('\n\n');
-            sections.push(`SEC Filing Citations (${resultCount}):\n\n${formatted}`);
+            const headerParts = [`SEC Filing Citations (${resultCount}):`];
+            if (executionId)
+                headerParts.push(`Execution ID: ${executionId}`);
+            if (researchRunId)
+                headerParts.push(`Research Run ID: ${researchRunId}`);
+            const header = headerParts.join('\n');
+            sections.push(`${header}\n\n${formatted}`);
         }
-        // Format XBRL metrics if present (handles both wide-format and long-format rows)
         if (xbrlMetrics.length > 0) {
             const colNames = Object.keys(xbrlMetrics[0] || {}).filter((k) => !k.startsWith('_'));
-            const header = colNames.join(' | ');
-            const separator = colNames.map(() => '---').join(' | ');
-            const displayRows = xbrlMetrics.slice(0, 20);
-            const tableRows = displayRows.map((row) => colNames.map((col) => {
-                const val = row[col];
-                if (val === null || val === undefined)
-                    return 'N/A';
-                if (typeof val === 'number')
-                    return Number.isInteger(val) ? String(val) : val.toFixed(2);
-                return String(val);
-            }).join(' | '));
-            const table = [header, separator, ...tableRows].join('\n');
-            const suffix = xbrlMetrics.length > 20
-                ? `\n(Showing 20 of ${xbrlMetrics.length} rows)`
-                : '';
-            sections.push(`XBRL Metrics (${xbrlMetrics.length}):\n\n${table}${suffix}`);
+            const table = buildMarkdownTable(colNames, xbrlMetrics);
+            sections.push(`XBRL Metrics (${xbrlMetrics.length}):\n\n${table}`);
         }
         log('info', `Search returned ${resultCount} citations, ${xbrlMetrics.length} metrics`);
         return {
@@ -216,28 +562,448 @@ server.registerTool('etsquare_search', {
         };
     }
 });
-// Tool 3: Execute Metrics (XBRL structured data)
+// ─── Tool 3: Execute Metrics ────────────────────────────────────────────────
+server.registerTool('etsquare_financial_statements', {
+    title: 'Get Financial Statements',
+    description: 'Get canonical income statement, balance sheet, or cash flow statement for a company. ' +
+        'Assembles structured line items from XBRL facts with concept precedence and provenance.\n\n' +
+        'Each line item includes the selected XBRL concept, priority rank, and unit for auditability.\n\n' +
+        'Coverage: ~5,100 tickers for income statement and cash flow. ' +
+        'Balance sheet coverage is limited for some companies pending XBRL pipeline enhancement.\n\n' +
+        'For custom financial queries or peer comparisons, use etsquare_discover_metrics + etsquare_execute_metrics instead.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
+        statement_type: z.enum(['income_statement', 'balance_sheet', 'cash_flow'])
+            .describe('Which financial statement to return'),
+        period_mode: z.enum(['latest_annual', 'latest_quarterly', 'last_n_annual', 'last_n_quarterly'])
+            .default('last_n_annual')
+            .describe('Period selection: latest single period or last N periods'),
+        n_periods: z.number().min(1).max(20).default(5)
+            .describe('Number of periods for last_n modes (default: 5)'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        const result = await client.getFinancialStatement(input);
+        const periods = Array.isArray(result.periods) ? result.periods : [];
+        const lineOrder = Array.isArray(result.line_order) ? result.line_order : [];
+        const ticker = result.ticker || input.ticker.toUpperCase();
+        if (periods.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No ${input.statement_type.replace(/_/g, ' ')} data found for ${ticker}. ` +
+                            `The company may not have XBRL data available for the requested period.`,
+                    }],
+            };
+        }
+        // Format as markdown table
+        const labels = lineOrder.filter(label => {
+            return periods.some((p) => p.lines?.[label]?.value != null);
+        });
+        // Build header row
+        const periodHeaders = periods.map((p) => `FY${p.fiscal_year}${p.fiscal_period !== 'FY' ? ' ' + p.fiscal_period : ''}`);
+        const formatValue = (val, label) => {
+            if (val == null)
+                return '—';
+            if (label.startsWith('eps_'))
+                return val.toFixed(2);
+            if (label.startsWith('shares_'))
+                return (val / 1e6).toFixed(0) + 'M';
+            if (Math.abs(val) >= 1e9)
+                return (val / 1e9).toFixed(2) + 'B';
+            if (Math.abs(val) >= 1e6)
+                return (val / 1e6).toFixed(1) + 'M';
+            return val.toLocaleString();
+        };
+        const labelDisplay = (label) => label.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        let table = `## ${ticker} — ${input.statement_type.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase())}\n\n`;
+        table += `| Line Item | ${periodHeaders.join(' | ')} |\n`;
+        table += `|---|${periodHeaders.map(() => '---:').join('|')}|\n`;
+        for (const label of labels) {
+            const values = periods.map((p) => formatValue(p.lines?.[label]?.value, label));
+            table += `| ${labelDisplay(label)} | ${values.join(' | ')} |\n`;
+        }
+        // Add derived metrics (e.g., FCF)
+        const derivedKeys = new Set();
+        for (const p of periods) {
+            if (p.derived) {
+                for (const k of Object.keys(p.derived))
+                    derivedKeys.add(k);
+            }
+        }
+        if (derivedKeys.size > 0) {
+            table += `|---|${periodHeaders.map(() => '---:').join('|')}|\n`;
+            for (const dk of derivedKeys) {
+                const values = periods.map((p) => formatValue(p.derived?.[dk]?.value, dk));
+                table += `| **${labelDisplay(dk)}** | ${values.join(' | ')} |\n`;
+            }
+        }
+        // Provenance note
+        const firstPeriod = periods[0];
+        const sampleLine = firstPeriod?.lines?.[labels[0]];
+        if (sampleLine) {
+            table += `\n*Source: SEC XBRL filings. Concept precedence via VT_CF_XBRL_CONCEPT_FAMILIES.*`;
+        }
+        return {
+            content: [{ type: 'text', text: table }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Financial statement request failed: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('etsquare_insider_trades', {
+    title: 'Insider Trading Activity',
+    description: 'Get insider buying and selling activity for a company from SEC Form 3/4/5 filings. ' +
+        'Shows officer/director stock purchases, sales, option exercises, and tax withholdings.\n\n' +
+        'Data is sourced directly from SEC EDGAR ownership filings, filed within 2 business days of each transaction.\n\n' +
+        'Summary includes open-market buy/sell counts, net shares, and total values. ' +
+        'Derivative transactions (options, RSUs) are separated from open-market trades.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
+        days_back: z.number().min(1).max(730).default(90)
+            .describe('Days of history to return (default: 90)'),
+        transaction_types: z.array(z.string()).optional()
+            .describe('Filter by type: "P" (purchase), "S" (sale), "M" (exercise), "F" (tax withholding), "A" (award)'),
+        include_derivatives: z.boolean().default(true)
+            .describe('Include derivative transactions like options and RSUs (default: true)'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        const result = await client.getInsiderTransactions(input);
+        const transactions = Array.isArray(result.transactions) ? result.transactions : [];
+        const summary = result.summary || {};
+        const ticker = result.ticker || input.ticker.toUpperCase();
+        if (transactions.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No insider transactions found for ${ticker} in the last ${input.days_back || 90} days.`,
+                    }],
+            };
+        }
+        // Format summary
+        const fmtVal = (v) => {
+            if (v == null)
+                return '$0';
+            if (Math.abs(v) >= 1e9)
+                return `$${(v / 1e9).toFixed(1)}B`;
+            if (Math.abs(v) >= 1e6)
+                return `$${(v / 1e6).toFixed(1)}M`;
+            if (Math.abs(v) >= 1e3)
+                return `$${(v / 1e3).toFixed(0)}K`;
+            return `$${v.toFixed(0)}`;
+        };
+        let text = `## ${ticker} — Insider Trading (Last ${input.days_back || 90} Days)\n\n`;
+        // Summary line
+        const netLabel = (summary.net_shares_open_market ?? 0) >= 0 ? 'net buying' : 'net selling';
+        text += `**Open market**: ${summary.open_market_buys || 0} buys (${fmtVal(summary.total_buy_value)}) / `;
+        text += `${summary.open_market_sells || 0} sells (${fmtVal(summary.total_sell_value)})`;
+        if (summary.exercises)
+            text += ` | ${summary.exercises} exercises`;
+        if (summary.tax_withholdings)
+            text += ` | ${summary.tax_withholdings} tax withholdings`;
+        text += `\n\n`;
+        // Transaction table — show top 20
+        const shown = transactions.slice(0, 20);
+        text += `| Date | Insider | Title | Type | Shares | Price | Value |\n`;
+        text += `|------|---------|-------|------|-------:|------:|------:|\n`;
+        for (const t of shown) {
+            const shares = t.shares != null ? t.shares.toLocaleString() : '—';
+            const price = t.price_per_share != null ? `$${t.price_per_share.toFixed(2)}` : '—';
+            const value = t.total_value != null ? fmtVal(t.total_value) : '—';
+            const typeLabel = t.is_derivative ? `${t.transaction_type} *` : t.transaction_type;
+            text += `| ${t.transaction_date} | ${t.owner_name} | ${t.officer_title || '—'} | ${typeLabel} | ${shares} | ${price} | ${value} |\n`;
+        }
+        if (transactions.length > 20) {
+            text += `\n*Showing 20 of ${transactions.length} transactions.*\n`;
+        }
+        text += `\n*\\* = derivative transaction (options/RSUs). Source: SEC Form 4 filings via EDGAR.*`;
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Insider trades request failed: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('etsquare_institutional_holdings', {
+    title: 'Institutional Ownership (13F)',
+    description: 'Get institutional investor holdings for a company from SEC 13F filings. ' +
+        'Shows tracked managers holding the stock, their position sizes, and portfolio concentration.\n\n' +
+        'Data is from tracked institutional managers (top filers by AUM). ' +
+        'Coverage is partial — not all institutional holders are tracked. ' +
+        'Multiple rows per manager may appear due to sub-manager reporting. ' +
+        'Source: SEC EDGAR 13F-HR filings, filed quarterly.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "NVDA", "AAPL")'),
+        quarters: z.number().min(1).max(8).default(2)
+            .describe('Quarters of history (default: 2)'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        const result = await client.getInstitutionalHoldings(input);
+        const summary = result.summary || {};
+        const holdersByQuarter = result.holders_by_quarter || {};
+        const ticker = result.ticker || input.ticker.toUpperCase();
+        const quarters = Object.keys(holdersByQuarter).sort().reverse();
+        if (quarters.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No institutional holdings found for ${ticker} in tracked managers. ` +
+                            `The stock may not be held by the top institutional filers currently tracked.`,
+                    }],
+            };
+        }
+        const fmtVal = (v) => {
+            if (v == null)
+                return '—';
+            if (Math.abs(v) >= 1e12)
+                return `$${(v / 1e12).toFixed(1)}T`;
+            if (Math.abs(v) >= 1e9)
+                return `$${(v / 1e9).toFixed(1)}B`;
+            if (Math.abs(v) >= 1e6)
+                return `$${(v / 1e6).toFixed(1)}M`;
+            if (Math.abs(v) >= 1e3)
+                return `$${(v / 1e3).toFixed(0)}K`;
+            return `$${v.toFixed(0)}`;
+        };
+        let text = `## ${ticker} — Institutional Holders (13F)\n\n`;
+        text += `**Distinct tracked managers**: ${summary.distinct_tracked_managers || 0} | `;
+        text += `**Holder rows**: ${summary.holder_rows || 0} | `;
+        text += `**Tracked shares**: ${(summary.tracked_shares_held || 0).toLocaleString()} | `;
+        text += `**Tracked value**: ${fmtVal(summary.tracked_value_usd)}\n`;
+        text += `*${summary.coverage_note || 'Partial coverage — tracked managers only'}*\n\n`;
+        for (const q of quarters) {
+            const holders = holdersByQuarter[q] || [];
+            if (holders.length === 0)
+                continue;
+            text += `### ${q}\n\n`;
+            text += `| Manager | Shares | Value | Portfolio % | Discretion |\n`;
+            text += `|---------|-------:|------:|------------:|:-----------|\n`;
+            for (const h of holders.slice(0, 20)) {
+                const shares = h.shares != null ? h.shares.toLocaleString() : '—';
+                const value = fmtVal(h.value_usd);
+                const pct = h.portfolio_pct != null ? `${h.portfolio_pct.toFixed(2)}%` : '—';
+                const disc = h.investment_discretion || '—';
+                const label = h.manager_label || h.manager_name || '—';
+                text += `| ${label} | ${shares} | ${value} | ${pct} | ${disc} |\n`;
+            }
+            if (holders.length > 20) {
+                text += `\n*Showing 20 of ${holders.length} tracked holders.*\n`;
+            }
+            text += '\n';
+        }
+        text += `*Source: SEC 13F-HR filings via EDGAR. Tracked managers only — not full institutional ownership.*`;
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Institutional holdings request failed: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('etsquare_earnings_actuals', {
+    title: 'Earnings Actuals & Guidance',
+    description: 'Get issuer-reported earnings actuals and forward guidance for a company from SEC 8-K filings. ' +
+        'Extracts revenue, EPS (basic/diluted), and net income from Item 2.02 press releases.\n\n' +
+        'Values are deterministically extracted from exhibit press releases (EX-99.1) attached to 8-K filings. ' +
+        'Only explicit issuer-reported values are included — no analyst estimates or consensus.\n\n' +
+        'Guidance shows forward-looking ranges (low/high) when the issuer provides them.\n\n' +
+        'Coverage: ~1,900 tickers, most recent 1-2 quarters (Dec 2025 onward). ' +
+        'Historical depth is expanding — some tickers may have fewer quarters than requested.\n\n' +
+        'Source: SEC EDGAR 8-K Item 2.02 filings with attached press releases.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
+        quarters: z.number().min(1).max(20).default(4)
+            .describe('Quarters of history (default: 4)'),
+        metrics: z.array(z.string()).optional()
+            .describe('Filter metrics: "revenue", "diluted_eps", "basic_eps", "net_income"'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        const result = await client.getEarningsActuals(input);
+        const summary = result.summary || {};
+        const actuals = result.actuals || [];
+        const guidance = result.guidance || [];
+        const ticker = result.ticker || input.ticker.toUpperCase();
+        if (actuals.length === 0 && guidance.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No earnings actuals found for ${ticker}. ` +
+                            `Earnings data is extracted from 8-K Item 2.02 press releases — ` +
+                            `the company may not have earnings filings in the extracted dataset yet.`,
+                    }],
+            };
+        }
+        const fmtVal = (v, unit) => {
+            if (v == null)
+                return '—';
+            if (unit === 'USD_PER_SHARE')
+                return `$${v.toFixed(2)}`;
+            if (Math.abs(v) >= 1e12)
+                return `$${(v / 1e12).toFixed(1)}T`;
+            if (Math.abs(v) >= 1e9)
+                return `$${(v / 1e9).toFixed(2)}B`;
+            if (Math.abs(v) >= 1e6)
+                return `$${(v / 1e6).toFixed(1)}M`;
+            if (Math.abs(v) >= 1e3)
+                return `$${(v / 1e3).toFixed(0)}K`;
+            return `$${v.toFixed(0)}`;
+        };
+        let text = `## ${ticker} — Earnings Actuals\n\n`;
+        text += `**Metrics found**: ${summary.total_actuals || 0} actuals, ${summary.total_guidance || 0} guidance\n`;
+        if (summary.date_range?.earliest && summary.date_range?.latest) {
+            text += `**Period**: ${summary.date_range.earliest} to ${summary.date_range.latest}\n`;
+        }
+        text += '\n';
+        if (actuals.length > 0) {
+            text += `| Filing Date | Metric | Value | GAAP | FY | FQ | Confidence |\n`;
+            text += `|-------------|--------|------:|:----:|---:|---:|-----------:|\n`;
+            for (const a of actuals) {
+                const val = fmtVal(a.value, a.unit);
+                const gaap = a.gaap_flag || '—';
+                const fy = a.fiscal_year ?? '—';
+                const fq = a.fiscal_quarter ?? '—';
+                const conf = a.confidence != null ? `${(a.confidence * 100).toFixed(0)}%` : '—';
+                text += `| ${a.filing_date || '—'} | ${a.metric_name} | ${val} | ${gaap} | ${fy} | ${fq} | ${conf} |\n`;
+            }
+            text += '\n';
+        }
+        if (guidance.length > 0) {
+            text += `### Forward Guidance\n\n`;
+            text += `| Filing Date | Metric | Low | High | Midpoint | GAAP | Target FY | Target FQ |\n`;
+            text += `|-------------|--------|----:|-----:|---------:|:----:|----------:|----------:|\n`;
+            for (const g of guidance) {
+                const low = fmtVal(g.low_value, g.unit);
+                const high = fmtVal(g.high_value, g.unit);
+                const mid = g.midpoint != null ? fmtVal(g.midpoint, g.unit) : '—';
+                const gaap = g.gaap_flag || '—';
+                const fy = g.fiscal_year ?? '—';
+                const fq = g.fiscal_quarter ?? '—';
+                text += `| ${g.filing_date || '—'} | ${g.metric_name} | ${low} | ${high} | ${mid} | ${gaap} | ${fy} | ${fq} |\n`;
+            }
+            text += '\n';
+        }
+        text += `*Source: SEC 8-K Item 2.02 press releases — deterministic extraction from issuer filings.*`;
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Earnings actuals request failed: ${message}` }],
+            isError: true,
+        };
+    }
+});
 server.registerTool('etsquare_execute_metrics', {
     title: 'Execute Financial Metrics Query',
     description: 'Execute an XBRL metrics template by template_id to get structured financial data ' +
         '(numbers, ratios, time series). Returns tabular rows with columns like revenue, margins, EPS, etc.\n\n' +
-        'Common bind_params: p_ticker (company ticker), p_sic_code (industry), ' +
-        'p_start_year / p_end_year (time range, e.g., 2023-2025).',
+        'Common bind_params: p_tickers (comma-separated tickers), p_ticker (single ticker), p_sic_code (industry), ' +
+        'p_start_year / p_end_year (time range, e.g., 2023-2025).\n\n' +
+        'Use the tickers array to pass multiple companies — automatically joins as p_tickers comma-separated string.\n\n' +
+        'Set response_format="structured" for typed JSON with column metadata, visualization hints, and summary stats.',
     inputSchema: {
         template_id: z.string().min(10).describe('Template ID for metrics execution'),
         bind_params: z.record(z.unknown()).optional().describe('Template parameters as key-value pairs'),
         row_limit: z.number().min(1).max(500).optional().describe('Max rows to return (default: 100)'),
+        tickers: z.array(z.string()).max(5).optional()
+            .describe('Execute same template for multiple tickers and merge results. Overrides p_ticker in bind_params.'),
+        response_format: z.enum(['text', 'structured']).default('text')
+            .describe('"text" returns markdown table (default). "structured" returns JSON with column metadata and viz hints.'),
     },
 }, async (input) => {
     if (containsGuardrailBypass(input))
         return guardrailViolationResponse();
     try {
-        log('debug', 'Executing metrics template', { template_id: input.template_id });
-        const result = await client.executeMetrics(input);
-        const rows = result.rows || [];
-        const rowCount = result.row_count || rows.length;
-        const truncated = result.truncated || false;
-        const columns = result.columns || [];
+        log('debug', 'Executing metrics template', {
+            template_id: input.template_id,
+            tickers: input.tickers,
+        });
+        let rows = [];
+        let columns = [];
+        let rowCount = 0;
+        let truncated = false;
+        let vizHintFromApi = null;
+        // Multi-ticker: join as comma-separated p_tickers (single call)
+        // Templates use p_tickers (plural, comma-separated) for multi-company queries.
+        // Fallback: if p_tickers fails, try N parallel calls with p_ticker (singular).
+        if (input.tickers && input.tickers.length > 0) {
+            const joinedTickers = input.tickers.join(',');
+            const baseParams = { ...(input.bind_params || {}) };
+            // Remove any existing p_ticker — p_tickers takes precedence
+            delete baseParams.p_ticker;
+            try {
+                // Primary: single call with p_tickers (comma-separated)
+                const result = await client.executeMetrics({
+                    template_id: input.template_id,
+                    bind_params: { ...baseParams, p_tickers: joinedTickers },
+                    row_limit: input.row_limit,
+                });
+                rows = result.rows || [];
+                rowCount = result.row_count || rows.length;
+                truncated = result.truncated || false;
+                columns = result.columns || [];
+                vizHintFromApi = result.visualization_hint || null;
+            }
+            catch {
+                // Fallback: parallel calls with p_ticker (singular) per ticker
+                log('debug', 'p_tickers failed, falling back to parallel p_ticker calls');
+                const results = await Promise.allSettled(input.tickers.map(ticker => client.executeMetrics({
+                    template_id: input.template_id,
+                    bind_params: { ...baseParams, p_ticker: ticker },
+                    row_limit: input.row_limit,
+                })));
+                for (const res of results) {
+                    if (res.status === 'fulfilled' && res.value) {
+                        const val = res.value;
+                        if (Array.isArray(val.rows))
+                            rows.push(...val.rows);
+                        if (!columns.length && Array.isArray(val.columns))
+                            columns = val.columns;
+                        if (val.truncated)
+                            truncated = true;
+                        if (!vizHintFromApi)
+                            vizHintFromApi = val.visualization_hint || null;
+                    }
+                }
+                rowCount = rows.length;
+            }
+        }
+        else {
+            // Single execution
+            const result = await client.executeMetrics(input);
+            rows = result.rows || [];
+            rowCount = result.row_count || rows.length;
+            truncated = result.truncated || false;
+            columns = result.columns || [];
+            vizHintFromApi = result.visualization_hint || null;
+        }
         if (rowCount === 0) {
             return {
                 content: [{
@@ -246,21 +1012,31 @@ server.registerTool('etsquare_execute_metrics', {
                     }],
             };
         }
-        const colNames = columns.length > 0 ? columns.map((c) => c.name) : Object.keys(rows[0] || {});
-        const header = colNames.join(' | ');
-        const separator = colNames.map(() => '---').join(' | ');
-        const displayRows = rows.slice(0, 20);
-        const tableRows = displayRows.map((row) => colNames.map((col) => {
-            const val = row[col];
-            if (val === null || val === undefined)
-                return 'N/A';
-            if (typeof val === 'number')
-                return Number.isInteger(val) ? String(val) : val.toFixed(2);
-            return String(val);
-        }).join(' | '));
-        const table = [header, separator, ...tableRows].join('\n');
+        // ── Structured response path ──
+        if (input.response_format === 'structured') {
+            const columnMeta = buildColumnMeta(columns, rows);
+            // API-returned hint takes precedence over auto-derived
+            const autoHint = deriveMetricsVizHint(rows, { columns: columnMeta });
+            const colNames = columnMeta.map((c) => c.name);
+            const structured = {
+                template_id: input.template_id,
+                columns: columnMeta,
+                rows,
+                row_count: rowCount,
+                truncated,
+                visualization_hint: vizHintFromApi || autoHint,
+                summary_stats: computeSummaryStats(colNames, rows),
+            };
+            log('info', `Metrics query returned ${rowCount} rows [structured]`);
+            return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }] };
+        }
+        // ── Text response path (existing behavior) ──
+        const colNames = columns.length > 0
+            ? columns.map((c) => c.name)
+            : Object.keys(rows[0] || {});
+        const table = buildMarkdownTable(colNames, rows);
         const suffix = truncated || rows.length > 20
-            ? `\n\n(Showing ${displayRows.length} of ${rowCount} rows${truncated ? ', results truncated' : ''})`
+            ? `\n\n(Showing ${Math.min(rows.length, 20)} of ${rowCount} rows${truncated ? ', results truncated' : ''})`
             : '';
         log('info', `Metrics query returned ${rowCount} rows`);
         return {
@@ -278,18 +1054,24 @@ server.registerTool('etsquare_execute_metrics', {
         };
     }
 });
-// Tool 4: Discover Metrics Templates
+// ─── Tool 4: Discover Metrics Templates ─────────────────────────────────────
 server.registerTool('etsquare_discover_metrics', {
     title: 'Discover Financial Metrics Templates',
     description: 'Find available XBRL metrics templates by business question. ' +
         'Returns template IDs and metadata — use the template_id with etsquare_execute_metrics.\n\n' +
+        'Use this only for structured metrics such as revenue, gross margin, operating margin, EPS, debt, liquidity, or cash flow.\n\n' +
+        'Do not use this for narrative KPI questions like same-store sales, comparable sales, traffic, guest count, average check, or AUV. ' +
+        'For those, use etsquare_search in NARRATIVE mode instead.\n\n' +
         'Example: "revenue trend by quarter" → returns matching templates with their required bind_params.\n\n' +
-        'Workflow: discover_metrics → pick template_id → execute_metrics with bind_params.',
+        'Workflow: discover_metrics → pick template_id → execute_metrics with bind_params.\n\n' +
+        'Set response_format="structured" for JSON with similarity scores and visualization hints.',
     inputSchema: {
-        question: z.string().min(3).describe('Business question (e.g., "revenue trend by quarter", "profit margins comparison")'),
+        question: z.string().min(3).describe('Structured metrics question (e.g., "revenue trend by quarter", "gross margin trend", "EPS trend")'),
         scenario: z.enum(['snapshot', 'trends', 'peer_benchmark']).optional().describe('Filter by scenario type'),
         metric_family: z.string().optional().describe('Filter by metric family: REVENUE, EARNINGS, PROFITABILITY_MARGIN, LEVERAGE_DEBT, FREE_CASH_FLOW, LIQUIDITY'),
         max_results: z.number().min(1).max(10).default(5).optional().describe('Max templates to return'),
+        response_format: z.enum(['text', 'structured']).default('text')
+            .describe('"text" returns formatted list (default). "structured" returns JSON with scores and viz hints.'),
     },
 }, async (input) => {
     if (containsGuardrailBypass(input))
@@ -300,14 +1082,49 @@ server.registerTool('etsquare_discover_metrics', {
         const templates = Array.isArray(result.templates)
             ? result.templates
             : [];
+        const guidance = result.guidance && typeof result.guidance === 'object'
+            ? result.guidance
+            : null;
         if (templates.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `No metrics templates found for: "${input.question}"\nTry a different question or remove filters.`,
-                    }],
+            let text = `No structured metrics templates found for: "${input.question}"`;
+            if (guidance?.message) {
+                text += `\n${guidance.message}`;
+            }
+            if (guidance?.suggested_tool === 'etsquare_search') {
+                text += '\nRecommended next step: use etsquare_search with NARRATIVE mode.';
+            }
+            const examples = Array.isArray(guidance?.valid_metrics_examples)
+                ? guidance.valid_metrics_examples
+                : [];
+            if (examples.length > 0) {
+                text += `\nValid metrics examples: ${examples.join('; ')}`;
+            }
+            return { content: [{ type: 'text', text }] };
+        }
+        // ── Structured response path ──
+        if (input.response_format === 'structured') {
+            const structuredTemplates = templates.map((t, i) => ({
+                template_id: t.template_id,
+                name: t.title,
+                description: t.description,
+                recommended: i === 0,
+                similarity_score: t.similarity_score || null,
+                confidence_score: t.confidence_score || null,
+                scenario: t.scenario,
+                category: t.category,
+                required_params: t.required_params || {},
+                columns: t.columns || [],
+                visualization_hint: t.visualization_hint || null,
+            }));
+            const structured = {
+                question: result.question || input.question,
+                templates: structuredTemplates,
+                guidance: guidance || null,
             };
+            log('info', `Discovered ${templates.length} templates [structured]`);
+            return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }] };
         }
+        // ── Text response path (existing behavior) ──
         const formatted = templates
             .map((t, i) => {
             const lines = [
@@ -354,7 +1171,295 @@ server.registerTool('etsquare_discover_metrics', {
         };
     }
 });
-// Start server
+// ─── Tool 5: Get Full Chunk Text ────────────────────────────────────────────
+server.registerTool('etsquare_get_chunk', {
+    title: 'Get Full Chunk Text',
+    description: 'Fetch the full text for a specific search result chunk. ' +
+        'Use this when etsquare_search returns a truncated snippet and you need the complete chunk text. ' +
+        'Requires both chunk_id and execution_id from a prior search result.',
+    inputSchema: {
+        chunk_id: z.string().length(32).describe('Chunk ID from etsquare_search output'),
+        execution_id: z.string().min(32).describe('Execution ID from the etsquare_search response header'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Fetching full chunk text', { chunk_id: input.chunk_id });
+        const result = await client.getChunk(input);
+        const chunkText = typeof result.chunk_text === 'string'
+            ? result.chunk_text
+            : '';
+        const chunkLength = result.chunk_text_length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Chunk ${input.chunk_id}${typeof chunkLength === 'number' ? ` (${chunkLength} chars)` : ''}:\n\n${chunkText}`,
+                }],
+        };
+    }
+    catch (error) {
+        log('error', 'Chunk fetch failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Chunk fetch failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool 6: Get Chunk Context ──────────────────────────────────────────────
+server.registerTool('etsquare_get_chunk_context', {
+    title: 'Get Chunk Context',
+    description: 'Fetch the highlighted chunk plus surrounding context from the same filing section. ' +
+        'Use this when you need the paragraphs immediately before and after a search hit.',
+    inputSchema: {
+        chunk_id: z.string().length(32).describe('Chunk ID from etsquare_search output'),
+        neighbor_span: z.number().min(0).max(5).default(1).optional().describe('How many adjacent chunks to include before and after'),
+        window: z.number().min(200).max(4000).default(900).optional().describe('Approximate character budget for surrounding context'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Fetching chunk context', { chunk_id: input.chunk_id });
+        const result = await client.getChunkContext(input);
+        const filing = result.filing || {};
+        const context = result.context || {};
+        const navigation = result.navigation || {};
+        const lines = [
+            `Chunk ID: ${result.chunk_id || input.chunk_id}`,
+        ];
+        if (result.sec_url)
+            lines.push(`SEC URL: ${result.sec_url}`);
+        if (filing.ticker || filing.company) {
+            lines.push(`Filing: ${filing.ticker || 'N/A'} - ${filing.company || 'Unknown'} (${filing.form_type || filing.doc_subtype || 'N/A'})`);
+        }
+        if (filing.item_code || filing.accession_number) {
+            lines.push(`Section: ${filing.item_code || 'N/A'}${filing.accession_number ? ` | Accession: ${filing.accession_number}` : ''}`);
+        }
+        if (typeof navigation.chunk_position === 'number' || typeof navigation.total_chunks_in_item === 'number') {
+            lines.push(`Position: ${navigation.chunk_position ?? 'N/A'} of ${navigation.total_chunks_in_item ?? 'N/A'}`);
+        }
+        lines.push('');
+        if (context.before) {
+            lines.push('Before:');
+            lines.push(String(context.before));
+            lines.push('');
+        }
+        lines.push('Highlight:');
+        lines.push(String(context.highlight || ''));
+        if (context.after) {
+            lines.push('');
+            lines.push('After:');
+            lines.push(String(context.after));
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: lines.join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        log('error', 'Chunk context fetch failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Chunk context fetch failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool 7: Compare Companies ──────────────────────────────────────────────
+server.registerTool('etsquare_compare', {
+    title: 'Compare Companies in SEC Filings',
+    description: 'Compare 2-5 companies across SEC filings in a single call. ' +
+        'Returns per-ticker results grouped for easy side-by-side analysis.\n\n' +
+        'Resolve company names to tickers first with etsquare_lookup_company.\n\n' +
+        'Use mode_lock=HYBRID to include both narrative text and structured metrics.\n\n' +
+        'Always returns structured JSON (comparison results are inherently structured).',
+    inputSchema: {
+        tickers: z.array(z.string()).min(2).max(5)
+            .describe('Company tickers to compare (2-5). Resolve names first with etsquare_lookup_company.'),
+        query: z.string().min(3)
+            .describe('Comparison question (e.g., "revenue growth and risk factors", "tariff risk exposure")'),
+        mode_lock: z.enum(['NARRATIVE', 'HYBRID']).default('NARRATIVE')
+            .describe('HYBRID recommended for comparisons (gets both text and metrics)'),
+        top_k_per_ticker: z.number().int().min(1).max(10).default(3)
+            .describe('Narrative results per company'),
+        doc_types: z.array(z.string()).optional()
+            .describe('Limit by form type (e.g., ["10-k", "8-k"])'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Executing comparison', {
+            tickers: input.tickers,
+            query: input.query,
+            mode_lock: input.mode_lock,
+        });
+        const searchResult = await client.search({
+            query: input.query,
+            mode_lock: input.mode_lock,
+            scope_lock: 'COMPANY',
+            tickers: input.tickers,
+            top_k: input.top_k_per_ticker * input.tickers.length,
+            doc_types: input.doc_types,
+        });
+        const allResults = Array.isArray(searchResult.narrative_results)
+            ? searchResult.narrative_results
+            : [];
+        const xbrlMetrics = Array.isArray(searchResult.xbrl_metrics)
+            ? searchResult.xbrl_metrics
+            : [];
+        // Group results by ticker
+        const perTicker = {};
+        for (const ticker of input.tickers) {
+            perTicker[ticker] = allResults
+                .filter((r) => r.ticker === ticker)
+                .slice(0, input.top_k_per_ticker)
+                .map((r, i) => ({
+                index: i + 1,
+                chunk_id: r.chunk_id,
+                company_name: r.company_name,
+                form_type: r.form_type,
+                filing_date: r.filing_date,
+                item_code: r.item_code,
+                section_label: mapItemCodeToLabel(r.item_code),
+                score: r.similarity_score,
+                chunk_text: r.chunk_text,
+                truncated: r.chunk_text_truncated || false,
+                accession_number: r.accession_number,
+                sec_url: r.sec_url,
+            }));
+        }
+        const hasMetrics = xbrlMetrics.length > 0;
+        const metricsColumnMeta = hasMetrics
+            ? buildColumnMeta(searchResult.xbrl_output_schema?.columns || [], xbrlMetrics)
+            : null;
+        const response = {
+            comparison: {
+                tickers: input.tickers,
+                query: input.query,
+                per_ticker: perTicker,
+                metrics: hasMetrics ? {
+                    rows: xbrlMetrics,
+                    columns: metricsColumnMeta,
+                    visualization_hint: deriveMetricsVizHint(xbrlMetrics, { columns: metricsColumnMeta }),
+                } : null,
+            },
+            layout_hint: {
+                suggested: hasMetrics ? 'comparison_dashboard' : 'comparison_grid',
+                reason: 'multi_ticker_compare',
+                panels: hasMetrics
+                    ? ['metrics_chart', 'narrative_side_by_side']
+                    : ['narrative_side_by_side'],
+                tone: 'comparative',
+            },
+            search_context: buildSearchContext(searchResult, input.query),
+        };
+        const tickerCounts = input.tickers
+            .map(t => `${t}: ${perTicker[t]?.length || 0}`)
+            .join(', ');
+        log('info', `Compare returned results: ${tickerCounts}, ${xbrlMetrics.length} metrics`);
+        return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
+    }
+    catch (error) {
+        log('error', 'Compare failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Compare failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool 8: Weekly Brief ───────────────────────────────────────────────────
+server.registerTool('etsquare_weekly_brief', {
+    title: 'Weekly SEC Filing Intelligence Brief',
+    description: 'Get the latest weekly SEC filing intelligence brief. ' +
+        'Returns notable 8-K events, edge signals (unusual filings), and sector heatmap. ' +
+        'Updated weekly. Great for market monitoring and identifying emerging risks.\n\n' +
+        'Default response_format is "structured" (full JSON). Use "text" for readable summary.',
+    inputSchema: {
+        sections: z.array(z.enum(['notable', 'edge_signals', 'heatmap', 'methodology'])).optional()
+            .describe('Filter to specific sections. Returns all if omitted.'),
+        response_format: z.enum(['text', 'structured']).default('structured')
+            .describe('"structured" returns full JSON (default). "text" returns a readable summary.'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Fetching weekly brief', { sections: input.sections });
+        const brief = await client.weeklyBrief();
+        if (!brief || (!brief.notable && !brief.edge_signals)) {
+            return { content: [{ type: 'text', text: 'No weekly brief available for the current period.' }] };
+        }
+        // Client-side section filtering
+        let output = brief;
+        if (input.sections && input.sections.length > 0) {
+            output = {
+                week_start: brief.week_start,
+                week_end: brief.week_end,
+                generated_at: brief.generated_at,
+            };
+            if (input.sections.includes('notable'))
+                output.notable = brief.notable;
+            if (input.sections.includes('edge_signals'))
+                output.edge_signals = brief.edge_signals;
+            if (input.sections.includes('heatmap'))
+                output.heatmap = brief.heatmap;
+            if (input.sections.includes('methodology'))
+                output.methodology = brief.methodology;
+        }
+        // ── Structured response path ──
+        if (input.response_format === 'structured') {
+            log('info', `Weekly brief returned: ${(brief.notable || []).length} notable, ${(brief.edge_signals || []).length} edge signals`);
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        // ── Text response path ──
+        const lines = [];
+        lines.push(`SEC Weekly Brief: ${brief.week_start || 'N/A'} to ${brief.week_end || 'N/A'}`);
+        lines.push(`Generated: ${brief.generated_at || 'N/A'}`);
+        lines.push('');
+        if (output.notable?.length) {
+            lines.push(`Notable Filings (${output.notable.length}):`);
+            for (const n of output.notable) {
+                lines.push(`  ${n.ticker || 'N/A'} — ${n.company_name || 'Unknown'} (${n.form_type || ''} Item ${n.item_code || ''})`);
+                lines.push(`    Filed: ${n.filed || 'N/A'} | Score: ${n.score_notable || 'N/A'}`);
+                if (n.summary)
+                    lines.push(`    ${n.summary}`);
+                if (n.sec_url)
+                    lines.push(`    ${n.sec_url}`);
+                lines.push('');
+            }
+        }
+        if (output.edge_signals?.length) {
+            lines.push(`Edge Signals (${output.edge_signals.length}):`);
+            for (const e of output.edge_signals) {
+                lines.push(`  ${e.ticker || 'N/A'} — ${e.company_name || 'Unknown'}`);
+                if (e.signal_reason)
+                    lines.push(`    ${e.signal_reason}`);
+                if (e.citation)
+                    lines.push(`    Verbatim: "${e.citation}"`);
+                lines.push('');
+            }
+        }
+        if (output.heatmap?.length) {
+            lines.push(`Sector Heatmap (${output.heatmap.length} sectors):`);
+            for (const h of output.heatmap) {
+                lines.push(`  ${h.sector || h.sic_description || 'N/A'}: ${h.filing_count || h.count || 0} filings`);
+            }
+        }
+        log('info', `Weekly brief returned: ${(brief.notable || []).length} notable, ${(brief.edge_signals || []).length} edge signals`);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        log('error', 'Weekly brief fetch failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Weekly brief unavailable: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Start Server ───────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-log('info', 'ETSquare MCP Server ready and listening on stdio');
+log('info', 'ETSquare MCP Server v0.3.0 ready and listening on stdio (8 tools)');