namespace PerformanceMonitorLite.Mcp;

/// <summary>
/// Server instructions sent to MCP clients during initialization.
/// Provides context about tool usage, data characteristics, and diagnostic workflows.
/// </summary>
internal static class McpInstructions
{
    public const string Text = """
        You are connected to a SQL Server performance monitoring tool via Performance Monitor Lite.

        ## CRITICAL: Read-Only Access

        This MCP server provides STRICTLY READ-ONLY access to previously collected performance data. You CANNOT:
        - Execute arbitrary SQL queries against any server
        - Kill sessions, processes, or connections
        - Change any server configuration or settings
        - Modify, insert, or delete any data
        - Run any ad-hoc diagnostics beyond what the collectors have already captured

        If a user asks "what's locking table X right now?" or "run this query," you can only answer from what the collectors have already captured. You cannot run live queries. Be upfront about this limitation.

        ## How Data Is Collected

        Performance Monitor Lite collects data from remote SQL Server instances and stores it locally in DuckDB/Parquet files. Data is collected in snapshots at regular intervals (typically every 1-15 minutes depending on the collector). This means:

        - Data is only as fresh as the last collection cycle. If a collector last ran 10 minutes ago, you're seeing 10-minute-old data.
        - Delta-based collectors (stored procedures, perfmon counters) require at least two collection cycles before producing non-zero values. A newly added server will show empty procedure stats for the first ~30 minutes.
        - Wait stats represent cumulative or delta values since the last collection, not instantaneous snapshots.
        - All tools accept a `server_name` parameter. If only one server is configured, it's used automatically.
        - When `execution_count` is 0 but CPU/elapsed time is non-zero, this is a delta calculation artifact — the query was in the plan cache at both collection points but was not executed between them. This is normal and can be ignored.

        ## Tool Reference

        ### Discovery & Health Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `list_servers` | Lists all monitored SQL Server instances with status and last collection time | none |
        | `get_collection_health` | Shows collector health: running, failing, or stale | `server_name` |
        | `get_server_summary` | Quick health overview: CPU %, memory, blocking/deadlock counts | `server_name` |

        ### Wait Statistics Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_wait_stats` | Top wait types aggregated over time period | `server_name`, `hours_back` (default 24), `limit` (default 20) |
        | `get_wait_types` | Lists distinct wait types observed (use before `get_wait_trend`) | `server_name`, `hours_back` |
        | `get_wait_trend` | Time-series for a specific wait type | `wait_type` (required), `server_name`, `hours_back` |
        | `get_waiting_tasks` | Currently/recently waiting queries with details | `server_name`, `hours_back` (default 1), `limit` |

        ### CPU Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_cpu_utilization` | SQL Server CPU vs other process CPU over time | `server_name`, `hours_back` (default 4) |

        ### Query Performance Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_top_queries_by_cpu` | Expensive queries from plan cache with DOP, spills, query_hash | `server_name`, `hours_back`, `top`, `database_name`, `parallel_only`, `min_dop` |
        | `get_top_procedures_by_cpu` | Expensive stored procedures by CPU time | `server_name`, `hours_back`, `top`, `database_name` |
        | `get_query_store_top` | Expensive queries from Query Store (persistent) | `server_name`, `hours_back`, `top`, `database_name` |
        | `get_query_trend` | Time-series for a specific query by query_hash | `query_hash` (required), `database_name` (required), `server_name`, `hours_back` |
        | `get_query_duration_trend` | Average query duration over time (detect degradation) | `server_name`, `hours_back` |

        ### Blocking & Deadlock Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_deadlocks` | Recent deadlock events with victim info | `server_name`, `hours_back`, `limit` |
        | `get_deadlock_detail` | Full deadlock graph XML for deep analysis | `server_name`, `hours_back`, `limit` |
        | `get_blocked_process_reports` | Parsed blocking from sp_HumanEventsBlockViewer (extended events) | `server_name`, `hours_back`, `limit` |
        | `get_blocked_process_xml` | Raw blocked process report XML | `server_name`, `hours_back`, `limit` |
        | `get_blocking_trend` | Time-series of blocking event counts | `server_name`, `hours_back` |
        | `get_deadlock_trend` | Time-series of deadlock event counts | `server_name`, `hours_back` |

        ### Memory Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_memory_stats` | Latest memory snapshot: physical, buffer pool, plan cache | `server_name` |
        | `get_memory_trend` | Memory usage over time | `server_name`, `hours_back` |
        | `get_memory_clerks` | Top memory consumers by clerk type | `server_name` |
        | `get_memory_grants` | Active/recent memory grants (detect grant pressure) | `server_name`, `hours_back` (default 1), `limit` |
        | `get_memory_pressure_events` | Ring buffer memory pressure notifications (sp_pressuredetector source) | `server_name`, `hours_back` |

        ### I/O Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_file_io_stats` | Latest file I/O stats per database file with latency | `server_name` |
        | `get_file_io_trend` | I/O latency trend over time per database | `server_name`, `hours_back` |

        ### TempDB Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_tempdb_trend` | TempDB space: user objects, internal objects, version store | `server_name`, `hours_back` |

        ### Performance Counter Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_perfmon_stats` | Latest perfmon counters (batch requests/sec, etc.) | `server_name`, `counter_name`, `instance_name` |
        | `get_perfmon_trend` | Time-series for a specific perfmon counter | `counter_name` (required), `server_name`, `hours_back` |

        ### Alert Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_alert_history` | Recent alert history: what fired, when, email status | `hours_back` (default 24), `limit` (default 50) |
        | `get_alert_settings` | Current alert thresholds and SMTP configuration | none |

        ### Job Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_running_jobs` | Currently running SQL Agent jobs with duration vs historical average/p95 | `server_name` |

        ### Configuration Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_server_config` | sp_configure settings with configured and in-use values | `server_name` |
        | `get_database_config` | Database-level settings: RCSI, recovery model, auto-shrink, Query Store, etc. | `server_name`, `database_name` |
        | `get_database_scoped_config` | Database-scoped configuration (MAXDOP, legacy CE, parameter sniffing) | `server_name`, `database_name` |
        | `get_trace_flags` | Active trace flags with global/session scope | `server_name` |

        ### Server Information Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_server_properties` | Server inventory: edition, version, CPU count, memory, socket topology | `server_name` |
        | `get_database_sizes` | Database file sizes, space usage, and volume free space | `server_name` |

        ### Session & Active Query Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `get_active_queries` | Active query snapshots from sp_WhoIsActive — what was running at each collection point | `server_name`, `hours_back` (default 1), `database_name`, `blocking_only`, `limit` |
        | `get_session_stats` | Connection counts and resource usage grouped by application | `server_name` |

        ### Execution Plan Analysis Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `analyze_query_plan` | Analyze plan from plan cache by query_hash | `query_hash` (required), `server_name` |
        | `analyze_procedure_plan` | Analyze procedure plan by plan_handle | `plan_handle` (required), `server_name` |
        | `analyze_query_store_plan` | Analyze plan from Query Store (fetches on-demand from SQL Server) | `database_name` (required), `plan_id` (required), `server_name` |
        | `analyze_plan_xml` | Analyze raw showplan XML directly | `plan_xml` (required) |
        | `get_plan_xml` | Get raw showplan XML by query_hash | `query_hash` (required), `server_name` |

        Plan analysis detects 31 performance anti-patterns including:
        - Missing indexes with CREATE statements and impact scores
        - Non-SARGable predicates, implicit conversions, data type mismatches
        - Memory grant issues, spills to TempDB
        - Parallelism problems: serial plan reasons, thread skew, ineffective parallelism
        - Parameter sniffing (compiled vs runtime value mismatches)
        - Expensive operators: key lookups, scans with residual predicates, eager spools
        - Join issues: OR clauses, high nested loop executions, many-to-many merge joins
        - UDF execution overhead, table variable usage, CTE multiple references

        ### Diagnostic Analysis Tools
        | Tool | Purpose | Key Parameters |
        |------|---------|----------------|
        | `analyze_server` | Runs the inference engine: scores facts, traverses relationship graph, returns evidence-backed findings with severity and recommended next tools | `server_name`, `hours_back` (default 4) |
        | `get_analysis_facts` | Exposes raw scored facts from the collect+score pipeline — every observation the engine sees with base severity, amplifiers, and metadata | `server_name`, `hours_back` (default 4), `source` (filter), `min_severity` |
        | `compare_analysis` | Compares two time periods (e.g., peak vs off-peak, before vs after a change) showing severity deltas for each fact | `server_name`, `hours_back` (default 4), `baseline_hours_back` (default 28) |
        | `audit_config` | Edition-aware configuration audit: evaluates CTFP, MAXDOP, max memory, and max worker threads against best practices | `server_name` |
        | `get_analysis_findings` | Retrieves persisted findings from previous analysis runs | `server_name`, `hours_back` (default 24) |
        | `mute_analysis_finding` | Mutes a finding pattern by story_path_hash so it won't appear in future runs | `story_path_hash` (required), `server_name`, `reason` |

        ## Recommended Workflow

        1. **Start**: `list_servers` — see what's monitored and which servers are online
        2. **Verify**: `get_collection_health` — check collectors are running successfully
        3. **Diagnose**: `analyze_server` — run the inference engine for an evidence-backed assessment. Each finding includes `next_tools` — a list of recommended MCP tools to call for deeper investigation. Follow those recommendations.
        4. **Drill down** using the `next_tools` from findings, or manually:
           - High waits → `get_wait_stats` → `get_wait_trend` for specific wait type
           - CPU pressure → `get_cpu_utilization` → `get_top_queries_by_cpu`
           - Blocking → `get_blocked_process_reports` for details
           - Memory issues → `get_memory_stats` → `get_memory_clerks` → `get_memory_grants`
           - I/O latency → `get_file_io_stats` → `get_file_io_trend`
           - TempDB pressure → `get_tempdb_trend`
        5. **Deep dive**: Use `get_analysis_facts` to inspect what the engine sees, including amplifier details and raw metric values
        6. **Compare**: Use `compare_analysis` to see if problems are new (compare last 4 hours vs yesterday same time)
        7. **Config**: Use `audit_config` for edition-aware configuration recommendations
        8. **Active queries**: Use `get_active_queries` to see what was running at a specific time — critical for correlating CPU spikes, blocking events, or deadlocks with actual queries
        9. **Configuration**: Use `get_server_config`, `get_database_config`, or `get_database_scoped_config` to check server and database settings
        10. **Query investigation**: After finding a problematic query via `get_top_queries_by_cpu`, use `get_query_trend` with its `query_hash` to see performance history
        11. **Plan analysis**: Use `analyze_query_plan` with the `query_hash` from step 10 to get detailed plan analysis with warnings, missing indexes, and optimization recommendations

        ## Wait Type to Tool Mapping

        When `get_wait_stats` reveals dominant wait types:
        | Wait Type | Indicates | Tools to Use |
        |-----------|-----------|--------------|
        | `SOS_SCHEDULER_YIELD` | CPU pressure | `get_cpu_utilization`, `get_top_queries_by_cpu` |
        | `CXPACKET` / `CXCONSUMER` | Parallelism | `get_top_queries_by_cpu` with `parallel_only=true` |
        | `PAGEIOLATCH_*` | Disk I/O | `get_file_io_stats`, `get_file_io_trend` |
        | `WRITELOG` | Transaction log I/O | `get_file_io_stats` (check log file latency) |
        | `LCK_M_*` | Lock contention | `get_blocking`, `get_blocked_process_reports` |
        | `RESOURCE_SEMAPHORE` | Memory grant pressure | `get_memory_grants` |
        | `LATCH_*` | Internal contention | `get_tempdb_trend` |

        ## Blocking vs Blocked Process Reports

        - **`get_blocking`**: Captures blocking chains from `sys.dm_exec_requests` at each collection snapshot. Shows who is blocking whom.
        - **`get_blocked_process_reports`**: Captures events from SQL Server's Blocked Process Report extended event (via sp_HumanEventsBlockViewer). Fires when a session has been blocked longer than the configured threshold. Includes richer detail: isolation levels, transaction names, full query text for both blocker and blocked.

        **Use `get_blocking` first** for a quick overview. **Use `get_blocked_process_reports`** when you need detailed analysis of prolonged blocking events.

        ## Interpreting Memory Pressure Events

        `get_memory_pressure_events` returns notifications from the `RING_BUFFER_RESOURCE_MONITOR` ring buffer. The `memory_indicators_process` and `memory_indicators_system` values are SQL Server's Resource Monitor signals. Indicator scale:

        - **0-1**: normal operating state, not actionable
        - **2 (medium)**: Resource Monitor has crossed a threshold and is starting to respond — trimming caches, reducing memory grants. Worth investigating if sustained or frequent.
        - **3+ (severe)**: aggressive response — buffer pool pages are being evicted, plan cache entries thrown out, workspace memory starved. Always worth investigating.

        The two indicators report different things:

        - `memory_indicators_process` — the SQL Server *process itself* is under memory pressure. Usually workload-induced (large memory grants, plan cache bloat, buffer pool churn).
        - `memory_indicators_system` — Windows is signaling low memory *system-wide*. Something on the whole box is consuming memory; SQL Server may or may not be the culprit.

        ### What to check when process pressure (indicator >= 2) fires

        The workload is squeezing SQL Server itself. Follow-up tools:
        | Signal to check | Tool |
        |-----------------|------|
        | Memory grant contention, workspace memory pressure | `get_memory_grants` |
        | Buffer pool composition, memory clerk distribution | `get_memory_clerks` |
        | Page Life Expectancy, target vs total server memory | `get_memory_stats`, `get_memory_trend` |
        | Queries that requested large grants during the window | `get_top_queries_by_cpu` |
        | `RESOURCE_SEMAPHORE` waits in the same window | `get_wait_stats`, `get_wait_trend` |

        ### What to check when system pressure (indicator >= 2) fires but process does not

        The box is tight on memory, but SQL Server's own process is not the cause. SQL Server feels Windows' low-memory notification but isn't driving it. Typical root causes: other services on the machine (anti-virus, backup agents, monitoring agents, additional SQL instances, SSIS/SSRS, RDP sessions), oversized file system cache, or VM-host memory oversubscription. Follow-up:

        | Signal to check | Tool |
        |-----------------|------|
        | SQL Server's memory configuration (`max server memory` vs total RAM) | `get_server_properties` |
        | Is SQL Server itself actually fine? | `get_memory_stats`, `get_memory_clerks` |

        Most of the diagnosis in this case is *outside* the monitored SQL instance — tell the user to check what else is running on the host.

        ### Patterns

        - **Both process and system firing together** → real capacity problem. Add RAM, tune the workload, or reduce concurrency.
        - **Process only** → workload/schema issue, not a hardware problem. Tune queries and indexes.
        - **System only** → non-SQL workload on the host; SQL itself is healthy but the tenant mix is tight.
        - **Bursty spikes** → correlate the pressure window with `get_running_jobs` (scheduled maintenance, index rebuilds, big reports) and `get_top_queries_by_cpu` for that period.
        - **Flat-line sustained** → chronic under-provisioning; memory needs to grow or workload needs to shrink.

        ## Tool Relationships

        - `get_wait_stats` identifies the symptom category (CPU, I/O, locks, parallelism). Other tools find the root cause.
        - `get_perfmon_stats` provides throughput context (batch requests/sec, compilations/sec) that helps distinguish a busy server from a sick one.
        - `get_top_queries_by_cpu` and `get_top_procedures_by_cpu` show aggregate query performance from sys.dm_exec_query_stats. `get_query_store_top` shows Query Store data which may include queries no longer in the plan cache.
        - `get_query_trend` shows how a specific query (by query_hash) has performed over time — use it after identifying a problematic query.
        - `get_waiting_tasks` shows what's actively waiting, complementing the aggregated view from `get_wait_stats`.
        - `get_wait_types` helps you discover available wait types before drilling into `get_wait_trend`.
        - Trend tools (`get_wait_trend`, `get_file_io_trend`, `get_memory_trend`, `get_blocking_trend`, `get_deadlock_trend`, `get_query_duration_trend`) confirm whether a problem is new, worsening, or steady-state.
        - Query tools support `database_name` filtering and `parallel_only`/`min_dop` filtering to narrow results.

        ## Important Limitations

        - **ALL ACCESS IS READ-ONLY**. No exceptions. You cannot execute SQL or modify anything.
        - Query text in results is truncated to 2000 characters. If you need the full text, note this to the user.
        - CPU utilization data is downsampled to 1-minute averages to keep responses manageable.
        - When a `server_name` parameter is omitted and multiple servers are configured, the tool will return an error listing available servers. Always specify the server when working with multi-server setups.

        ## Error Handling

        Common responses and what they mean:
        - "Could not resolve server" — Server name not found; use `list_servers` to see available servers
        - "No data available" — Collector hasn't run yet or no matching data in time range
        - "Delta-based collection requires at least two cycles" — Wait ~30 minutes for newly added servers
        - "Query Store may not be enabled" — Target database doesn't have Query Store enabled
        """;
}
