@fluentcommerce/fluent-mcp-extn 0.7.0 → 0.7.3

package/docs/TOOL_REFERENCE.md

@@ -31,7 +31,7 @@ Most tools include extra fields like `event`, `response`, `job`, or `status`.
 
 `error.retryable` indicates whether a caller can safely retry the same request. Non-idempotent writes intentionally avoid automatic retry behavior.
 
-## `config.validate`
+## `config_validate`
 
 Validates configuration and auth readiness without calling Fluent APIs.
 
@@ -44,7 +44,7 @@ Example:
 {}
 ```
 
-## `health.ping`
+## `health_ping`
 
 Returns server health, SDK availability, and safe config summary.
 
@@ -57,7 +57,7 @@ Example:
 {}
 ```
 
-## `event.build`
+## `event_build`
 
 Builds a Fluent event payload only (no API call).
 
@@ -79,19 +79,19 @@ Example:
 }
 ```
 
-## `event.send`
+## `event_send`
 
 Builds and sends an event via SDK adapter. When `dryRun: true`, enriches the response with a `_workflowPreview` showing predicted outcomes from cached workflow analysis.
 
 - **Required**: `name`, `entityRef`, `entityType`
-- **Optional**: all `event.build` fields plus:
+- **Optional**: all `event_build` fields plus:
   - `mode`: `async` or `sync`
   - `dryRun`: boolean
 - **Important**: `retailerId` must match the target entity's retailer for real sends.
 
 ### dryRun workflow preview
 
-When `dryRun: true` and a workflow is cached (call `workflow.get` first), the response includes `_workflowPreview`:
+When `dryRun: true` and a workflow is cached (call `workflow_get` first), the response includes `_workflowPreview`:
 
 - `workflowName`: matched workflow name (e.g. `ORDER::HD`)
 - `matchingRulesets`: array of rulesets triggered by this event at the current status
@@ -125,7 +125,7 @@ Example send:
 }
 ```
 
-## `event.get`
+## `event_get`
 
 Gets one event by ID via SDK-native `getEventById(eventId)`:
 
@@ -155,7 +155,7 @@ Typical success shape (truncated):
 }
 ```
 
-## `event.list`
+## `event_list`
 
 Lists/filter events via SDK-native `getEvents(params)`:
 
@@ -207,11 +207,11 @@ Typical success shape (truncated):
 }
 ```
 
-If `event.send` does not return an `id`, use `event.list` with `name`,
+If `event_send` does not return an `id`, use `event_list` with `name`,
 `entityRef`, and `retailerId` to resolve the latest event ID, then call
-`event.get`.
+`event_get`.
 
-## `event.flowInspect`
+## `event_flowInspect`
 
 One-call runtime forensics for any root entity.
 
@@ -225,8 +225,8 @@ One-call runtime forensics for any root entity.
   - `includeEventDetails`: include compact orchestration event rows (default `true`, full mode only)
   - `includeAuditDetails`: include compact audit action samples (default `false`, full mode only)
   - `includeScheduled`: fetch SCHEDULED events separately (default `true`)
-  - `inspectStatuses`: statuses to drill via `event.get` (defaults: `["NO_MATCH", "PENDING", "FAILED"]`)
-  - `maxDrilldowns`: cap on individual event.get calls (`0..100`, default `50`)
+  - `inspectStatuses`: statuses to drill via `event_get` (defaults: `["NO_MATCH", "PENDING", "FAILED"]`)
+  - `maxDrilldowns`: cap on individual event_get calls (`0..100`, default `50`)
   - `actionSampleLimit`: max rows for action-derived sections (`1..200`, default `100`)
 - **Default-on flags:**
   - `compact`: pre-analyzed summary response (default `true`)
@@ -265,7 +265,7 @@ Returns complete raw arrays:
 - Custom plugin logs (when `includeCustomLogs: true`)
 - Entity snapshots (when `includeSnapshots: true`)
 - Cross-entity events with full events array (when `includeCrossEntity: true`)
-- `NO_MATCH`/`PENDING`/`FAILED` drilldown with full event payload via `event.get`
+- `NO_MATCH`/`PENDING`/`FAILED` drilldown with full event payload via `event_get`
 - Auto-recommendations based on findings
 
 Example (compact — recommended first call):
@@ -304,7 +304,7 @@ Example (lightweight):
 }
 ```
 
-## `metrics.query`
+## `metrics_query`
 
 Queries Prometheus metrics for Fluent runtime telemetry.
 
@@ -317,25 +317,25 @@ Queries Prometheus metrics for Fluent runtime telemetry.
 - **Execution path**:
   - instant -> GraphQL `metricInstant(query, time?)`
   - range -> GraphQL `metricRange(query, start, end, step)`
-- **Note**: `metrics.query` routes PromQL through Fluent's GraphQL proxy. Raw Prometheus REST endpoints are not relied on directly by this tool.
+- **Note**: `metrics_query` routes PromQL through Fluent's GraphQL proxy. Raw Prometheus REST endpoints are not relied on directly by this tool.
 
 Label hygiene reminder:
 - `core_event_received_total` does **not** include `status`
 - `rubix_event_runtime_seconds_*` does include `status`
 - histogram bucket series add `le`
 
-Safer fixed-window counter total pattern:
-
-```promql
-(
-  last_over_time(metric[window])
-  -
-  last_over_time(metric[5m] offset <period>)
-)
-or last_over_time(metric[window])
-```
-
-Use the fallback `or` arm when the series did not exist at the offset point. Pair this with `resets(metric[window])` to decide whether the delta is trustworthy.
+Safer fixed-window counter total pattern:
+
+```promql
+(
+  last_over_time(metric[window])
+  -
+  last_over_time(metric[5m] offset <period>)
+)
+or last_over_time(metric[window])
+```
+
+Use the fallback `or` arm when the series did not exist at the offset point. Pair this with `resets(metric[window])` to decide whether the delta is trustworthy.
 
 Instant example:
 
@@ -358,7 +358,7 @@ Range example:
 }
 ```
 
-## `metrics.topEvents`
+## `metrics_topEvents`
 
 Returns ranked event analytics for a time window by aggregating Event API results.
 
@@ -385,20 +385,20 @@ Example:
 }
 ```
 
-## `metrics.healthCheck`
+## `metrics_healthCheck`
 
 Runs a compact, one-call anomaly assessment.
 
 - **Optional**:
   - `window`: Prometheus/Event API analysis window (`1h`, `6h`, `24h`, `7d`; default `1h`)
-  - `includeTopEvents`: include ranked event list in response (default `true`)
+  - `includeTopEvents`: include ranked event_list in response (default `true`)
   - `topN`: max top event rows (`1..100`, default `10`)
   - `thresholds`: override defaults
     - `failureRate` (default `5`)
     - `pendingRate` (default `10`)
     - `dominanceRate` (default `50`)
 - **Behavior**:
-  - Prometheus-first (`metrics.query` equivalent calls under the hood)
+  - Prometheus-first (`metrics_query` equivalent calls under the hood)
   - Falls back to Event API aggregation if Prometheus is unavailable
 
 Example:
@@ -411,7 +411,7 @@ Example:
 }
 ```
 
-## `metrics.sloReport`
+## `metrics_sloReport`
 
 Returns a managed-services SLO snapshot with explicit KPI fields and threshold findings.
 
@@ -442,7 +442,7 @@ Example:
 }
 ```
 
-## `metrics.labelCatalog`
+## `metrics_labelCatalog`
 
 Discovers what labels a metric supports so PromQL groupings are correct.
 
@@ -467,7 +467,7 @@ Example:
 }
 ```
 
