fix(dsql): document CloudWatch MCP setup and fix Workflow 12 gaps

Workflow 12 (System Diagnostics) required the CloudWatch MCP server but
gave no way to enable it, and agents that hit unavailable PromQL tools
had no recovery guidance. Address the observed failure modes:

- Add a CloudWatch MCP Server section to mcp/mcp-setup.md: enabling the
  shipped-disabled server, AWS_REGION/AWS_PROFILE config, the
  PromQL-enabled region limitation, and the session restart needed for
  its tools to register (a mid-session enable shows "Connected" but
  exposes no callable tools until restart).
- Add AWS_REGION/AWS_PROFILE placeholders to the disabled cloudwatch
  entry in .mcp.json so users see what to fill in.
- workflow.md: add an explicit "If the PromQL tools are unavailable"
  callout in Prerequisites (enable + restart, no fabrication/CLI
  fallback) and a matching Error Handling row, so a blocked agent
  surfaces the fix rather than only reporting missing data.
- Document the discovery-window gotcha: get_promql_label_values
  defaults to a window ending "now" and returns empty for older data;
  pass explicit start/end. An empty result means "no data in window,"
  not "no such cluster."
- Fix "6 diagnostic workflows/sub-workflows" -> "5 diagnostic phases"
  in SKILL.md (both the reference table and Workflow 12 section).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Morlej

plugins/databases-on-aws/.mcp.json

@@ -21,7 +21,9 @@
       ],
       "disabled": true,
       "env": {
-        "FASTMCP_LOG_LEVEL": "ERROR"
+        "FASTMCP_LOG_LEVEL": "ERROR",
+        "AWS_REGION": "[your dsql cluster region, e.g. us-east-1 — must be a PromQL-enabled region]",
+        "AWS_PROFILE": "[your aws profile name, e.g. default]"
       }
     }
   }

plugins/databases-on-aws/skills/dsql/SKILL.md

@@ -79,7 +79,7 @@ Load these files as needed for detailed guidance:
 
 | Reference                                                                                 | When to Load                                                     | Contains                                                              |
 | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [system-diagnostics/workflow.md](references/system-diagnostics/workflow.md)               | MUST load at Workflow 12 entry — cluster performance diagnostics | Prerequisites, 6 diagnostic workflows, temporal comparison, handoff   |
+| [system-diagnostics/workflow.md](references/system-diagnostics/workflow.md)               | MUST load at Workflow 12 entry — cluster performance diagnostics | Prerequisites, 5 diagnostic phases, temporal comparison, handoff      |
 | [system-diagnostics/wait-events.md](references/system-diagnostics/wait-events.md)         | ALWAYS load when interpreting AAS results                        | Canonical DSQL wait event descriptions and investigation guidance     |
 | [system-diagnostics/promql-patterns.md](references/system-diagnostics/promql-patterns.md) | Load when constructing PromQL queries                            | Reusable query templates for AAS breakdown, top-SQL, temporal compare |
 
@@ -262,9 +262,9 @@ Load [orm-guides/overview.md](references/orm-guides/overview.md) for adapter nam
 
 Diagnose cluster performance by querying `db.active_sessions.avg` via PromQL. Detects temporal anomalies in wait event distribution, identifies regressed queries, and routes to Workflow 9 for per-query investigation.
 
