@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.0

package/docs/TOOL_REFERENCE.md

@@ -1114,697 +1114,43 @@ Response:
 
 ---
 
-## `entity.create`
-
-Type-safe entity creation with built-in validation and gotcha knowledge.
-
-**Supported entity types:** ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT, INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER, SETTING
-
-- **Required**:
-  - `entityType`: entity type string (see supported list above)
-  - `data`: creation input fields matching the GraphQL create input type
-- **Optional**:
-  - `returnFields`: array of field names to return (defaults to entity type defaults)
-  - `dryRun`: if `true`, builds and validates the mutation without executing (default `false`)
-
-**Key behaviors:**
-
-- Validates required fields BEFORE sending (e.g., Location requires `openingSchedule`)
-- Encodes compound key rules (ProductKey needs `ref` + `catalogue.ref`)
-- Auto-resolves `retailerId` from config for retailer-scoped entities
-- Returns the executed mutation string for audit trail
-
-**Known gotchas (encoded in validation):**
-
-- No create inputs have a `status` field — status is auto-set to `CREATED`
-- `Customer` has NO `ref` field; `username` is the identifier
-- `Network` uses `name` (not `ref`) in create; `retailers` is a plural array
-- `Location` requires `openingSchedule` even for 24/7 (use `allHours: true`)
-- `Product` `gtin` has a 20-character max
-- `Setting` `context` is a plain String, `contextId` is a separate Int
-
-**Example** — create a location (dry run):
-
-```json
-{
-  "entityType": "LOCATION",
-  "data": {
-    "ref": "LOC_WH_01",
-    "type": "WAREHOUSE",
-    "name": "Main Warehouse",
-    "openingSchedule": { "allHours": true }
-  },
-  "dryRun": true
-}
-```
-
-Response (dry run):
-
-```json
-{
-  "ok": true,
-  "dryRun": true,
-  "entityType": "LOCATION",
-  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { createLocation(input: $input) { id ref status type name } }",
-  "inputType": "CreateLocationInput",
-  "variables": { "input": { "ref": "LOC_WH_01", "type": "WAREHOUSE", "name": "Main Warehouse", "openingSchedule": { "allHours": true } } },
-  "requiredFields": ["ref", "type", "name", "openingSchedule"],
-  "gotchas": ["Location requires openingSchedule — use { allHours: true } for 24/7"],
-  "note": "No API call made. Set dryRun=false to execute."
-}
-```
-
-**Example** — create a location (real):
-
-```json
-{
-  "entityType": "LOCATION",
-  "data": {
-    "ref": "LOC_WH_01",
-    "type": "WAREHOUSE",
-    "name": "Main Warehouse",
-    "openingSchedule": { "allHours": true }
-  }
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "entityType": "LOCATION",
-  "entity": { "id": "42", "ref": "LOC_WH_01", "status": "CREATED", "type": "WAREHOUSE", "name": "Main Warehouse" },
-  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { ... }"
-}
-```
-
----
-
-## `entity.update`
-
-Status-aware entity updates with optional transition validation.
-
-- **Required**:
-  - `entityType`: entity type string
-  - `id`: entity ID (required for updates)
-  - `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`)
-
-**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
-- Returns the previous status for audit trail when transition validation is used
-- Uses no-retry semantics (write operation)
-
-**Example** — update order status with transition validation:
-
-```json
-{
-  "entityType": "ORDER",
-  "id": "12345",
-  "fields": { "status": "COMPLETE" },
-  "validateTransition": true
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
-  "mutation": "mutation UpdateOrder($input: UpdateOrderInput!) { ... }"
-}
-```
-
-If no workflow transition exists:
-
-```json
-{
-  "ok": true,
-  "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."
-}
-```
-
----
-
-## `entity.get`
-
-Unified entity lookup by ID or ref with optional edge inclusion.
-
-- **Required**:
-  - `entityType`: entity type string
-  - At least one of `id` or `ref`
-- **Optional**:
-  - `id`: entity ID (preferred lookup method)
-  - `ref`: entity ref (fallback — not available for CUSTOMER)
-  - `fields`: array of field names to return (defaults to entity type defaults: id, ref, status, type, createdOn, etc.)
-  - `includeEdges`: array of related entity edges to fetch (e.g., `["fulfilments", "items", "attributes"]`)
-
-**Key behaviors:**
-
-- Prefers ID-based lookup (single entity query) over ref-based lookup (connection query)
-- Ref-based lookup uses the connection query pattern (edges/node)
-- Returns `{ found: false }` when entity is not found (not an error)
-- CUSTOMER entity type does not support ref-based lookup
-
-**Example** — get order by ref with fulfilments:
-
-```json
-{
-  "entityType": "ORDER",
-  "ref": "HD-001",
-  "includeEdges": ["fulfilments"]
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "found": true,
-  "entityType": "ORDER",
-  "entity": {
-    "id": "12345",
-    "ref": "HD-001",
-    "status": "BOOKED",
-    "type": "HD",
-    "fulfilments": {
-      "edges": [
-        { "node": { "id": "67890", "ref": "FUL-001", "status": "CREATED" } }
-      ]
-    }
-  }
-}
-```
-
----
-
-## `workflow.upload`
-
-Deploy a workflow JSON definition to the Fluent environment.
-
-Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoint the Fluent CLI uses.
-
-- **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`)
-
-**Validation checks:**
-
-- `name` field present
-- At least one status defined in `statuses` array
-- All rulesets have `name`, `triggers`, and `rules` (warns if empty)
-
-**Important:** 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 validation:
-
-```json
-{
-  "workflow": {
-    "name": "ORDER::HD",
-    "type": "ORDER",
-    "subtype": "HD",
-    "statuses": [{ "name": "CREATED" }, { "name": "BOOKED" }],
-    "rulesets": [
-      {
-        "name": "BookOrder",
-        "triggers": [{ "status": "CREATED" }],
-        "rules": [{ "name": "com.fluentretail.rubix.rule.order.SendEventOnVerifyingState", "props": { "status": "BOOKED" } }]
-      }
-    ]
-  },
-  "dryRun": true
-}
-```
-
-Response (dry run — valid):
-
-```json
-{
-  "ok": true,
-  "dryRun": true,
-  "valid": true,
-  "workflowName": "ORDER::HD",
-  "retailerId": "5",
-  "note": "Validation passed. Set dryRun=false to deploy."
-}
-```
-
----
-
-## `workflow.diff`
-
-Compare two workflow JSON definitions and identify changes.
-
-Pure local computation — no API calls.
-
-- **Required**:
-  - `base`: base workflow JSON (before changes)
-  - `target`: target workflow JSON (after changes)
-- **Optional**:
-  - `format`: output format — `summary` (default), `detailed`, or `mermaid`
-
-**Comparison scope:**
-
-- Rulesets: added, removed, modified (trigger changes, rule additions/removals, prop changes)
-- Statuses: added, removed
-- Risk assessment: removing rulesets or statuses = HIGH, modifying props = MEDIUM, adding = LOW
-
-**Formats:**
-
-| Format | Returns |
-|---|---|
-| `summary` | Change counts, status changes, risk level |
-| `detailed` | Full `WorkflowDiffResult` object with per-ruleset breakdown |
-| `mermaid` | `stateDiagram-v2` with color-coded added/removed/modified states and transitions |
-
-**Example** — summary diff:
-
-```json
-{
-  "base": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
-  "target": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
-  "format": "summary"
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "summary": "3 ruleset change(s): 1 added, 0 removed, 2 modified. 1 status change(s): 1 added, 0 removed. Risk level: MEDIUM.",
-  "riskLevel": "medium",
-  "rulesetChanges": { "added": 1, "removed": 0, "modified": 2 },
-  "statusChanges": { "added": ["AWAITING_PICKUP"], "removed": [] }
-}
-```
-
----
-
-## `workflow.simulate`
-
-Static prediction of workflow event outcomes from workflow JSON.
-
-Pure local computation — no API calls. Parses workflow JSON to find matching rulesets and predict state transitions, follow-on events, and webhook side effects.
-
-- **Required**:
-  - `workflow`: workflow JSON definition (as object or JSON string)
-  - `currentStatus`: entity status to simulate from (e.g., `CREATED`, `BOOKED`)
-- **Optional**:
-  - `eventName`: event name to match against ruleset names (if omitted, returns all rulesets triggered by `currentStatus`)
-  - `entityType`: entity type filter for trigger matching
-  - `entitySubtype`: entity subtype filter for trigger matching
-
-**What it does:**
-
-- Finds rulesets whose triggers match `currentStatus` (and optionally `eventName`)
-- Extracts `SetState`/`ChangeState` rules → predicted next status
-- Extracts `SendEvent` rules → predicted follow-on events
-- Extracts `SendWebhook` rules → predicted webhook side effects
-- Identifies custom Java rules that cannot be statically predicted
-
-**Important limitations (always disclosed in response):**
-
-- **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
-
-**Example** — simulate from CREATED status:
-
-```json
-{
-  "workflow": { "name": "ORDER::HD", "rulesets": [...] },
-  "currentStatus": "CREATED",
-  "eventName": "BookOrder"
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "workflowName": "ORDER::HD",
-  "currentStatus": "CREATED",
-  "eventName": "BookOrder",
-  "matchedRulesets": 1,
-  "rulesets": [
-    {
-      "name": "BookOrder",
-      "matchType": "statusAndEvent",
-      "predictedStatus": "BOOKED",
-      "predictedEvents": ["SendToFulfilment"],
-      "predictedWebhooks": [],
-      "ruleCount": 3
-    }
-  ],
-  "prediction": {
-    "likelyNextStatus": "BOOKED",
-    "followOnEvents": ["SendToFulfilment"],
-    "webhookSideEffects": [],
-    "confidence": "low",
-    "note": "Custom rules present — prediction may be incomplete or wrong."
-  },
-  "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."
-  ]
-}
-```
-
----
-
-## `setting.upsert`
-
-Create or update a Fluent Commerce setting with upsert semantics.
-
-Queries existing settings by `name` + `context` + `contextId` first. Creates if missing, updates if exists.
-
-- **Required**:
-  - `name`: setting key/name
-  - `value`: setting value (for small values)
-  - `context`: setting scope — `RETAILER`, `ACCOUNT`, `LOCATION`, `NETWORK`, `AGENT`, `CUSTOMER`
-- **Optional**:
-  - `lobValue`: large object value for JSON payloads > 4KB (mutually exclusive with `value`)
-  - `contextId`: context ID (e.g., retailer ID). Defaults to `FLUENT_RETAILER_ID` for `RETAILER` context.
-
-**Key gotchas:**
-
-- `context` is a plain String (`"RETAILER"`), NOT an object
-- `contextId` is a separate Int field
-- For large JSON values (> 4KB), use `lobValue` instead of `value`
-- Returns `created: true/false` for audit trail
-
-**Example** — create a webhook URL setting:
-
-```json
-{
-  "name": "WEBHOOK_ORDER_NOTIFICATION",
-  "value": "https://api.example.com/webhooks/orders",
-  "context": "RETAILER"
-}
-```
-
-Response (created):
-
-```json
-{
-  "ok": true,
-  "created": true,
-  "updated": false,
-  "setting": {
-    "id": "99",
-    "name": "WEBHOOK_ORDER_NOTIFICATION",
-    "value": "https://api.example.com/webhooks/orders",
-    "context": "RETAILER",
-    "contextId": 5
-  }
-}
-```
-
-Response (updated existing):
-
-```json
-{
-  "ok": true,
-  "created": false,
-  "updated": true,
-  "setting": { "id": "99", "name": "WEBHOOK_ORDER_NOTIFICATION", "value": "https://api.example.com/webhooks/orders-v2", "context": "RETAILER", "contextId": 5 },
-  "previousValue": "https://api.example.com/webhooks/orders"
-}
-```
-
----
-
-## `setting.bulkUpsert`
-
-Batch create or update multiple settings in one call.
-
-Processes up to 50 settings sequentially with individual error handling. Each setting is an independent upsert — failures on one setting don't block others.
-
-- **Required**:
-  - `settings`: array of setting objects (min 1, max 50), each with `name`, `value`, `context`, and optional `lobValue` and `contextId`
-
-**Example** — bulk create 3 settings:
-
-```json
-{
-  "settings": [
-    { "name": "WEBHOOK_ORDER_URL", "value": "https://api.example.com/orders", "context": "RETAILER" },
-    { "name": "WEBHOOK_FULFILMENT_URL", "value": "https://api.example.com/fulfilments", "context": "RETAILER" },
-    { "name": "FEATURE_FLAG_RETURNS", "value": "true", "context": "RETAILER" }
-  ]
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "created": 2,
-  "updated": 1,
-  "failed": 0,
-  "total": 3,
-  "results": [
-    { "name": "WEBHOOK_ORDER_URL", "status": "created" },
-    { "name": "WEBHOOK_FULFILMENT_URL", "status": "created" },
-    { "name": "FEATURE_FLAG_RETURNS", "status": "updated" }
-  ]
-}
-```
-
----
-
-## `environment.discover`
-
-Full environment snapshot in one call.
-
-Returns everything an agent needs to understand the Fluent environment: retailer details, locations, networks, catalogues, workflows, settings, modules, and user context.
-
-- **Optional**:
-  - `include`: array of sections to include. Default: `["retailer", "locations", "networks", "catalogues"]`. Available: `retailer`, `locations`, `networks`, `catalogues`, `workflows`, `settings`, `modules`, `users`
-
-**Limitations:**
-
-- Locations and settings return the first 100 items only (no auto-pagination)
-- Workflows section uses a transition API probe — may miss workflows with no user actions at the initial state. Use `fluent workflow list` via CLI for definitive listing.
-
-**Example** — discover retailer, locations, and settings:
-
-```json
-{
-  "include": ["retailer", "locations", "settings"]
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "retailer": { "id": "5", "ref": "HM_TEST", "tradingName": "HM Test", "status": "ACTIVE" },
-  "locations": [
-    { "id": "10", "ref": "LOC_WH_01", "type": "WAREHOUSE", "status": "ACTIVE", "name": "Main Warehouse" }
-  ],
-  "settings": [
-    { "name": "WEBHOOK_ORDER_URL", "value": "https://...", "context": "RETAILER", "contextId": 5 }
-  ]
-}
-```
-
----
-
-## `environment.validate`
-
-Pre-flight environment validation. Runs configurable checks before E2E tests or deployments.
-
-- **Optional**:
-  - `checks`: array of checks to run. Default: `["auth", "retailer", "locations"]`. Available: `auth`, `retailer`, `locations`, `inventory`, `workflows`, `settings`, `modules`
-
-**Available checks:**
-
-| Check | What it validates |
-|---|---|
-| `auth` | Token valid, permissions sufficient |
-| `retailer` | Retailer exists and is active |
-| `locations` | At least one warehouse location exists |
-| `inventory` | At least one product with stock |
-| `workflows` | Key workflows deployed (ORDER, FULFILMENT) |
-| `settings` | Critical settings exist |
-| `modules` | Expected modules deployed |
-
-Returns pass/fail per check with severity and actionable messages.
-
-**Example** — full pre-flight validation:
-
-```json
-{
-  "checks": ["auth", "retailer", "locations", "workflows", "settings"]
-}
-```
-
-Response:
-
-```json
-{
-  "ok": true,
-  "results": [
-    { "check": "auth", "passed": true, "severity": "critical", "message": "Authenticated as admin@example.com" },
-    { "check": "retailer", "passed": true, "severity": "critical", "message": "Retailer HM_TEST (ID 5) is ACTIVE" },
-    { "check": "locations", "passed": true, "severity": "high", "message": "Found 3 locations (2 warehouses)" },
-    { "check": "workflows", "passed": false, "severity": "high", "message": "Missing workflow: FULFILMENT_OPTIONS::HD" },
-    { "check": "settings", "passed": true, "severity": "medium", "message": "12 retailer settings found" }
-  ],
-  "summary": { "passed": 4, "failed": 1, "total": 5 }
-}
-```
-
----
-
-## `test.assert`
-
-Assert entity state matches expectations with optional polling.
-
-Deep assertion on entity fields, attributes, and edge counts/statuses with human-readable failure messages.
-
-- **Required**:
-  - `entityType`: entity type (ORDER, FULFILMENT, etc.)
-  - `assertions`: object with expected values
-- **Optional**:
-  - `id`: entity ID (preferred)
-  - `ref`: entity ref (fallback)
-  - `poll`: if `true`, retry until assertions pass or timeout (default `false`)
-  - `timeoutMs`: polling timeout in ms, 1000–300000 (default `60000`)
-  - `intervalMs`: polling interval in ms, 1000–30000 (default `5000`)
-
-**Assertion types:**
-
-| Assertion | Description |
-|---|---|
-| `status` | Exact match on entity status |
-| `type` | Exact match on entity type |
-| `subtype` | Exact match on entity subtype |
-| `attributes` | Key-value pairs that must be present on the entity |
-| `edges` | Min/max count and status on related entities (e.g., fulfilments) |
-
-**Polling mode:** Set `poll: true` to retry assertions on an interval until they pass or the timeout is reached. Useful after sending events when state changes are asynchronous.
-
-**Example** — assert order is BOOKED with at least 1 fulfilment (polling):
-
-```json
-{
-  "entityType": "ORDER",
-  "ref": "HD-001",
-  "assertions": {
-    "status": "BOOKED",
-    "edges": {
-      "fulfilments": { "minCount": 1 }
-    }
-  },
-  "poll": true,
-  "timeoutMs": 60000,
-  "intervalMs": 5000
-}
-```
-
-Response (pass):
-
-```json
-{
-  "ok": true,
-  "passed": true,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "BOOKED" },
-  "assertions": {
-    "status": { "expected": "BOOKED", "actual": "BOOKED", "passed": true },
-    "edges.fulfilments.minCount": { "expected": 1, "actual": 2, "passed": true }
-  },
-  "polling": { "attempts": 3, "elapsed": 12500 }
-}
-```
-
-Response (fail after timeout):
-
-```json
-{
-  "ok": true,
-  "passed": false,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "CREATED" },
-  "assertions": {
-    "status": { "expected": "BOOKED", "actual": "CREATED", "passed": false }
-  },
-  "polling": { "attempts": 12, "elapsed": 60000, "timedOut": true },
-  "failureMessage": "Assertion failed: status expected \"BOOKED\" but got \"CREATED\" (timed out after 60000ms)"
-}
-```
-
----
-
 ## Retry and idempotency matrix
 
 | Category | Tools | Retry behavior |
 |------|----------|-------------|
-| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test`, `entity.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`, `event.build`, `webhook.validate`, `workflow.diff`, `workflow.simulate` | not applicable |
-
-## Tool inventory summary (36 tools)
-
-| 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) |
-| `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.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) |
-| `batch.create` | Batch | Yes | No | Create ingestion job |
-| `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.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.upload` | Workflow Mgmt | Yes | No | Deploy workflow JSON via REST API with structure validation |
-| `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.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 |
+| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test` | retry + backoff |
+| Write operations | `event.send`, `batch.create`, `batch.send`, `graphql.query` (mutation), `graphql.batchMutate` | timeout-only (no automatic retry) |
+| Local validation / no API | `config.validate`, `health.ping`, `event.build`, `webhook.validate` | not applicable |
+
+## Tool inventory summary
+
+| Tool | Category | Requires SDK | Description |
+|------|----------|:------------:|-------------|
+| `config.validate` | Config | No | Validate auth/base URL configuration |
+| `health.ping` | Config | No | Quick health check with config summary |
+| `event.build` | Events | No | Build event payload (no API call) |
+| `event.send` | Events | Yes | Send event (async/sync, supports dryRun) |
+| `event.get` | Events | Yes | Get single event by ID |
+| `event.list` | Events | Yes | List/filter events with pagination |
+| `event.flowInspect` | Events | Yes | One-call root-entity flow forensics (mutations/webhooks/scheduled/exceptions/no-match/rules/snapshots/cross-entity) |
+| `metrics.query` | Metrics | Yes | Query Prometheus metrics (instant/range) |
+| `metrics.healthCheck` | Metrics | Yes | One-call anomaly assessment with fallback |
+| `metrics.sloReport` | Metrics | Yes | SLO snapshot with rates, latency, and threshold findings |
+| `metrics.labelCatalog` | Metrics | Yes | Label discovery for a metric (live sampling + known hints) |
+| `metrics.topEvents` | Metrics | Yes | Ranked event analytics using Event API aggregation |
+| `workflow.transitions` | Workflow | Yes | Query available user actions/transitions at any entity state |
+| `graphql.query` | GraphQL | Yes | Execute single-page query or mutation |
+| `graphql.queryAll` | GraphQL | Yes | Auto-paginated query (all records) |
+| `graphql.batchMutate` | GraphQL | Yes | Multiple aliased mutations in one request |
+| `graphql.introspect` | GraphQL | Yes | Schema introspection (types, mutations) |
+| `batch.create` | Batch | Yes | Create ingestion job |
+| `batch.send` | Batch | Yes | Send records to job |
+| `batch.status` | Batch | Yes | Check job status |
+| `batch.batchStatus` | Batch | Yes | Check specific batch status |
+| `batch.results` | Batch | Yes | Get per-record job outcomes |
+| `plugin.list` | Orchestration | Yes | List registered rules with optional name filter |
+| `connection.test` | Diagnostics | Yes | Full connectivity test (user/retailer/location) |
+| `webhook.validate` | Webhooks | No* | Validate webhook payload + signature |
+
+\* `webhook.validate` does not call Fluent APIs. Signature validation uses local crypto.