-## `metrics.metricCatalog`
+## `metrics_metricCatalog`
 
 Lists all documented Fluent platform metric families with labels, variants, example PromQL, and queryability flags. Optional live probing discovers active metrics and samples label values from the environment.
 
@@ -479,11 +479,11 @@ Lists all documented Fluent platform metric families with labels, variants, exam
   - `includeLiveLabels`: sample live label values for the selected metric (default `false`)
   - `maxMetrics`: max live metrics to return (default `100`)
   - `maxValuesPerLabel`: max sample values per label (default `10`)
-- **Behavior**:
-  - Without `metric`: returns all 10 documented families (Rubix OTel, GraphQL OTel, GraphQL Micrometer, billing/read-only usage, freshness gauge)
-  - With `metric`: deep dive into one family with labels, variants, notes, examples
-  - `includeLiveMetrics=true`: runs `count by (__name__)({__name__=~".+"})` to discover active metrics
-  - `includeLiveLabels=true`: samples label values via `last_over_time` on histogram _count + _bucket variants
+- **Behavior**:
+  - Without `metric`: returns all 10 documented families (Rubix OTel, GraphQL OTel, GraphQL Micrometer, billing/read-only usage, freshness gauge)
+  - With `metric`: deep dive into one family with labels, variants, notes, examples
+  - `includeLiveMetrics=true`: runs `count by (__name__)({__name__=~".+"})` to discover active metrics
+  - `includeLiveLabels=true`: samples label values via `last_over_time` on histogram _count + _bucket variants
 
 Example:
 
@@ -495,132 +495,132 @@ Example:
 }
 ```
 
-## `metrics.planQuery`
+## `metrics_planQuery`
 
-Generates ready-to-run PromQL for any documented metric family. Validates labels, picks the right histogram variant, and returns a metrics.query-ready payload plus count-audit helpers when the query is count-like.
+Generates ready-to-run PromQL for any documented metric family. Validates labels, picks the right histogram variant, and returns a metrics_query-ready payload plus count-audit helpers when the query is count-like.
 
 - **Required**: `metric`
-- **Optional**:
-  - `goal`: `rate` (default), `increase`, `delta` (exact integer count via last_over_time-offset), `breakdown`, `topk`, `p95`, `avg`, `recency` (gauge freshness via max last_over_time), `raw`
-  - `window`: PromQL range window (default `5m`). Supports compound durations like `1h30m`
+- **Optional**:
+  - `goal`: `rate` (default), `increase`, `delta` (exact integer count via last_over_time-offset), `breakdown`, `topk`, `p95`, `avg`, `recency` (gauge freshness via max last_over_time), `raw`
+  - `window`: PromQL range window (default `5m`). Supports compound durations like `1h30m`
   - `groupBy`: labels to group by
   - `filters`: label matchers (string for exact, array for regex OR)
   - `validateLabels`: reject unsupported labels (default `true`)
   - `topN`: for `topk` goal (default `10`)
   - `percentile`: for `p95` goal (default `0.95`)
-- **Behavior**:
-  - Resolves metric family → picks correct variant (_bucket for p95, _count for rate/increase/delta, _sum/_count for avg, gauge for recency)
-  - Validates groupBy/filter labels against known schema
-  - Reuses the shared duration parser so `metrics.planQuery`, `metrics.compare`, and `metrics.mutationAudit` interpret windows the same way
-  - Returns `rangeQueryHint` with `recommendedStep`, `estimatedPoints`, and a ready-to-run `metrics.query` range payload, snapped upward to stay within the LLM-safe point budget
-  - For `goal=delta` and `goal=increase`, returns `countAudit` with:
-    - `resetAuditQuery`
-    - `comparisonQuery`
-    - `recommendedMethod`
-  - Returns `executeWith: { tool: "metrics.query", arguments: { query, type } }` for direct handoff
-
-### Practical goal mapping
-
-- `rate`: throughput per second
-- `increase`: extrapolated total over a window
-- `delta`: fixed-window endpoint delta, best for near-integer counts when `resets(...) == 0`
-- `breakdown`: grouped totals/rates by safe labels
-- `topk`: ranked grouped results
-- `p95`: latency percentile from histogram buckets
-- `avg`: mean latency from `_sum / _count`
-- `recency`: last-seen timestamp for gauge freshness metrics
-- `raw`: raw selector, mostly for debugging
+- **Behavior**:
+  - Resolves metric family → picks correct variant (_bucket for p95, _count for rate/increase/delta, _sum/_count for avg, gauge for recency)
+  - Validates groupBy/filter labels against known schema
+  - Reuses the shared duration parser so `metrics_planQuery`, `metrics_compare`, and `metrics_mutationAudit` interpret windows the same way
+  - Returns `rangeQueryHint` with `recommendedStep`, `estimatedPoints`, and a ready-to-run `metrics_query` range payload, snapped upward to stay within the LLM-safe point budget
+  - For `goal=delta` and `goal=increase`, returns `countAudit` with:
+    - `resetAuditQuery`
+    - `comparisonQuery`
+    - `recommendedMethod`
+  - Returns `executeWith: { tool: "metrics_query", arguments: { query, type } }` for direct handoff
+
+### Practical goal mapping
+
+- `rate`: throughput per second
+- `increase`: extrapolated total over a window
+- `delta`: fixed-window endpoint delta, best for near-integer counts when `resets(...) == 0`
+- `breakdown`: grouped totals/rates by safe labels
+- `topk`: ranked grouped results
+- `p95`: latency percentile from histogram buckets
+- `avg`: mean latency from `_sum / _count`
+- `recency`: last-seen timestamp for gauge freshness metrics
+- `raw`: raw selector, mostly for debugging
+
+Example:
+
+```json
+{
+  "metric": "rubix_event_runtime_seconds",
+  "goal": "p95",
+  "groupBy": ["entity_type"],
+  "filters": { "account_id": "ACME" },
+  "window": "5m"
+}
+```
+
+## `time_resolveWindow`
+
+Resolves natural-language, shorthand, and datemath time phrases into exact ISO `from` / `to` timestamps so the LLM does not silently guess calendar intent.
+
+- **Required**:
+  - `phrase`: natural-language, shorthand, or datemath phrase such as `last month`, `yesterday`, `last 7 days`, `7d`, `1h30m`, `now-7d/d`, or `now-7d to now`
+- **Optional**:
+  - `timezone`: IANA timezone such as `UTC`, `Asia/Calcutta`, `Australia/Sydney` (defaults to runtime timezone)
+  - `anchor`: ISO-8601 anchor timestamp to resolve against (defaults to `now`)
+  - `mode`: `detect` (default), `calendar`, or `rolling`
+  - `weekStartsOn`: `monday` (default) or `sunday`
+
+Behavior:
+- unambiguous phrases resolve directly (`last 7 days`, `7d`, `previous calendar month`)
+- compound shorthand resolves directly (`1h30m`, `2w3d`)
+- datemath resolves directly (`now-7d`, `now/d`, `now-7d/d`, `now-7d to now`)
+- ambiguous phrases return `valid: false`, `candidates`, and `clarificationQuestion` when `mode: "detect"`
+- forcing `mode: "calendar"` or `mode: "rolling"` resolves the phrase without asking
+
+Use this tool before `graphql_query`, `graphql_queryAll`, or `event_list` when the user asks for relative windows like `last month` and the underlying tool needs explicit timestamps.
+
+Example:
+
+```json
+{
+  "phrase": "last month",
+  "timezone": "Asia/Calcutta"
+}
+```
+
+Datemath example:
+
+```json
+{
+  "phrase": "now-7d/d",
+  "timezone": "Asia/Calcutta"
+}
+```
+
+## `metrics_mutationAudit`
+
+Audits GraphQL create/update mutation traffic by business domain and subdomain. This tool discovers mutation names locally, then queries each operation explicitly over the requested window so the model does not need to handcraft per-operation PromQL.
+
+- **Optional**:
+  - `window`: fixed window for counts (default `7d`)
+  - `domain`: optional domain filter such as `inventory`, `order`, `fulfilment`, `catalog`
+  - `subdomain`: optional subdomain filter such as `position`, `quantity`, `virtual-catalogue`, `virtual-position`, `consignment`
+  - `operationTypes`: subset of `create`, `update` (default both)
+  - `statuses`: GraphQL request outcome labels to include (default `["success"]`)
+  - `operations`: explicit mutation names to audit instead of schema discovery
+  - `includeZeroCount`: include zero-count operations (default `false`)
+  - `comparePrevious`: also count the immediately preceding window and return deltas (default `true`)
+  - `includeQueries`: include the generated PromQL per operation (default `false`)
+  - `maxOperations`: safety cap for how many operations to evaluate (default `100`)
+  - `forceIntrospection`: refresh schema mutation discovery instead of using cache
+- **Behavior**:
+  - Discovers `create*` / `update*` mutations from schema when `operations` is omitted
+  - Classifies operations into domain/subdomain using the built-in taxonomy
+  - Uses fixed-window delta counting on `graphql_request_runtime_seconds_count`
+  - Returns grouped summaries by domain, subdomain, and action, plus per-operation rows
+  - Includes `countAudit` with `resets()` and `increase()` comparison queries so you can sanity-check the totals
+- **Caveat**:
+  - This measures GraphQL mutation request traffic, not guaranteed business-truth entity changes
+  - If the tenant does not expose a usable `operation` label on GraphQL metrics, the tool returns `valid=false` instead of pretending the split is trustworthy
 
 Example:
 
 ```json