-**Requires:** CloudWatch MCP server (`awslabs.cloudwatch-mcp-server`) configured with PromQL access in the same region as the cluster.
+**Requires:** CloudWatch MCP server (`awslabs.cloudwatch-mcp-server`) enabled and configured with PromQL access in the same region as the cluster — see [mcp/mcp-setup.md](mcp/mcp-setup.md#cloudwatch-mcp-server-system-diagnostics--workflow-12) for enabling it, region requirements, and the session restart needed for its tools to register.
 
-MUST load [system-diagnostics/workflow.md](references/system-diagnostics/workflow.md) at entry — it defines prerequisites, 6 diagnostic sub-workflows, temporal baselines, and the routing to Workflow 9 for identified queries.
+MUST load [system-diagnostics/workflow.md](references/system-diagnostics/workflow.md) at entry — it defines prerequisites, 5 diagnostic phases, temporal baselines, and the routing to Workflow 9 for identified queries.
 
 ## Error Scenarios
 

plugins/databases-on-aws/skills/dsql/mcp/mcp-setup.md

@@ -106,6 +106,54 @@ has custom AWS configurations or would like to allow/disallow the MCP server mut
   to be for the MCP server. Always ask the user if writes
   should be allowed.
 
+## CloudWatch MCP Server (System Diagnostics — Workflow 12)
+
+Workflow 12 (System Diagnostics) reads Aurora DSQL Active Average Sessions (AAS) telemetry
+through the CloudWatch MCP server's PromQL tools. This is a **separate server** from
+`aurora-dsql` — it reads CloudWatch metrics, not the database — so it has its own entry in
+`.mcp.json`. The plugin ships it disabled because it needs region and credential details the
+plugin can't know in advance.
+
+The plugin's `.mcp.json` pre-configures it as:
+
+```json
+{
+  "mcpServers": {
+    "cloudwatch": {
+      "command": "uvx",
+      "args": ["awslabs.cloudwatch-mcp-server@latest"],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR",
+        "AWS_REGION": "[your dsql cluster region, e.g. us-east-1 — must be a PromQL-enabled region]",
+        "AWS_PROFILE": "[your aws profile name, e.g. default]"
+      },
+      "disabled": true
+    }
+  }
+}
+```
+
+To enable it:
+
+1. Set `AWS_REGION` to the cluster's region and `AWS_PROFILE` to a profile with CloudWatch
+   read permissions (`cloudwatch:GetMetricData`, and the CloudWatch PromQL / `aps` query
+   permissions). The server uses the standard AWS credential chain, so `--profile` on the
+   command line or `AWS_PROFILE` in `env` both work.
+2. Set `"disabled": false`.
+
+**Region matters.** The server must run in the **same region as the DSQL cluster**, and
+CloudWatch PromQL is only available in a subset of regions — at the time of writing:
+`us-east-1`, `us-west-2`, `eu-west-1`, `ap-southeast-1`, `ap-southeast-2`. If the cluster is
+in another region, PromQL-based diagnostics are not available there; verify the current list
+in the CloudWatch documentation.
+
+**Restart after enabling.** MCP tools are registered when the session starts. If you enable
+the server (or fix its config) mid-session, its tools (`execute_promql_range_query`,
+`get_promql_label_values`, `get_metric_data`, …) will **not** become callable until you
+restart the coding assistant — even though `claude mcp list` may already show it as
+"Connected". A server that shows Connected but whose tools return "No such tool available" is
+the classic symptom of this: restart the session to pick them up.
+
 ## Coding Assistant - Custom Instructions
 
 Before proceeding, identify which coding assistant you are adding the MCP server to and

plugins/databases-on-aws/skills/dsql/references/system-diagnostics/workflow.md

@@ -30,9 +30,11 @@ Diagnose Aurora DSQL cluster performance by querying Active Average Sessions (AA
 **MUST** have before starting:
 
 1. A specific `cluster_id` to investigate — never proceed without one. Ask the user if not provided.
-2. The CloudWatch MCP server (`awslabs.cloudwatch-mcp-server`) configured with PromQL access in the **same region** as the DSQL cluster
+2. The CloudWatch MCP server (`awslabs.cloudwatch-mcp-server`) enabled and configured with PromQL access in the **same region** as the DSQL cluster. See [mcp-setup.md](../../mcp/mcp-setup.md#cloudwatch-mcp-server-system-diagnostics--workflow-12) for how to enable it, the region requirement, PromQL-enabled regions, and the required session restart. If its PromQL tools are unavailable, resolve that before starting rather than working around it — see Error Handling below.
 3. The `aurora-dsql` MCP server configured for the target cluster (for per-query investigation via EXPLAIN)
 
+**If the PromQL tools are unavailable** (e.g. `execute_promql_range_query` / `get_promql_label_values` are missing, or a call returns "No such tool available"): the diagnostic cannot run, and there is no substitute — AAS is only readable through these tools, so do not fall back to the AWS CLI, standard CloudWatch metrics, or fabricated numbers. The usual cause is that the CloudWatch server is disabled, misconfigured, or was enabled after this session started (its tools only register at session start). **Tell the user to enable/fix it per [mcp-setup.md](../../mcp/mcp-setup.md#cloudwatch-mcp-server-system-diagnostics--workflow-12) and then restart the session**, since a mid-session enable will show as "Connected" yet still expose no callable tools until restart. Report this as the blocker and the fix, rather than reporting only that data is missing.
+
 ---
 
 ## Reference Files
@@ -81,7 +83,7 @@ The primary metric is `db.active_sessions.avg` — the average number of session
 **Steps:**
 
 1. Confirm you have a specific `cluster_id` — do not proceed without one
-2. Verify the cluster exists by calling `get_promql_label_values` with a match filter (see [promql-patterns.md](promql-patterns.md))
+2. Verify the cluster exists by calling `get_promql_label_values` with a match filter **and an explicit `start`/`end` window covering the period you intend to analyze** (see [promql-patterns.md](promql-patterns.md)). Label-value and series lookups default to a window ending "now"; if the cluster's most recent data is older than that default (for example, a lightly-used or paused cluster), the call returns an empty list even though the cluster exists. An empty result here means "no data in that window," not "no such cluster" — widen or shift the window before concluding the cluster is missing.
 3. Query AAS by `db.wait.event` for the **current hour** in 10-minute chunks (step=60s)
 4. Query AAS by `db.wait.event` for the **same hour yesterday** (baseline 1)
 5. Query AAS by `db.wait.event` for the **same hour last week** (baseline 2)
@@ -93,7 +95,7 @@ The primary metric is `db.active_sessions.avg` — the average number of session
 
 - **MUST** filter by cluster using `"@resource.aws.auroradsql.cluster_id"` in all queries
 - **MUST** quote label names that contain `.` or `@` in PromQL selectors
-- **MUST** use the `match` parameter with `get_promql_label_values` — calls without match return empty
+- **MUST** use the `match` parameter with `get_promql_label_values` — calls without match return empty. When the data you care about is not recent, **also** pass an explicit `start`/`end`, since these lookups default to a window ending "now" and will otherwise miss older data
 - **MUST** compare against temporal baselines — do NOT report absolute AAS values as inherently problematic
 - A >30% change in a wait event's share of total AAS warrants flagging
 
@@ -282,11 +284,12 @@ execute_promql_range_query(
 
 ## Error Handling
 
-| Situation              | Action                                                                 |
-| ---------------------- | ---------------------------------------------------------------------- |
-| No cluster_id provided | Ask the user — never proceed without a specific cluster                |
-| No series found        | Verify cluster ID with `get_promql_label_values`. Check region.        |
-| Empty result (no data) | Cluster is idle for that period. Widen time window.                    |
-| `db.query.id` missing  | Not all queries emit it. Filter by `db.query.normalized_text` instead. |
-| PromQL timeout         | Reduce cardinality — fewer labels or shorter time range.               |
-| Range > 7 days         | Split into multiple 7-day range queries.                               |
+| Situation                                                 | Action                                                                                                                                                                                                                                                                                                                                |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No cluster_id provided                                    | Ask the user — never proceed without a specific cluster                                                                                                                                                                                                                                                                               |
+| PromQL tools not callable (e.g. "No such tool available") | The CloudWatch server is not enabled, is misconfigured, or was enabled after the session started. Enable/fix it per [mcp-setup.md](../../mcp/mcp-setup.md#cloudwatch-mcp-server-system-diagnostics--workflow-12), then **restart the session** — tools are registered at startup. Do not fall back to guessing or to unrelated tools. |
+| No series / empty label values                            | Confirm the `match` selector, then widen or shift the `start`/`end` window — these lookups default to "now" and miss older data. Only after that, suspect a wrong cluster ID or region.                                                                                                                                               |
+| Empty result (no data)                                    | Cluster is idle for that period. Widen time window.                                                                                                                                                                                                                                                                                   |
+| `db.query.id` missing                                     | Not all queries emit it. Filter by `db.query.normalized_text` instead.                                                                                                                                                                                                                                                                |
+| PromQL timeout                                            | Reduce cardinality — fewer labels or shorter time range.                                                                                                                                                                                                                                                                              |
+| Range > 7 days                                            | Split into multiple 7-day range queries.                                                                                                                                                                                                                                                                                              |