@mcp-consultant-tools/log-analytics 20.0.0-beta.3 → 28.0.0-beta.1

package/build/index.js

@@ -5,7 +5,8 @@ import { realpathSync } from "node:fs";
 import { createMcpServer, createEnvLoader } from "@mcp-consultant-tools/core";
 import { LogAnalyticsService } from "./LogAnalyticsService.js";
 import { z } from 'zod';
-import { formatTableAsMarkdown, analyzeLogs, analyzeFunctionLogs, analyzeFunctionErrors, analyzeFunctionStats, generateRecommendations } from './utils/loganalytics-formatters.js';
+import { formatTableAsMarkdown, analyzeLogs, analyzeFunctionLogs, analyzeFunctionErrors, analyzeFunctionStats, generateRecommendations, filterColumns, resolveColumnPreset, } from './utils/loganalytics-formatters.js';
+import { descWithExamples, KQL_EXAMPLES, TIMESPAN_EXAMPLES, COLUMN_PRESET_EXAMPLES, TABLE_NAME_EXAMPLES, APP_NAME_EXAMPLES, OUTPUT_FORMAT_EXAMPLES, SEVERITY_EXAMPLES, } from './tool-examples.js';
 export function registerLogAnalyticsTools(server, loganalyticsService) {
     let service = loganalyticsService || null;
     function getLogAnalyticsService() {
@@ -338,17 +339,34 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-execute-query", "Execute a custom KQL query against Log Analytics workspace", {
         resourceId: z.string().describe("Resource ID"),
-        query: z.string().describe("KQL query string"),
-        timespan: z.string().optional().describe("Time range (e.g., 'PT1H', 'P1D')"),
-    }, async ({ resourceId, query, timespan }) => {
+        query: z.string().describe(descWithExamples("KQL query string", KQL_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results. 'minimal' reduces token count significantly", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset). E.g., ['TimeGenerated', 'Message']"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, query, timespan, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.executeQuery(resourceId, query, timespan);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -396,18 +414,35 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-get-recent-events", "Get recent events from a specific Log Analytics table", {
         resourceId: z.string().describe("Resource ID"),
-        tableName: z.string().describe("Table name (e.g., 'FunctionAppLogs', 'traces', 'requests')"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
+        tableName: z.string().describe(descWithExamples("Table name to query", TABLE_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
         limit: z.number().optional().describe("Maximum number of results (default: 100)"),
-    }, async ({ resourceId, tableName, timespan, limit }) => {
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset)"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, tableName, timespan, limit, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.getRecentEvents(resourceId, tableName, timespan || 'PT1H', limit || 100);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -427,19 +462,36 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-search-logs", "Search logs by text content across tables or a specific table", {
         resourceId: z.string().describe("Resource ID"),
-        searchText: z.string().describe("Text to search for"),
-        tableName: z.string().optional().describe("Table name to search in (optional, searches all if not specified)"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
+        searchText: z.string().describe("Text to search for (case-insensitive)"),
+        tableName: z.string().optional().describe(descWithExamples("Table name to search in (optional, searches all if not specified)", TABLE_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
         limit: z.number().optional().describe("Maximum number of results (default: 100)"),
-    }, async ({ resourceId, searchText, tableName, timespan, limit }) => {
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset)"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, searchText, tableName, timespan, limit, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.searchLogs(resourceId, searchText, tableName, timespan || 'PT1H', limit || 100);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -459,19 +511,36 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-get-function-logs", "Get Azure Function logs from FunctionAppLogs table with optional filtering", {
         resourceId: z.string().describe("Resource ID"),
-        functionName: z.string().optional().describe("Function name to filter by (optional)"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
-        severityLevel: z.number().optional().describe("Minimum severity level (0=Verbose, 1=Info, 2=Warning, 3=Error, 4=Critical)"),
+        functionName: z.string().optional().describe(descWithExamples("Function name to filter by (optional)", APP_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
+        severityLevel: z.number().optional().describe(descWithExamples("Minimum severity level", SEVERITY_EXAMPLES)),
         limit: z.number().optional().describe("Maximum number of results (default: 100)"),
-    }, async ({ resourceId, functionName, timespan, severityLevel, limit }) => {
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset)"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, functionName, timespan, severityLevel, limit, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.getFunctionLogs(resourceId, functionName, timespan || 'PT1H', severityLevel, limit || 100);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -491,18 +560,35 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-get-function-errors", "Get Azure Function error logs with exception details", {
         resourceId: z.string().describe("Resource ID"),
-        functionName: z.string().optional().describe("Function name to filter by (optional)"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
+        functionName: z.string().optional().describe(descWithExamples("Function name to filter by (optional)", APP_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
         limit: z.number().optional().describe("Maximum number of results (default: 100)"),
-    }, async ({ resourceId, functionName, timespan, limit }) => {
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset)"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, functionName, timespan, limit, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.getFunctionErrors(resourceId, functionName, timespan || 'PT1H', limit || 100);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -520,14 +606,23 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
             };
         }
     });
-    server.tool("loganalytics-get-function-stats", "Get execution statistics for Azure Functions (count, success rate, errors)", {
+    server.tool("loganalytics-get-function-stats", "Get execution statistics for Azure Functions (count, success rate, errors). Returns aggregated data - no column filtering needed.", {
         resourceId: z.string().describe("Resource ID"),
-        functionName: z.string().optional().describe("Function name (optional, returns stats for all functions if not specified)"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
-    }, async ({ resourceId, functionName, timespan }) => {
+        functionName: z.string().optional().describe(descWithExamples("Function name (optional, returns stats for all functions if not specified)", APP_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, functionName, timespan, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.getFunctionStats(resourceId, functionName, timespan || 'PT1H');
+            // Format output
+            if (outputFormat === 'markdown' && result.tables && result.tables.length > 0) {
+                const markdown = result.tables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
@@ -552,18 +647,35 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
     });
     server.tool("loganalytics-get-function-invocations", "Get Azure Function invocation history from requests/traces tables", {
         resourceId: z.string().describe("Resource ID"),
-        functionName: z.string().optional().describe("Function name to filter by (optional)"),
-        timespan: z.string().optional().describe("Time range (default: PT1H)"),
+        functionName: z.string().optional().describe(descWithExamples("Function name to filter by (optional)", APP_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
         limit: z.number().optional().describe("Maximum number of results (default: 100)"),
-    }, async ({ resourceId, functionName, timespan, limit }) => {
+        columnPreset: z.enum(["minimal", "investigation", "full"]).optional()
+            .describe(descWithExamples("Column preset for filtering results", COLUMN_PRESET_EXAMPLES)),
+        columns: z.array(z.string()).optional()
+            .describe("Custom columns to include (overrides columnPreset)"),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: json)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, functionName, timespan, limit, columnPreset, columns, outputFormat }) => {
         try {
             const service = getLogAnalyticsService();
             const result = await service.getFunctionInvocations(resourceId, functionName, timespan || 'PT1H', limit || 100);
+            // Apply column filtering
+            const columnsToInclude = resolveColumnPreset(columnPreset, columns);
+            const filteredTables = result.tables.map((t) => filterColumns(t, columnsToInclude));
+            const filteredResult = { ...result, tables: filteredTables };
+            // Format output
+            if (outputFormat === 'markdown' && filteredTables.length > 0) {
+                const markdown = filteredTables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: JSON.stringify(filteredResult, null, 2),
                     },
                 ],
             };
@@ -581,8 +693,466 @@ export function registerLogAnalyticsTools(server, loganalyticsService) {
             };
         }
     });
-    console.error("log-analytics tools registered: 10 tools, 4 prompts");
-    console.error("Log Analytics tools registered: 10 tools, 4 prompts");
+    // ========================================
+    // NEW INVESTIGATION TOOLS
+    // ========================================
+    server.tool("loganalytics-get-error-summary", "Get aggregated error summary by type - ideal for starting investigations. Returns counts, first/last seen, and sample messages.", {
+        resourceId: z.string().describe("Resource ID"),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
+        tableName: z.enum(["AppExceptions", "AppTraces", "FunctionAppLogs"]).optional()
+            .describe("Table to analyze (default: AppExceptions)"),
+        minCount: z.number().optional().describe("Minimum error count to include (default: 1)"),
+        deduplicateRetries: z.boolean().optional()
+            .describe("Group by OperationId to deduplicate retry attempts (default: true). Shows UniqueErrors count and total RetryCount."),
+        outputFormat: z.enum(["json", "markdown"]).optional()
+            .describe(descWithExamples("Output format (default: markdown for readability)", OUTPUT_FORMAT_EXAMPLES)),
+    }, async ({ resourceId, timespan, tableName, minCount, deduplicateRetries, outputFormat }) => {
+        try {
+            const service = getLogAnalyticsService();
+            const table = tableName || 'AppExceptions';
+            const timespanValue = timespan || 'PT1H';
+            const minCountValue = minCount || 1;
+            const dedupe = deduplicateRetries !== false; // default true
+            // Build aggregation query based on table type
+            let query;
+            if (table === 'AppExceptions') {
+                if (dedupe) {
+                    // Two-stage aggregation: first by OperationId to dedupe retries, then by error type
+                    query = `
+              AppExceptions
+              | summarize
+                  RetryCount = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(OuterMessage)
+                by OperationId, ExceptionType, AppRoleName
+              | summarize
+                  UniqueErrors = count(),
+                  TotalRetries = sum(RetryCount),
+                  FirstSeen = min(FirstSeen),
+                  LastSeen = max(LastSeen),
+                  SampleMessage = take_any(SampleMessage)
+                by ExceptionType, AppRoleName
+              | where UniqueErrors >= ${minCountValue}
+              | order by UniqueErrors desc
+            `;
+                }
+                else {
+                    query = `
+              AppExceptions
+              | summarize
+                  Count = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(OuterMessage)
+                by ExceptionType, AppRoleName
+              | where Count >= ${minCountValue}
+              | order by Count desc
+            `;
+                }
+            }
+            else if (table === 'AppTraces') {
+                if (dedupe) {
+                    query = `
+              AppTraces
+              | where SeverityLevel >= 3
+              | summarize
+                  RetryCount = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(Message)
+                by OperationId, AppRoleName, SeverityLevel
+              | summarize
+                  UniqueErrors = count(),
+                  TotalRetries = sum(RetryCount),
+                  FirstSeen = min(FirstSeen),
+                  LastSeen = max(LastSeen),
+                  SampleMessage = take_any(SampleMessage)
+                by AppRoleName, SeverityLevel
+              | where UniqueErrors >= ${minCountValue}
+              | order by UniqueErrors desc
+            `;
+                }
+                else {
+                    query = `
+              AppTraces
+              | where SeverityLevel >= 3
+              | summarize
+                  Count = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(Message)
+                by AppRoleName, SeverityLevel
+              | where Count >= ${minCountValue}
+              | order by Count desc
+            `;
+                }
+            }
+            else {
+                // FunctionAppLogs - no OperationId, use InvocationId instead
+                if (dedupe) {
+                    query = `
+              FunctionAppLogs
+              | where ExceptionDetails != ''
+              | summarize
+                  RetryCount = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(Message)
+                by InvocationId, FunctionName
+              | summarize
+                  UniqueErrors = count(),
+                  TotalRetries = sum(RetryCount),
+                  FirstSeen = min(FirstSeen),
+                  LastSeen = max(LastSeen),
+                  SampleMessage = take_any(SampleMessage)
+                by FunctionName
+              | where UniqueErrors >= ${minCountValue}
+              | order by UniqueErrors desc
+            `;
+                }
+                else {
+                    query = `
+              FunctionAppLogs
+              | where ExceptionDetails != ''
+              | summarize
+                  Count = count(),
+                  FirstSeen = min(TimeGenerated),
+                  LastSeen = max(TimeGenerated),
+                  SampleMessage = take_any(Message)
+                by FunctionName
+              | where Count >= ${minCountValue}
+              | order by Count desc
+            `;
+                }
+            }
+            const result = await service.executeQuery(resourceId, query, timespanValue);
+            // Default to markdown for this aggregation tool
+            const format = outputFormat || 'markdown';
+            if (format === 'markdown' && result.tables && result.tables.length > 0) {
+                const dedupeNote = dedupe ? ' (deduplicated by OperationId)' : '';
+                const markdown = `## Error Summary (${table})${dedupeNote}\n\n**Time range:** ${timespanValue}\n\n` +
+                    result.tables.map((t) => formatTableAsMarkdown(t)).join('\n\n');
+                return {
+                    content: [{ type: "text", text: markdown }],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error("Error getting error summary:", error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to get error summary: ${error.message}`,
+                    },
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("loganalytics-investigate-app", "Combined investigation tool: searches AppTraces + AppExceptions, returns summary + recent error details. Best starting point for app investigations.", {
+        resourceId: z.string().describe("Resource ID"),
+        appNamePattern: z.string().optional().describe(descWithExamples("Filter by app name (searches AppRoleName). Partial match supported.", APP_NAME_EXAMPLES)),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT1H)", TIMESPAN_EXAMPLES)),
+        includeDetails: z.boolean().optional().describe("Include recent error details (default: true)"),
+        detailsLimit: z.number().optional().describe("Max recent errors to include (default: 20)"),
+        deduplicateRetries: z.boolean().optional()
+            .describe("Group by OperationId to deduplicate retry attempts (default: true)"),
+    }, async ({ resourceId, appNamePattern, timespan, includeDetails, detailsLimit, deduplicateRetries }) => {
+        try {
+            const service = getLogAnalyticsService();
+            const timespanValue = timespan || 'PT1H';
+            const showDetails = includeDetails !== false;
+            const limit = detailsLimit || 20;
+            const dedupe = deduplicateRetries !== false; // default true
+            const appFilter = appNamePattern
+                ? `| where AppRoleName contains "${appNamePattern}"`
+                : '';
+            // Query 1: Exception summary (with optional deduplication)
+            const exceptionSummaryQuery = dedupe ? `
+          AppExceptions
+          ${appFilter}
+          | summarize
+              RetryCount = count(),
+              FirstSeen = min(TimeGenerated),
+              LastSeen = max(TimeGenerated)
+            by OperationId, ExceptionType, AppRoleName
+          | summarize
+              UniqueErrors = count(),
+              TotalRetries = sum(RetryCount),
+              FirstSeen = min(FirstSeen),
+              LastSeen = max(LastSeen)
+            by ExceptionType, AppRoleName
+          | order by UniqueErrors desc
+          | take 20
+        ` : `
+          AppExceptions
+          ${appFilter}
+          | summarize
+              Count = count(),
+              FirstSeen = min(TimeGenerated),
+              LastSeen = max(TimeGenerated)
+            by ExceptionType, AppRoleName
+          | order by Count desc
+          | take 20
+        `;
+            // Query 2: Trace severity distribution (with optional deduplication)
+            const traceSeverityQuery = dedupe ? `
+          AppTraces
+          ${appFilter}
+          | summarize RetryCount = count() by OperationId, SeverityLevel, AppRoleName
+          | summarize UniqueTraces = count(), TotalCount = sum(RetryCount) by SeverityLevel, AppRoleName
+          | order by SeverityLevel desc
+        ` : `
+          AppTraces
+          ${appFilter}
+          | summarize Count = count() by SeverityLevel, AppRoleName
+          | order by SeverityLevel desc
+        `;
+            // Query 3: Recent errors - deduplicated by showing one per OperationId
+            const recentErrorsQuery = showDetails ? (dedupe ? `
+          AppExceptions
+          ${appFilter}
+          | summarize
+              TimeGenerated = max(TimeGenerated),
+              RetryCount = count(),
+              OuterMessage = take_any(OuterMessage)
+            by OperationId, AppRoleName, ExceptionType
+          | project TimeGenerated, AppRoleName, ExceptionType, OuterMessage, RetryCount
+          | order by TimeGenerated desc
+          | take ${limit}
+        ` : `
+          AppExceptions
+          ${appFilter}
+          | project TimeGenerated, AppRoleName, ExceptionType, OuterMessage
+          | order by TimeGenerated desc
+          | take ${limit}
+        `) : null;
+            // Execute queries
+            const [exceptionSummary, traceSeverity, recentErrors] = await Promise.all([
+                service.executeQuery(resourceId, exceptionSummaryQuery, timespanValue),
+                service.executeQuery(resourceId, traceSeverityQuery, timespanValue),
+                recentErrorsQuery ? service.executeQuery(resourceId, recentErrorsQuery, timespanValue) : null,
+            ]);
+            // Build markdown report
+            let markdown = `# App Investigation Report\n\n`;
+            markdown += `**Filter:** ${appNamePattern || '(all apps)'}\n`;
+            markdown += `**Time range:** ${timespanValue}\n`;
+            markdown += dedupe ? `**Deduplication:** enabled (grouped by OperationId)\n\n` : '\n';
+            markdown += `## Exception Summary\n\n`;
+            if (exceptionSummary.tables && exceptionSummary.tables.length > 0 && exceptionSummary.tables[0].rows.length > 0) {
+                markdown += formatTableAsMarkdown(exceptionSummary.tables[0]);
+            }
+            else {
+                markdown += '*No exceptions found*';
+            }
+            markdown += '\n\n';
+            markdown += `## Trace Severity Distribution\n\n`;
+            if (traceSeverity.tables && traceSeverity.tables.length > 0 && traceSeverity.tables[0].rows.length > 0) {
+                markdown += formatTableAsMarkdown(traceSeverity.tables[0]);
+            }
+            else {
+                markdown += '*No traces found*';
+            }
+            markdown += '\n\n';
+            if (showDetails && recentErrors) {
+                markdown += `## Recent Errors (${limit} max)\n\n`;
+                if (recentErrors.tables && recentErrors.tables.length > 0 && recentErrors.tables[0].rows.length > 0) {
+                    markdown += formatTableAsMarkdown(recentErrors.tables[0]);
+                }
+                else {
+                    markdown += '*No recent errors*';
+                }
+            }
+            return {
+                content: [{ type: "text", text: markdown }],
+            };
+        }
+        catch (error) {
+            console.error("Error investigating app:", error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to investigate app: ${error.message}`,
+                    },
+                ],
+                isError: true
+            };
+        }
+    });
+    server.tool("loganalytics-investigate-sync", "Investigate SmartConnectorCloud (SCC) sync failures. Only useful for clients using SmartConnectorCloud. Auto-derives sync app name from workspace ID (log-{env}-{client}-... → func-{env}-{client}-sc-sync-...). Best tool for SCC sync debugging.", {
+        resourceId: z.string().describe("Resource ID (e.g., 'log-dev-rtpi-uks-01'). Environment and client are auto-extracted."),
+        timespan: z.string().optional().describe(descWithExamples("Time range (default: PT8H - typical work day)", TIMESPAN_EXAMPLES)),
+        includeDetails: z.boolean().optional().describe("Include recent error details (default: true)"),
+        detailsLimit: z.number().optional().describe("Max recent errors to include (default: 10)"),
+    }, async ({ resourceId, timespan, includeDetails, detailsLimit }) => {
+        try {
+            const service = getLogAnalyticsService();
+            const timespanValue = timespan || 'PT8H';
+            const showDetails = includeDetails !== false;
+            const limit = detailsLimit || 10;
+            // Parse resourceId to extract environment and client
+            // Pattern: log-{environment}-{client}-...
+            const match = resourceId.match(/^log-([^-]+)-([^-]+)/);
+            if (!match) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Could not parse environment/client from resourceId '${resourceId}'. Expected format: log-{environment}-{client}-...`,
+                        }],
+                    isError: true,
+                };
+            }
+            const environment = match[1];
+            const client = match[2];
+            const syncAppPattern = `func-${environment}-${client}-sc-sync`;
+            // Query 1: Error summary by FunctionName (deduplicated)
+            // FunctionName is in Properties.AzureFunctions_FunctionName
+            const errorsByFunctionQuery = `
+          AppExceptions
+          | where AppRoleName contains "${syncAppPattern}"
+          | extend FunctionName = tostring(Properties.AzureFunctions_FunctionName)
+          | summarize
+              RetryCount = count(),
+              FirstSeen = min(TimeGenerated),
+              LastSeen = max(TimeGenerated),
+              SampleMessage = take_any(OuterMessage)
+            by OperationId, FunctionName, ExceptionType
+          | summarize
+              UniqueErrors = count(),
+              TotalRetries = sum(RetryCount),
+              FirstSeen = min(FirstSeen),
+              LastSeen = max(LastSeen),
+              SampleMessage = take_any(SampleMessage)
+            by FunctionName, ExceptionType
+          | order by UniqueErrors desc
+        `;
+            // Query 2: Error category summary (Dataverse, ServiceBus, SQL, etc.)
+            const errorCategoryQuery = `
+          AppExceptions
+          | where AppRoleName contains "${syncAppPattern}"
+          | extend ErrorCategory = case(
+              ExceptionType contains "FaultException" or ExceptionType contains "OrganizationService", "Dataverse",
+              ExceptionType contains "ServiceBus", "ServiceBus",
+              ExceptionType contains "Sql", "Database",
+              ExceptionType contains "Timeout", "Timeout",
+              ExceptionType contains "Socket" or ExceptionType contains "Http", "Network",
+              "Other"
+            )
+          | summarize
+              RetryCount = count(),
+              UniqueOps = dcount(OperationId)
+            by ErrorCategory
+          | order by UniqueOps desc
+        `;
+            // Query 3: Recent errors with details (deduplicated)
+            const recentErrorsQuery = showDetails ? `
+          AppExceptions
+          | where AppRoleName contains "${syncAppPattern}"
+          | extend FunctionName = tostring(Properties.AzureFunctions_FunctionName)
+          | summarize
+              TimeGenerated = max(TimeGenerated),
+              RetryCount = count(),
+              OuterMessage = take_any(OuterMessage)
+            by OperationId, FunctionName, ExceptionType
+          | project TimeGenerated, FunctionName, ExceptionType, OuterMessage, RetryCount
+          | order by TimeGenerated desc
+          | take ${limit}
+        ` : null;
+            // Query 4: Severity 3 (Error) traces for additional context
+            const errorTracesQuery = `
+          AppTraces
+          | where AppRoleName contains "${syncAppPattern}"
+          | where SeverityLevel >= 3
+          | summarize
+              RetryCount = count()
+            by OperationId, Message
+          | summarize
+              UniqueErrors = count(),
+              TotalCount = sum(RetryCount)
+            by Message
+          | order by UniqueErrors desc
+          | take 10
+        `;
+            // Execute queries in parallel
+            const [errorsByFunction, errorCategory, recentErrors, errorTraces] = await Promise.all([
+                service.executeQuery(resourceId, errorsByFunctionQuery, timespanValue),
+                service.executeQuery(resourceId, errorCategoryQuery, timespanValue),
+                recentErrorsQuery ? service.executeQuery(resourceId, recentErrorsQuery, timespanValue) : null,
+                service.executeQuery(resourceId, errorTracesQuery, timespanValue),
+            ]);
+            // Build markdown report
+            let markdown = `# SmartConnector Sync Investigation\n\n`;
+            markdown += `**Environment:** ${environment}\n`;
+            markdown += `**Client:** ${client}\n`;
+            markdown += `**Sync App:** ${syncAppPattern}-*\n`;
+            markdown += `**Time range:** ${timespanValue}\n`;
+            markdown += `**Deduplication:** enabled (grouped by OperationId)\n\n`;
+            // Error category summary (quick overview)
+            markdown += `## Error Categories\n\n`;
+            if (errorCategory.tables?.[0]?.rows?.length > 0) {
+                markdown += formatTableAsMarkdown(errorCategory.tables[0]);
+            }
+            else {
+                markdown += '*No errors found* ✅';
+            }
+            markdown += '\n\n';
+            // Errors by function (which sync operations are failing?)
+            markdown += `## Errors by Sync Operation\n\n`;
+            if (errorsByFunction.tables?.[0]?.rows?.length > 0) {
+                markdown += formatTableAsMarkdown(errorsByFunction.tables[0]);
+            }
+            else {
+                markdown += '*No errors found* ✅';
+            }
+            markdown += '\n\n';
+            // Error traces (additional context from logs)
+            markdown += `## Error Traces (Severity 3+)\n\n`;
+            if (errorTraces.tables?.[0]?.rows?.length > 0) {
+                markdown += formatTableAsMarkdown(errorTraces.tables[0]);
+            }
+            else {
+                markdown += '*No error traces found*';
+            }
+            markdown += '\n\n';
+            // Recent errors with details
+            if (showDetails && recentErrors) {
+                markdown += `## Recent Errors (${limit} max)\n\n`;
+                if (recentErrors.tables?.[0]?.rows?.length > 0) {
+                    markdown += formatTableAsMarkdown(recentErrors.tables[0]);
+                }
+                else {
+                    markdown += '*No recent errors*';
+                }
+            }
+            return {
+                content: [{ type: "text", text: markdown }],
+            };
+        }
+        catch (error) {
+            console.error("Error investigating sync:", error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to investigate sync: ${error.message}`,
+                    },
+                ],
+                isError: true
+            };
+        }
+    });
+    console.error("Log Analytics tools registered: 13 tools, 4 prompts");
 }
 // CLI entry point (standalone execution)
 // Uses realpathSync to resolve symlinks created by npx