-{
-  "metric": "rubix_event_runtime_seconds",
-  "goal": "p95",
-  "groupBy": ["entity_type"],
-  "filters": { "account_id": "ACME" },
-  "window": "5m"
-}
-```
-
-## `time.resolveWindow`
-
-Resolves natural-language, shorthand, and datemath time phrases into exact ISO `from` / `to` timestamps so the LLM does not silently guess calendar intent.
-
-- **Required**:
-  - `phrase`: natural-language, shorthand, or datemath phrase such as `last month`, `yesterday`, `last 7 days`, `7d`, `1h30m`, `now-7d/d`, or `now-7d to now`
-- **Optional**:
-  - `timezone`: IANA timezone such as `UTC`, `Asia/Calcutta`, `Australia/Sydney` (defaults to runtime timezone)
-  - `anchor`: ISO-8601 anchor timestamp to resolve against (defaults to `now`)
-  - `mode`: `detect` (default), `calendar`, or `rolling`
-  - `weekStartsOn`: `monday` (default) or `sunday`
-
-Behavior:
-- unambiguous phrases resolve directly (`last 7 days`, `7d`, `previous calendar month`)
-- compound shorthand resolves directly (`1h30m`, `2w3d`)
-- datemath resolves directly (`now-7d`, `now/d`, `now-7d/d`, `now-7d to now`)
-- ambiguous phrases return `valid: false`, `candidates`, and `clarificationQuestion` when `mode: "detect"`
-- forcing `mode: "calendar"` or `mode: "rolling"` resolves the phrase without asking
-
-Use this tool before `graphql.query`, `graphql.queryAll`, or `event.list` when the user asks for relative windows like `last month` and the underlying tool needs explicit timestamps.
-
-Example:
-
-```json
-{
-  "phrase": "last month",
-  "timezone": "Asia/Calcutta"
-}
-```
-
-Datemath example:
-
-```json
-{
-  "phrase": "now-7d/d",
-  "timezone": "Asia/Calcutta"
-}
-```
-
-## `metrics.mutationAudit`
-
-Audits GraphQL create/update mutation traffic by business domain and subdomain. This tool discovers mutation names locally, then queries each operation explicitly over the requested window so the model does not need to handcraft per-operation PromQL.
-
-- **Optional**:
-  - `window`: fixed window for counts (default `7d`)
-  - `domain`: optional domain filter such as `inventory`, `order`, `fulfilment`, `catalog`
-  - `subdomain`: optional subdomain filter such as `position`, `quantity`, `virtual-catalogue`, `virtual-position`, `consignment`
-  - `operationTypes`: subset of `create`, `update` (default both)
-  - `statuses`: GraphQL request outcome labels to include (default `["success"]`)
-  - `operations`: explicit mutation names to audit instead of schema discovery
-  - `includeZeroCount`: include zero-count operations (default `false`)
-  - `comparePrevious`: also count the immediately preceding window and return deltas (default `true`)
-  - `includeQueries`: include the generated PromQL per operation (default `false`)
-  - `maxOperations`: safety cap for how many operations to evaluate (default `100`)
-  - `forceIntrospection`: refresh schema mutation discovery instead of using cache
-- **Behavior**:
-  - Discovers `create*` / `update*` mutations from schema when `operations` is omitted
-  - Classifies operations into domain/subdomain using the built-in taxonomy
-  - Uses fixed-window delta counting on `graphql_request_runtime_seconds_count`
-  - Returns grouped summaries by domain, subdomain, and action, plus per-operation rows
-  - Includes `countAudit` with `resets()` and `increase()` comparison queries so you can sanity-check the totals
-- **Caveat**:
-  - This measures GraphQL mutation request traffic, not guaranteed business-truth entity changes
-  - If the tenant does not expose a usable `operation` label on GraphQL metrics, the tool returns `valid=false` instead of pretending the split is trustworthy
-
-Example:
-
-```json
-{
-  "domain": "inventory",
-  "window": "7d",
-  "operationTypes": ["create", "update"],
-  "statuses": ["success"],
-  "comparePrevious": true
-}
-```
-
-## `workflow.transitions`
+{
+  "domain": "inventory",
+  "window": "7d",
+  "operationTypes": ["create", "update"],
+  "statuses": ["success"],
+  "comparePrevious": true
+}
+```
+
+## `workflow_transitions`
 
 Query available user actions (transitions) for entities at a given workflow state, enriched with workflow-aware predictions.
 
@@ -630,7 +630,7 @@ Calls `POST /api/v4.1/transition` to discover what events can be fired, what att
 - **Optional per trigger**: `type`, `subtype`, `status`, `module`, `flexType`, `flexVersion`, `name`
 - **Retailer behavior**: `retailerId` is required per trigger. Falls back to `FLUENT_RETAILER_ID` when omitted.
 - **flexType auto-derive**: When `flexType` is not provided but `type` and `subtype` are, the tool auto-derives `flexType` as `{type}::{subtype}` (e.g., `CREDIT_MEMO::APPEASEMENT`). This avoids the silent empty-response problem where the Transition API returns `{"response":[]}` when `flexType` is missing.
-- **Auto-fetch workflow**: When no cached workflow exists, automatically fetches it via `workflow.get` (deriving entityType/entitySubtype from trigger type+subtype or flexType) and caches it for future calls.
+- **Auto-fetch workflow**: When no cached workflow exists, automatically fetches it via `workflow_get` (deriving entityType/entitySubtype from trigger type+subtype or flexType) and caches it for future calls.
 
 ### Use cases
 
@@ -646,13 +646,13 @@ Calls `POST /api/v4.1/transition` to discover what events can be fired, what att
   - `classification`: `"progression"` (advances workflow), `"terminal"` (reaches end state), or `"unknown"` (no workflow match)
   - `targetStatus`: the predicted status the entity will reach after this action
   - `nextSteps`: array of event names available from the predicted `targetStatus` (multi-step lookahead)
-- **`_attributeTemplate`**: `{ eventName: { attrName: "<required>" | "<optional>" } }` — ready-to-fill templates for `event.send`
+- **`_attributeTemplate`**: `{ eventName: { attrName: "<required>" | "<optional>" } }` — ready-to-fill templates for `event_send`
 - **`_recommended`**: `{ eventName, reason, confidence }` — the safest next action to take
   - `confidence`: `"high"` (single progression action), `"medium"` (non-confirmation only), `"low"` (multiple choices)
 
-### Integration with event.send
+### Integration with event_send
 
-The `eventName` from each `userAction` maps directly to `event.send`'s `name` parameter. The `attributes[]` tell you what to include in `event.send`'s `attributes` parameter. The `_attributeTemplate` provides a pre-built skeleton.
+The `eventName` from each `userAction` maps directly to `event_send`'s `name` parameter. The `attributes[]` tell you what to include in `event_send`'s `attributes` parameter. The `_attributeTemplate` provides a pre-built skeleton.
 
 ### Example: ORDER at CREATED status
 
@@ -736,17 +736,17 @@ Typical success shape (truncated, showing enrichment):
 ### Dynamic test sequence pattern
 
 ```
-1. Create entity via graphql.query (mutation)
-2. workflow.transitions → get available actions at current status
+1. Create entity via graphql_query (mutation)
+2. workflow_transitions → get available actions at current status
 3. Use _recommended for safest next action, or iterate _predictions for multi-path testing
 4. For each action:
-   a. event.send with eventName and attributes from _attributeTemplate
+   a. event_send with eventName and attributes from _attributeTemplate
    b. Poll entity status until transition completes
-   c. workflow.transitions → get next available actions (use nextSteps for lookahead)
+   c. workflow_transitions → get next available actions (use nextSteps for lookahead)
 5. Repeat until no more userActions (terminal state)
 ```
 
-## `plugin.list`
+## `plugin_list`
 
 List all registered orchestration rules (standard + custom) with metadata.
 
@@ -806,7 +806,7 @@ Typical success shape (truncated):
 }
 ```
 
-## `graphql.query`
+## `graphql_query`
 
 Executes a Fluent Commerce GraphQL query or mutation through the SDK.
 
@@ -850,7 +850,7 @@ Pagination args: `first`/`after` (forward), `last`/`before` (backward).
 
 ### Synchronous Fulfilment Options (Live Checkout)
 
-`graphql.query` supports synchronous fulfilment options orchestration calls,
+`graphql_query` supports synchronous fulfilment options orchestration calls,
 commonly used by checkout journeys to get plans in the same response.
 
 ```json
@@ -892,7 +892,7 @@ All list queries return connections:
 
 Common query roots: `orders`, `fulfilments`, `fulfilmentChoices`, `locations`, `inventoryPositions`, `products`, `categories`, `settings`, `waves`, `articles`.
 
-## `batch.create`
+## `batch_create`
 
 Creates a Fluent ingestion job.
 
@@ -910,9 +910,9 @@ Example:
 }
 ```
 
-## `batch.describePayload`
+## `batch_describePayload`
 
-Returns entity-type-specific payload guidance for `batch.send` without making an API call.
+Returns entity-type-specific payload guidance for `batch_send` without making an API call.
 
 - **Required**: `entityType`
 - **Optional**: `action` (default: `UPSERT`)
@@ -935,9 +935,9 @@ Returns:
 }
 ```
 
-Use this before `batch.send` when the model is unsure about row shape for entity types like `PRODUCT`, `INVENTORY_POSITION`, `LOCATION`, `CUSTOMER`, or `ORDER`.
+Use this before `batch_send` when the model is unsure about row shape for entity types like `PRODUCT`, `INVENTORY_POSITION`, `LOCATION`, `CUSTOMER`, or `ORDER`.
 
-## `batch.send`
+## `batch_send`
 
 Sends payload records to an existing batch job.
 
@@ -968,7 +968,7 @@ Example:
 }
 ```
 
-## `batch.status`
+## `batch_status`
 
 Reads status for a previously created batch job.
 
@@ -982,7 +982,7 @@ Example:
 }
 ```
 
-## `batch.batchStatus`
+## `batch_batchStatus`
 
 Gets the status of a specific batch within a job. Useful for troubleshooting partial failures in multi-batch jobs.
 
@@ -997,9 +997,9 @@ Example:
 }
 ```
 
-## `batch.results`
+## `batch_results`
 
-Gets per-record outcomes for a completed job. Call after `batch.status` reports a terminal state.
+Gets per-record outcomes for a completed job. Call after `batch_status` reports a terminal state.
 
 - **Required**: `jobId`
 
@@ -1013,9 +1013,9 @@ Example:
 
 ---
 
-## `graphql.queryAll`
+## `graphql_queryAll`
 
-Executes a GraphQL query with SDK auto-pagination. Automatically follows cursors, merges all edges, and deduplicates by node ID. Use instead of `graphql.query` when you need ALL records from a connection.
+Executes a GraphQL query with SDK auto-pagination. Automatically follows cursors, merges all edges, and deduplicates by node ID. Use instead of `graphql_query` when you need ALL records from a connection.
 
 - **Required**: `query`
 - **Optional**:
@@ -1072,7 +1072,7 @@ If truncated: `truncationReason` will be `"maxPages"`, `"maxRecords"`, or `"time
 }
 ```
 
-## `graphql.batchMutate`
+## `graphql_batchMutate`
 
 Executes multiple GraphQL mutations in a single request using aliased mutations. Sends up to 50 mutations at once, each with its own input.
 
@@ -1138,7 +1138,7 @@ On partial failure, `errors` array includes per-mutation error details with `ali
 }
 ```
 
-## `graphql.introspect`
+## `graphql_introspect`
 
 Inspects the Fluent Commerce GraphQL schema via introspection. Caches schema responses locally (24h disk cache by default when cache is enabled) and supports `force` refresh. Use to discover mutations, input types, and field requirements at runtime.
 
@@ -1224,9 +1224,9 @@ Response:
 1. `{ "listMutations": true }` → find `updateOrder`
 2. `{ "mutation": "updateOrder" }` → see it takes `UpdateOrderInput!`
 3. `{ "type": "UpdateOrderInput" }` → see all updatable fields
-4. Use `graphql.query` or `graphql.batchMutate` with the discovered schema
+4. Use `graphql_query` or `graphql_batchMutate` with the discovered schema
 
-## `graphql.listRoots`
+## `graphql_listRoots`
 
 List all query and mutation root fields from the live GraphQL schema. Use to discover what queries and mutations are available before building them.
 
@@ -1250,7 +1250,7 @@ Response:
 }
 ```
 
-## `graphql.planOperation`
+## `graphql_planOperation`
 
 Plan a query or mutation before execution. This is the best tool when the model needs help building the right GraphQL payload shape.
 
@@ -1274,7 +1274,7 @@ Returns:
 - `recommendedExecutionTool`
 - `document`
 
-For query roots with nested connections or aggregate-style fields, the planner also includes connection/field guidance so the caller can decide when to use `graphql.queryAll`, add `first`, or select leaf fields like `sum` / `count`.
+For query roots with nested connections or aggregate-style fields, the planner also includes connection/field guidance so the caller can decide when to use `graphql_queryAll`, add `first`, or select leaf fields like `sum` / `count`.
 
 ### Example
 
@@ -1287,12 +1287,12 @@ For query roots with nested connections or aggregate-style fields, the planner a
 
 Typical follow-on flow:
 
-1. Run `graphql.planOperation`
+1. Run `graphql_planOperation`
 2. Review `requiredInputPaths` and `variablesTemplate`
 3. Adjust the scaffold if needed
-4. Execute with `graphql.query` or `graphql.queryAll`
+4. Execute with `graphql_query` or `graphql_queryAll`
 
-## `graphql.buildQuery`
+## `graphql_buildQuery`
 
 Generate a GraphQL query or mutation string from structured inputs. Validates the result against the live schema by default.
 
@@ -1333,7 +1333,7 @@ Response:
 }
 ```
 
-## `graphql.validate`
+## `graphql_validate`
 
 Validate a GraphQL document string against the live schema. Returns "OK" if valid, or a list of validation errors.
 
@@ -1364,7 +1364,7 @@ Response (invalid):
 }
 ```
 
-## `graphql.generateFull`
+## `graphql_generateFull`
 
 Generate a maximal-selection query for a root field, recursively including all scalar fields and nested object fields up to the specified depth.
 
@@ -1396,7 +1396,7 @@ Response:
 }
 ```
 
-## `connection.test`
+## `connection_test`
 
 Comprehensive Fluent Commerce connectivity test. Authenticates, executes a `me` query, and returns the authenticated user's details.
 
@@ -1433,9 +1433,9 @@ Comprehensive Fluent Commerce connectivity test. Authenticates, executes a `me`
 }
 ```
 
-More thorough than `health.ping` — actually verifies the GraphQL endpoint works end-to-end. Use when first connecting, debugging auth issues, or verifying retailer/location context.
+More thorough than `health_ping` — actually verifies the GraphQL endpoint works end-to-end. Use when first connecting, debugging auth issues, or verifying retailer/location context.
 
-## `webhook.validate`
+## `webhook_validate`
 
 Validates a Fluent Commerce webhook payload and optionally verifies its signature.
 
@@ -1507,7 +1507,7 @@ Response:
 
 ---
 
-## `entity.planCreate`
+## `entity_planCreate`
 
 Plan an entity creation locally without making an API call.
 
@@ -1527,7 +1527,7 @@ Returns:
 - `_meta.availableEdges`
 - `_hints`
 
-Use this when the model knows it wants `entity.create` but needs help with required fields, retailer auto-injection, or the mutation shape first.
+Use this when the model knows it wants `entity_create` but needs help with required fields, retailer auto-injection, or the mutation shape first.
 
 ### Example
 
@@ -1539,9 +1539,9 @@ Use this when the model knows it wants `entity.create` but needs help with requi
 
 ---
 
-## `entity.planUpdate`
+## `entity_planUpdate`
 
-Plan an entity update locally without making an API call.
+Plan an entity_update locally without making an API call.
 
 - **Required**: `entityType`
 
@@ -1557,7 +1557,7 @@ Returns:
 - `_meta.availableEdges`
 - `_hints`
 
-Use this when the model needs to know which fields are likely safe to send to `entity.update`, or wants a starter payload before setting `status`, `attributes`, or related fields.
+Use this when the model needs to know which fields are likely safe to send to `entity_update`, or wants a starter payload before setting `status`, `attributes`, or related fields.
 
 ### Example
 
@@ -1569,7 +1569,7 @@ Use this when the model needs to know which fields are likely safe to send to `e
 
 ---
 
-## `entity.create`
+## `entity_create`
 
 Type-safe entity creation with built-in validation and gotcha knowledge.
 
@@ -1656,7 +1656,7 @@ Response:
 
 ---
 
-## `entity.update`
+## `entity_update`
 
 Status-aware entity updates with optional transition validation.
 
@@ -1666,12 +1666,12 @@ Status-aware entity updates with optional transition validation.
   - `fields`: object of fields to update (matches GraphQL update input type)
 - **Optional**:
   - `returnFields`: array of field names to return
-  - `validateTransition`: if `true` and `status` is being changed, queries `workflow.transitions` to verify the transition is allowed before executing (default `false`)
+  - `validateTransition`: if `true` and `status` is being changed, queries `workflow_transitions` to verify the transition is allowed before executing (default `false`)
 
 **Key behaviors:**
 
 - Auto-detects the correct GraphQL mutation name from entity type
-- When `validateTransition` is `true`: fetches current entity state, queries transition API, warns if no workflow transitions exist from the current status
+- When `validateTransition` is `true`: fetches current entity state, queries transition API, warns if no workflow_transitions exist from the current status
 - Returns the previous status for audit trail when transition validation is used
 - Uses no-retry semantics (write operation)
 
@@ -1705,13 +1705,13 @@ If no workflow transition exists:
   "entityType": "ORDER",
   "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
   "mutation": "...",
-  "transitionWarning": "No workflow transitions available from status \"BOOKED\" for ORDER. The status update may succeed as a direct mutation but will not trigger workflow orchestration."
+  "transitionWarning": "No workflow_transitions available from status \"BOOKED\" for ORDER. The status update may succeed as a direct mutation but will not trigger workflow orchestration."
 }
 ```
 
 ---
 
-## `entity.get`
+## `entity_get`
 
 Unified entity lookup by ID or ref with optional edge inclusion.
 
@@ -1764,7 +1764,7 @@ Response:
 
 ---
 
-## `workflow.get`
+## `workflow_get`
 
 Fetch a specific workflow definition by entity type and subtype via REST API.
 
@@ -1796,7 +1796,7 @@ Uses `GET /api/v4.1/workflow/{retailerId}/{entityType}::{entitySubtype}/` — wo
 
 ---
 
-## `workflow.list`
+## `workflow_list`
 
 List all workflows for a retailer via REST API.
 
@@ -1816,20 +1816,19 @@ Uses `GET /api/v4.1/workflow?retailerId={id}&count=200`. Response is deduplicate
 }
 ```
 
-**Note:** Some accounts restrict this endpoint (401 "Incorrect retailer"). In that case, use `workflow.get` with a specific entityType + entitySubtype instead.
+**Note:** Some accounts restrict this endpoint (401 "Incorrect retailer"). In that case, use `workflow_get` with a specific entityType + entitySubtype instead.
 
 ---
 
-## `workflow.upload`
+## `workflow_upload`
 
-Deploy a workflow JSON definition to the Fluent environment with preflight safety analysis.
+Deploy a workflow JSON via the Fluent REST API (`PUT /api/v4.1/workflow/{retailerId}`) with preflight safety analysis.
 
-Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoint the Fluent CLI uses. Before deploying, performs semantic risk analysis and compares with the live workflow if it exists.
+Uses PUT for idempotent upsert — deploying the same JSON twice does not create duplicate versions (unlike POST which always creates a new version). Before deploying, performs semantic risk analysis and compares with the live workflow if it exists.
 
 - **Required**:
   - `workflow`: workflow JSON definition (as object or JSON string)
 - **Optional**:
-  - `retailerId`: target retailer ID (falls back to `FLUENT_RETAILER_ID`)
   - `validate`: validate structure before uploading (default `true`)
   - `dryRun`: validate only, do not deploy (default `false`)
 
@@ -1843,7 +1842,7 @@ Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoin
 
 - **No-match zone detection**: identifies statuses that are transition targets but have no rulesets triggered from them — events sent to these statuses will NO_MATCH
 - **Webhook dependency extraction**: lists all setting keys referenced by webhook rules so you can verify they exist
-- **Live workflow comparison**: when updating an existing workflow, fetches the current version and runs `workflow.diff` to show ruleset/status changes and risk level
+- **Live workflow comparison**: when updating an existing workflow, fetches the current version and runs `workflow_diff` to show ruleset/status changes and risk level
 - **Cross-version risk analysis**: detects removed statuses that had active rulesets and removed rulesets
 
 **Response fields (in addition to standard success fields):**
@@ -1857,8 +1856,9 @@ Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoin
 
 **Important:**
 - Preflight analysis is **non-blocking** — failures to fetch the current workflow don't prevent upload (handles first deployments and permission issues gracefully)
+- Deploys via REST API PUT (full replace semantics) — the uploaded JSON completely replaces the workflow definition
+- Does NOT update the CLI workflowlog — `fluent workflow download` may show stale data. Fix: `fluent workflowlog delete` then redeploy via CLI
 - For production deployments, prefer `fluent module install` via CLI which bundles workflows with settings, rules, and data in a versioned module
-- Use this tool for interactive editing, hotfixes, or when CLI is unavailable
 
 **Example** — dry-run with risk analysis:
 
@@ -1917,7 +1917,7 @@ Response (dry run with no-match zone detected):
 
 ---
 
-## `workflow.diff`
+## `workflow_diff`
 
 Compare two workflow JSON definitions and identify changes.
 
@@ -1967,7 +1967,7 @@ Response:
 
 ---
 
-## `workflow.simulate`
+## `workflow_simulate`
 
 Static prediction of workflow event outcomes from workflow JSON.
 
@@ -1994,7 +1994,7 @@ Pure local computation — no API calls. Parses workflow JSON to find matching r
 - **STATIC ONLY** — cannot evaluate runtime conditions, entity attributes, or settings values
 - **CUSTOM RULES OPAQUE** — Java plugin rules may conditionally execute; behavior unknown without live state
 - **NO CROSS-ENTITY** — does not follow SendEvent chains into child entity workflows
-- Use `workflow.transitions` for **authoritative live validation** of available actions
+- Use `workflow_transitions` for **authoritative live validation** of available actions
 
 **Example** — simulate from CREATED status:
 
@@ -2035,14 +2035,14 @@ Response:
   "limitations": [
     "STATIC PREDICTION ONLY — does not account for runtime conditions, entity attributes, or settings values.",
     "1 custom rule(s) found whose behavior cannot be predicted statically: ForwardIfOrderCoordinatesPresent.",
-    "Use workflow.transitions for AUTHORITATIVE live validation of available actions."
+    "Use workflow_transitions for AUTHORITATIVE live validation of available actions."
   ]
 }
 ```
 
 ---
 
-## `setting.get`
+## `setting_get`
 
 Fetch one or more Fluent Commerce settings by name (supports `%` wildcards).
 
@@ -2093,7 +2093,7 @@ Uses the GraphQL `settings(name:)` query. Returns metadata inline (name, context
 
 ---
 
-## `setting.upsert`
+## `setting_upsert`
 
 Create or update a Fluent Commerce setting with upsert semantics.
 
@@ -2158,7 +2158,7 @@ Response (updated existing):
 
 ---
 
-## `setting.bulkUpsert`
+## `setting_bulkUpsert`
 
 Batch create or update multiple settings in one call.
 
@@ -2198,7 +2198,7 @@ Response:
 
 ---
 
-## `environment.discover`
+## `environment_discover`
 
 Full environment snapshot in one call.
 
@@ -2237,7 +2237,7 @@ Response:
 
 ---
 
-## `environment.validate`
+## `environment_validate`
 
 Pre-flight environment validation. Runs configurable checks before E2E tests or deployments.
 
@@ -2284,7 +2284,7 @@ Response:
 
 ---
 
-## `test.assert`
+## `test_assert`
 
 Assert entity state matches expectations with optional polling.
 
@@ -2364,7 +2364,7 @@ Response (fail after timeout):
 
 ---
 
-## `cache.status`
+## `cache_status`
 
 Show local cache statistics. No API call.
 
@@ -2394,11 +2394,11 @@ Returns:
 - `FLUENT_CACHE_TTL_PLUGIN` — plugin TTL in ms (default 1 hour)
 
 **Cached tools:**
-- `graphql.introspect`
-- `plugin.list`
-- `workflow.get`
-- `workflow.list`
-- `setting.get`
+- `graphql_introspect`
+- `plugin_list`
+- `workflow_get`
+- `workflow_list`
+- `setting_get`
 
 Example:
 
@@ -2410,7 +2410,7 @@ Example:
 
 ---
 
-## `cache.clear`
+## `cache_clear`
 
 Clear cached entries. No API call.
 
@@ -2418,10 +2418,10 @@ Clear cached entries. No API call.
   - `pattern`: string — glob-style cache key filter. Omit to clear everything.
 
 Common patterns:
-- `workflow:*` — clear workflow list/get cache
+- `workflow:get:*` or `workflow:list:*` — clear workflow get/list cache
 - `setting:get:fc.mystique.*` — clear cached manifest/settings lookups
 - `introspect:*` — clear GraphQL schema cache
-- `plugin:list` — clear cached plugin metadata
+- `plugin:list:*` — clear cached plugin metadata
 
 Response includes:
 - `cleared`: number of entries removed
@@ -2446,15 +2446,15 @@ Example:
 
 | Category | Tools | Retry behavior |
 |------|----------|-------------|
-| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.metricCatalog`, `metrics.planQuery`, `metrics.snapshot`, `metrics.compare`, `metrics.mutationAudit`, `metrics.topEvents`, `workflow.transitions`, `workflow.get`, `workflow.list`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `graphql.listRoots`, `graphql.validate`, `graphql.generateFull`, `connection.test`, `entity.get`, `setting.get`, `environment.discover`, `environment.validate`, `test.assert`, `plugin.list` | retry + backoff |
-| Write operations | `event.send`, `batch.create`, `batch.send`, `graphql.query` (mutation), `graphql.batchMutate`, `entity.create`, `entity.update`, `workflow.upload`, `setting.upsert`, `setting.bulkUpsert` | timeout-only (no automatic retry) |
-| Local validation / no API | `config.validate`, `health.ping`, `time.resolveWindow`, `event.build`, `webhook.validate`, `workflow.diff`, `workflow.simulate`, `graphql.buildQuery` (validate=false), `cache.status`, `cache.clear`, `connection.list`, `connection.add`, `connection.remove`, `connection.switch` | not applicable |
+| Read operations | `event_get`, `event_list`, `event_flowInspect`, `metrics_query`, `metrics_healthCheck`, `metrics_sloReport`, `metrics_labelCatalog`, `metrics_metricCatalog`, `metrics_planQuery`, `metrics_snapshot`, `metrics_compare`, `metrics_mutationAudit`, `metrics_topEvents`, `workflow_transitions`, `workflow_get`, `workflow_list`, `graphql_query` (query), `graphql_queryAll`, `batch_status`, `batch_batchStatus`, `batch_results`, `graphql_introspect`, `graphql_listRoots`, `graphql_validate`, `graphql_generateFull`, `connection_test`, `entity_get`, `setting_get`, `environment_discover`, `environment_validate`, `test_assert`, `plugin_list` | retry + backoff |
+| Write operations | `event_send`, `batch_create`, `batch_send`, `graphql_query` (mutation), `graphql_batchMutate`, `entity_create`, `entity_update`, `workflow_upload`, `setting_upsert`, `setting_bulkUpsert` | timeout-only (no automatic retry) |
+| Local validation / no API | `config_validate`, `health_ping`, `time_resolveWindow`, `event_build`, `webhook_validate`, `workflow_diff`, `workflow_simulate`, `graphql_buildQuery` (validate=false), `cache_status`, `cache_clear`, `connection_list`, `connection_add`, `connection_remove`, `connection_switch` | not applicable |
 
 ## Connection Management
 
 These tools manage the multi-profile registry at runtime. They do not require a `profile` parameter themselves.
 
-### `connection.list`
+### `connection_list`
 
 List all registered profiles with auth strategy, init status, and default marker.
 
@@ -2498,7 +2498,7 @@ Response:
 }
 ```
 
-### `connection.add`
+### `connection_add`
 
 Add a new profile at runtime. Supports CLI profile names or explicit credentials.
 
@@ -2519,7 +2519,7 @@ Each registered slot resolves auth independently, so one server session can mix:
 - explicit OAuth
 - explicit static bearer token
 
-`TOKEN_COMMAND` is not currently a `connection.add` option; token-command auth is configured at server startup via environment variables.
+`TOKEN_COMMAND` is not currently a `connection_add` option; token-command auth is configured at server startup via environment variables.
 
 Example — add by CLI profile:
 
@@ -2554,7 +2554,7 @@ Example — add with static bearer token:
 }
 ```
 
-### `connection.remove`
+### `connection_remove`
 
 Remove a non-default profile from the registry.
 
@@ -2569,7 +2569,7 @@ Example:
 }
 ```
 
-### `connection.switch`
+### `connection_switch`
 
 Change the default profile. Subsequent tool calls that omit `profile` will use this profile.
 
@@ -2589,63 +2589,63 @@ Example:
 
 | Tool | Category | Requires SDK | Retry | Description |
 |------|----------|:------------:|:-----:|-------------|
-| `config.validate` | Diagnostics | No | — | Validate auth/base URL configuration |
-| `health.ping` | Diagnostics | No | — | Quick health check with config summary |
-| `connection.test` | Diagnostics | Yes | Yes | Full auth + GraphQL end-to-end test (returns user/account context) |
-| `connection.list` | Connection | No | — | List registered profiles with auth strategy and init status |
-| `connection.add` | Connection | No | — | Add a profile at runtime (CLI profile or explicit credentials) |
-| `connection.remove` | Connection | No | — | Remove a non-default profile |
-| `connection.switch` | Connection | No | — | Switch the default profile |
-| `event.build` | Events | No | — | Build event payload (no API call) |
-| `event.send` | Events | Yes | No | Send event (async/sync, supports dryRun) |
-| `event.get` | Events | Yes | Yes | Get single event by ID |
-| `event.list` | Events | Yes | Yes | List/filter events with pagination and optional analysis mode |
-| `event.flowInspect` | Events | Yes | Yes | One-call root-entity flow forensics with compact/full modes |
-| `metrics.query` | Metrics | Yes | Yes | Query Prometheus metrics (instant/range) |
-| `metrics.healthCheck` | Metrics | Yes | Yes | One-call anomaly assessment with Prometheus + Event API fallback |
-| `metrics.sloReport` | Metrics | Yes | Yes | SLO snapshot with rates, latency, and threshold findings |
-| `metrics.labelCatalog` | Metrics | Yes | Yes | Label discovery for a metric (live sampling + known hints) |
-| `metrics.metricCatalog` | Metrics | Yes | Yes | Documented Fluent metric families with labels, examples, live probing |
-| `metrics.planQuery` | Metrics | No | No | Generate validated PromQL for any documented metric family |
-| `metrics.snapshot` | Metrics | Yes | Yes | One-call dashboard snapshot for volume, failures, and latency |
-| `metrics.compare` | Metrics | Yes | Yes | Compare two adjacent windows for a metric and highlight deltas |
-| `time.resolveWindow` | Time | Yes | Yes | Resolve natural-language time phrases into exact `from` / `to` timestamps |
-| `metrics.mutationAudit` | Metrics | Yes | Yes | Audit GraphQL create/update mutation traffic by domain, subdomain, and operation |
-| `metrics.topEvents` | Metrics | Yes | Yes | Ranked event analytics using Event API aggregation |
-| `workflow.transitions` | Orchestration | Yes | Yes | Query available user actions/transitions at any entity state |
-| `plugin.list` | Orchestration | Yes | Yes | List registered rules with optional name filter |
-| `graphql.query` | GraphQL | Yes | Varies | Execute single-page query or mutation (retries for queries only) |
-| `graphql.queryAll` | GraphQL | Yes | Yes | Auto-paginated query — follows cursors across all pages |
-| `graphql.batchMutate` | GraphQL | Yes | No | Execute up to 50 aliased mutations in one request |
-| `graphql.introspect` | GraphQL | Yes | Yes | Schema introspection (types, mutations, queries) with force-refresh |
-| `graphql.listRoots` | GraphQL | Yes | Yes | List all query and mutation root fields from the live schema |
-| `graphql.planOperation` | GraphQL | Yes | Yes | Plan a query or mutation: required args, variables skeleton, selection template, execution guidance |
-| `graphql.buildQuery` | GraphQL | Yes | Varies | Generate query/mutation from structured inputs with optional validation |
-| `graphql.validate` | GraphQL | Yes | Yes | Validate a GraphQL document against the live schema |
-| `graphql.generateFull` | GraphQL | Yes | Yes | Generate maximal-selection query for a root field (depth-limited) |
-| `batch.create` | Batch | Yes | No | Create ingestion job |
-| `batch.describePayload` | Batch | No | — | Describe entity-type-specific payload shape and example rows for batch.send |
-| `batch.send` | Batch | Yes | No | Send records to job |
-| `batch.status` | Batch | Yes | Yes | Check job status |
-| `batch.batchStatus` | Batch | Yes | Yes | Check specific batch within a job |
-| `batch.results` | Batch | Yes | Yes | Get per-record job outcomes |
-| `webhook.validate` | Webhooks | No | — | Validate webhook payload + optional signature verification |
-| `entity.planCreate` | Entity | No | — | Plan an entity create mutation locally with required fields, skeleton, and gotchas |
-| `entity.planUpdate` | Entity | No | — | Plan an entity update mutation locally with updatable fields, skeleton, and guidance |
-| `entity.create` | Entity | Yes | No | Type-safe entity creation with field validation and gotcha knowledge (12 entity types) |
-| `entity.update` | Entity | Yes | No | Status-aware entity updates with optional transition validation |
-| `entity.get` | Entity | Yes | Yes | Unified entity lookup by ID or ref with optional edge inclusion |
-| `workflow.get` | Workflow Mgmt | Yes | Yes | Fetch specific workflow by entityType + entitySubtype via REST API |
-| `workflow.list` | Workflow Mgmt | Yes | Yes | List all workflows for a retailer (deduplicated to latest versions) |
-| `workflow.upload` | Workflow Mgmt | Yes | No | Deploy workflow JSON via REST API with structure validation and preflight safety analysis |
-| `workflow.diff` | Workflow Mgmt | No | — | Compare two workflows — rulesets, statuses, risk assessment, mermaid output |
-| `workflow.simulate` | Workflow Mgmt | No | — | Static prediction of event outcomes from workflow JSON |
-| `setting.get` | Settings | Yes | Yes | Fetch settings by name (wildcards supported), optionally save to local file |
-| `setting.upsert` | Settings | Yes | No | Create or update a setting with upsert semantics |
-| `setting.bulkUpsert` | Settings | Yes | No | Batch create/update up to 50 settings with per-setting error handling |
-| `environment.discover` | Environment | Yes | Yes | Full environment snapshot — retailer, locations, networks, catalogues, settings, modules |
-| `environment.validate` | Environment | Yes | Yes | Pre-flight validation checks: auth, retailer, locations, inventory, workflows |
-| `test.assert` | Test | Yes | Yes | Assert entity state with status, attribute, and edge assertions + polling mode |
-| `cache.status` | Cache | No | — | Show local cache statistics — entry count, size, hit/miss rate, per-category breakdown |
-| `cache.clear` | Cache | No | — | Clear cached entries by pattern or all — no API call, local filesystem only |
+| `config_validate` | Diagnostics | No | — | Validate auth/base URL configuration |
+| `health_ping` | Diagnostics | No | — | Quick health check with config summary |
+| `connection_test` | Diagnostics | Yes | Yes | Full auth + GraphQL end-to-end test (returns user/account context) |
+| `connection_list` | Connection | No | — | List registered profiles with auth strategy and init status |
+| `connection_add` | Connection | No | — | Add a profile at runtime (CLI profile or explicit credentials) |
+| `connection_remove` | Connection | No | — | Remove a non-default profile |
+| `connection_switch` | Connection | No | — | Switch the default profile |
+| `event_build` | Events | No | — | Build event payload (no API call) |
+| `event_send` | Events | Yes | No | Send event (async/sync, supports dryRun) |
+| `event_get` | Events | Yes | Yes | Get single event by ID |
+| `event_list` | Events | Yes | Yes | List/filter events with pagination and optional analysis mode |
+| `event_flowInspect` | Events | Yes | Yes | One-call root-entity flow forensics with compact/full modes |
+| `metrics_query` | Metrics | Yes | Yes | Query Prometheus metrics (instant/range) |
+| `metrics_healthCheck` | Metrics | Yes | Yes | One-call anomaly assessment with Prometheus + Event API fallback |
+| `metrics_sloReport` | Metrics | Yes | Yes | SLO snapshot with rates, latency, and threshold findings |
+| `metrics_labelCatalog` | Metrics | Yes | Yes | Label discovery for a metric (live sampling + known hints) |
+| `metrics_metricCatalog` | Metrics | Yes | Yes | Documented Fluent metric families with labels, examples, live probing |
+| `metrics_planQuery` | Metrics | No | No | Generate validated PromQL for any documented metric family |
+| `metrics_snapshot` | Metrics | Yes | Yes | One-call dashboard snapshot for volume, failures, and latency |
+| `metrics_compare` | Metrics | Yes | Yes | Compare two adjacent windows for a metric and highlight deltas |
+| `time_resolveWindow` | Time | Yes | Yes | Resolve natural-language time phrases into exact `from` / `to` timestamps |
+| `metrics_mutationAudit` | Metrics | Yes | Yes | Audit GraphQL create/update mutation traffic by domain, subdomain, and operation |
+| `metrics_topEvents` | Metrics | Yes | Yes | Ranked event analytics using Event API aggregation |
+| `workflow_transitions` | Orchestration | Yes | Yes | Query available user actions/transitions at any entity state |
+| `plugin_list` | Orchestration | Yes | Yes | List registered rules with optional name filter |
+| `graphql_query` | GraphQL | Yes | Varies | Execute single-page query or mutation (retries for queries only) |
+| `graphql_queryAll` | GraphQL | Yes | Yes | Auto-paginated query — follows cursors across all pages |
+| `graphql_batchMutate` | GraphQL | Yes | No | Execute up to 50 aliased mutations in one request |
+| `graphql_introspect` | GraphQL | Yes | Yes | Schema introspection (types, mutations, queries) with force-refresh |
+| `graphql_listRoots` | GraphQL | Yes | Yes | List all query and mutation root fields from the live schema |
+| `graphql_planOperation` | GraphQL | Yes | Yes | Plan a query or mutation: required args, variables skeleton, selection template, execution guidance |
+| `graphql_buildQuery` | GraphQL | Yes | Varies | Generate query/mutation from structured inputs with optional validation |
+| `graphql_validate` | GraphQL | Yes | Yes | Validate a GraphQL document against the live schema |
+| `graphql_generateFull` | GraphQL | Yes | Yes | Generate maximal-selection query for a root field (depth-limited) |
+| `batch_create` | Batch | Yes | No | Create ingestion job |
+| `batch_describePayload` | Batch | No | — | Describe entity-type-specific payload shape and example rows for batch_send |
+| `batch_send` | Batch | Yes | No | Send records to job |
+| `batch_status` | Batch | Yes | Yes | Check job status |
+| `batch_batchStatus` | Batch | Yes | Yes | Check specific batch within a job |
+| `batch_results` | Batch | Yes | Yes | Get per-record job outcomes |
+| `webhook_validate` | Webhooks | No | — | Validate webhook payload + optional signature verification |
+| `entity_planCreate` | Entity | No | — | Plan an entity_create mutation locally with required fields, skeleton, and gotchas |
+| `entity_planUpdate` | Entity | No | — | Plan an entity_update mutation locally with updatable fields, skeleton, and guidance |
+| `entity_create` | Entity | Yes | No | Type-safe entity creation with field validation and gotcha knowledge (12 entity types) |
+| `entity_update` | Entity | Yes | No | Status-aware entity updates with optional transition validation |
+| `entity_get` | Entity | Yes | Yes | Unified entity lookup by ID or ref with optional edge inclusion |
+| `workflow_get` | Workflow Mgmt | Yes | Yes | Fetch specific workflow by entityType + entitySubtype via REST API |
+| `workflow_list` | Workflow Mgmt | Yes | Yes | List all workflows for a retailer (deduplicated to latest versions) |
+| `workflow_upload` | Workflow Mgmt | Yes | Yes | Deploy workflow JSON via REST API PUT (idempotent upsert) with structure validation and preflight safety analysis |
+| `workflow_diff` | Workflow Mgmt | No | — | Compare two workflows — rulesets, statuses, risk assessment, mermaid output |
+| `workflow_simulate` | Workflow Mgmt | No | — | Static prediction of event outcomes from workflow JSON |
+| `setting_get` | Settings | Yes | Yes | Fetch settings by name (wildcards supported), optionally save to local file |
+| `setting_upsert` | Settings | Yes | No | Create or update a setting with upsert semantics |
+| `setting_bulkUpsert` | Settings | Yes | No | Batch create/update up to 50 settings with per-setting error handling |
+| `environment_discover` | Environment | Yes | Yes | Full environment snapshot — retailer, locations, networks, catalogues, settings, modules |
+| `environment_validate` | Environment | Yes | Yes | Pre-flight validation checks: auth, retailer, locations, inventory, workflows |
+| `test_assert` | Test | Yes | Yes | Assert entity state with status, attribute, and edge assertions + polling mode |
+| `cache_status` | Cache | No | — | Show local cache statistics — entry count, size, hit/miss rate, per-category breakdown |
+| `cache_clear` | Cache | No | — | Clear cached entries by pattern or all — no API call, local filesystem only |