@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/connections.js

@@ -1,23 +1,128 @@
 import { z } from "zod";
-import { formatResult, autoFormatTable, readOnly, creating, mutating, destructive, errorWithSuggestion, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, pickFields, createProgressReporter, elicitChoice, } from "@getimo/mcp-toolkit";
 import { request, hintFor, WP_BASE, WP_USER, authConfigured } from "./client.js";
+import { restErrorResult } from "./tool-result.js";
+import { toRows } from "./types.js";
 import { unwrapEntity } from "./envelope.js";
-export function registerConnectionTools(server) {
+import { ambiguityFallbackError, } from "./elicitation.js";
+import { fetchWithTimeout } from "./diagnose.js";
+import { filterByNameQuery } from "./node-schema.js";
+import { CONNECTION_TABLE_COLUMNS, CONNECTION_COMPACT_COLUMNS, CONNECTION_LIST_NEXT_STEPS, RESOURCE_TABLE_COLUMNS, mapConnectionRow, compactConnectionRow, mapResourceRow, buildConnectionDetail, buildConnectionTestStats, buildHealthCheckStats, buildHealthStats, } from "./connections-format.js";
+// W3 Stage-2 hardening — applyTrim + extractResourceList live in the
+// sibling connections-trim.ts (pure functions, ~200 lines). Imported for
+// internal use by the connection_data + connection_resources handlers,
+// and re-exported so the public surface
+// `import { ... } from "./connections.js"` stays unchanged for existing
+// callers and the test suite.
+import { applyTrim, extractResourceList, } from "./connections-trim.js";
+export { applyTrim, extractResourceList };
+// F-LS-04 (live-smoke 2026-05-20) — the PHP /connections endpoint emits
+// camelCase keys (authType, credentialId, ...). Every formatter + consumer
+// in this module reads snake_case. The wire-shape normaliser bridges
+// the two so the AI no longer sees auth=none / credential=— on real
+// upstream connections. Applied at the connection_list handler — that is
+// the only tool that fans out raw connection items to a downstream
+// formatter; connection_get / _update / _delete pass through unwrapEntity
+// + the rich-card builder which already reads from the same row map.
+import { normalizeConnectionFromWire } from "./normalizers.js";
+/**
+ * F-15 (W1.9) — downstream probe of api.wootsup.com from `apimapper_health`.
+ *
+ * The customer's WP-REST probe alone cannot distinguish "your server is fine
+ * but getimo's license/release infra is degraded" from a generic failure.
+ * Hitting the upstream `/health` endpoint surfaces that signal so an AI
+ * client can route the user to the right troubleshooting branch.
+ */
+const APIMAPPER_API_HEALTH_URL = "https://api.wootsup.com/health";
+/**
+ * 3-second budget — health is meant to be a fast snapshot. Shorter than
+ * diagnose's 5s because diagnose probes a customer-controlled server (which
+ * may legitimately be slow under load), while api.wootsup.com is
+ * getimo-controlled CDN-backed infra that should respond in <500ms.
+ */
+const APIMAPPER_API_HEALTH_TIMEOUT_MS = 3_000;
+/**
+ * F-15: probe api.wootsup.com/health and map the outcome to a stable
+ * status-string. NEVER throws — the health tool's contract is to surface
+ * downstream failure as data, not to fail itself when the downstream is
+ * unreachable. The four return values form a closed enum:
+ *
+ *   - "OK"           — 2xx response from api.wootsup.com
+ *   - "HTTP N"       — non-2xx response (e.g. "HTTP 503")
+ *   - "timeout"      — AbortError/TimeoutError after 3s
+ *   - "unreachable"  — any other fetch error (DNS, refused, TLS, etc.)
+ *
+ * Reuses fetchWithTimeout from diagnose.ts so the AbortSignal.timeout
+ * wiring lives in exactly one place (DRY across probe call sites).
+ */
+async function probeApimapperApi() {
+    try {
+        const res = await fetchWithTimeout(APIMAPPER_API_HEALTH_URL, { method: "GET" }, APIMAPPER_API_HEALTH_TIMEOUT_MS);
+        if (res.ok)
+            return "OK";
+        return `HTTP ${res.status}`;
+    }
+    catch (e) {
+        if (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError")) {
+            return "timeout";
+        }
+        return "unreachable";
+    }
+}
+/**
+ * Register the connection CRUD + probe + sample + pipeline tools.
+ *
+ * @param server      the tool registrar (essentials forward, rest captured).
+ * @param elicitation optional elicitation capability (the real McpServer, or
+ *   any `{ server: { elicitInput } }`). Supplied only by the host wiring in
+ *   index.ts. When omitted, `connection_create` falls back to a structured
+ *   error on genuine credential ambiguity instead of prompting.
+ */
+export function registerConnectionTools(server, elicitation) {
     // ── apimapper_health ───────────────────────────────────────────────
     server.registerTool("apimapper_health", {
         title: "API Mapper REST Health",
         description: "Check connectivity + auth against the API Mapper REST namespace. " +
-            "Returns {wp_base, wp_user, auth, connectivity, connection_count, http_status}. " +
+            "Returns {wp_base, wp_user, auth, connectivity, connection_count, http_status, apimapper_api_status}. " +
+            "`apimapper_api_status` reports the downstream api.wootsup.com health (OK/HTTP N/timeout/unreachable) " +
+            "so a degradation of getimo infra is distinguishable from a customer-server issue. " +
             "Run this first if any other tool fails." +
             "\n\nExample:\n  apimapper_health({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Health Check", openWorld: true }),
     }, async () => {
         const checks = {
             wp_base: WP_BASE,
             wp_user: WP_USER,
             auth: authConfigured() ? "configured" : "MISSING (set APIMAPPER_WP_APP_PASS)",
         };
+        // L-5 (W3F-5): when the customer uses bearer-only auth (the modern
+        // `amk_live_…` flow), APIMAPPER_WP_USER is intentionally unset, so
+        // the previous render emitted `WP user: ""`. Probe `/identity` and
+        // fall back to its `.username` field — it's anon-readable on both
+        // platforms and never throws. The probe is cheap (single GET) and
+        // runs alongside the existing api.wootsup.com probe.
+        if (checks.wp_user === "") {
+            try {
+                const idRes = await request("/identity");
+                const fromIdentity = idRes.success && typeof idRes.data?.username === "string"
+                    ? idRes.data.username
+                    : "";
+                if (fromIdentity !== "") {
+                    checks.wp_user = fromIdentity;
+                }
+            }
+            catch {
+                // Identity probe failure is non-fatal — the rest of the
+                // health snapshot still surfaces.
+            }
+        }
+        // F-15 (W1.9) — downstream api.wootsup.com probe. Runs before the
+        // WP-REST check; both are independent, but sequential is cheap (3s
+        // worst-case for the api probe, then the WP probe) and keeps the
+        // result ordering deterministic. Probe never throws — surfaces as
+        // status string per probeApimapperApi contract.
+        checks.apimapper_api_status = await probeApimapperApi();
         try {
             const r = await request("/connections");
             checks.http_status = r.status ?? 0;
@@ -32,92 +137,138 @@ export function registerConnectionTools(server) {
             }
         }
         catch (e) {
-            const err = errorWithSuggestion(e, { healthTool: "apimapper_health" });
-            checks.connectivity = `ERROR: ${err.message}`;
+            // A4 (Wave-B audit, 2026-06-03): this catch builds a STRING into the
+            // health-snapshot `checks` map and then continues to buildHealthStats —
+            // it is NOT an MCP error-result return, so the structured
+            // errorResult/restErrorResult builders do not apply here (they would
+            // early-return and abandon the snapshot). The lone `errorWithSuggestion`
+            // call is dropped in favour of the same raw, already-sanitised message
+            // the sibling `FAIL: ${r.error}` branch above surfaces — `request()`
+            // sanitises and never throws, so this remains a defensive guard.
+            const message = e instanceof Error ? e.message : String(e);
+            checks.connectivity = `ERROR: ${message}`;
         }
-        return formatResult(checks, false, { maxChars: 2000 });
+        // W3.1 — health snapshot is a flat scalar set: statsResult is the
+        // goldstandard fit. Every check becomes a stat so an AI client reads
+        // connectivity/auth/downstream state without parsing free text.
+        return buildHealthStats(checks);
     });
     // ── apimapper_connection_list ──────────────────────────────────────
     server.registerTool("apimapper_connection_list", {
         title: "List Connections",
-        description: "List all API Mapper connections. Use apimapper_connection_get for full details." +
-            "\n\nExample:\n  apimapper_connection_list({ source: 'user', limit: 25 })",
+        // rc.10 A5 (2026-05-19) — description states the default limit
+        // already covers a typical install. The Maria-walkthrough log
+        // showed AI defaulting to limit:200/500 reflexively.
+        description: "List all API Mapper connections. The default limit of 50 already covers a typical install — " +
+            "most customers run with 5-25 connections, increase the limit only if you have a specific " +
+            "reason to expect more. Use apimapper_connection_get for full details of a single connection." +
+            "\n\nExample:\n  apimapper_connection_list({})  // returns up to 50 connections in one call\n" +
+            "  apimapper_connection_list({ source: 'user' })  // narrow to user-created only",
         inputSchema: {
             source: z
                 .enum(["library", "demo", "user", "all"])
                 .default("all")
                 .describe("Filter by origin"),
-            limit: z.number().min(1).max(500).default(50).describe("Max items (1-500)"),
+            limit: z.number().min(1).max(500).default(50).describe("Max items (1-500). Default 50 already covers a typical install — do not raise unless you have evidence the list is larger."),
+            // W1.18 (F-32) — case-insensitive substring filter applied
+            // in-memory AFTER the upstream fetch (no per-name REST call).
+            // Min 2 chars at the schema boundary blocks the single-char
+            // probe-thrash pattern observed in the Maria-walkthrough logs.
+            name_query: z
+                .string()
+                .min(2)
+                .optional()
+                .describe("Case-insensitive substring filter on connection name. Applied in-memory after the upstream fetch — does NOT change the REST query. Must be 2+ characters; single-char probes are blocked. Combine with `source` for narrower results."),
         },
-        annotations: readOnly(),
-    }, async ({ source, limit }) => {
+        annotations: readOnly({ title: "List Connections", openWorld: true }),
+    }, async ({ source, limit, name_query }) => {
         const r = await request("/connections");
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { source, limit },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { source, limit, name_query }, { message: "connection list failed" });
         }
-        let items = Array.isArray(r.data?.connections) ? r.data.connections : [];
+        // F-LS-04 — normalise the camelCase wire shape (authType, credentialId,
+        // …) to snake_case BEFORE anything downstream reads it. The
+        // `Connection` domain type uses snake_case keys, so the result is
+        // safely cast back: `normalizeConnectionFromWire` only adds keys, it
+        // never drops them, and existing snake_case values win on collision.
+        const rawItems = Array.isArray(r.data?.connections) ? r.data.connections : [];
+        let items = rawItems.map((c) => normalizeConnectionFromWire(c));
         if (source !== "all")
             items = items.filter((c) => c.source === source);
+        // W1.18 (F-32) — filter BEFORE slice so limit applies to the matched
+        // subset, not the haystack. See `filterByNameQuery` JSDoc for the
+        // case-folding + undefined-skip contract shared with flow_list.
+        items = filterByNameQuery(items, name_query);
         items = items.slice(0, limit);
-        return autoFormatTable(items.map((c) => ({
-            id: c.id,
-            name: c.name,
-            source: c.source,
-            endpoint: c.endpoint || "(template)",
-            method: c.method || "GET",
-            auth_type: c.auth_type || "none",
-            credential_id: c.credential_id || "—",
-        })), {
-            columns: [
-                // Width 36 accommodates 30+ char IDs (e.g. legacy template
-                // connections like conn_calendly_jla_229fcbce95b7). Truncation
-                // produces orphan IDs that downstream tools fail to resolve
-                // via *_get; +6 headroom matches the longest historical IDs.
-                { key: "id", label: "ID", width: 36 },
-                { key: "name", label: "NAME", width: 28 },
-                { key: "source", label: "SRC", width: 8 },
-                { key: "endpoint", label: "ENDPOINT", width: 30 },
-                { key: "method", label: "M", width: 5 },
-                { key: "auth_type", label: "AUTH", width: 12 },
-                { key: "credential_id", label: "CRED", width: 26 },
-            ],
+        // W3.1 — tableResult: ASCII table for the LLM + typed DataTable payload
+        // for the Rich Card. T1 (W3.2): explicit compactColumns/compactMap drop
+        // ENDPOINT/METHOD/CRED at 21+ rows. IA-7: id stays llmOnly. IA-10: the
+        // footer carries the next-step guidance.
+        return tableResult(toRows(items), {
+            columns: CONNECTION_TABLE_COLUMNS,
+            compactColumns: CONNECTION_COMPACT_COLUMNS,
+            map: mapConnectionRow,
+            compactMap: compactConnectionRow,
             header: (n) => `${n} connections`,
-            footer: "Use apimapper_connection_get <id> for full details.",
+            footer: CONNECTION_LIST_NEXT_STEPS,
         });
     });
     // ── apimapper_connection_get ───────────────────────────────────────
     server.registerTool("apimapper_connection_get", {
         title: "Get Connection",
-        description: "Fetch full configuration of a single connection by ID." +
+        description: "Get the full configuration of one connection by ID (endpoints, auth/" +
+            "credential link, default params + headers, items_path, pipeline). Use to " +
+            "inspect or debug a single connection before editing it or wiring it into a flow. " +
+            "Keywords: get connection, connection detail, inspect connection, show config, by ID. " +
+            "When NOT to use: to enumerate all connections use apimapper_connection_list; to " +
+            "fetch sample rows use apimapper_connection_data; to probe reachability/auth use " +
+            "apimapper_connection_test; to change fields use apimapper_connection_update." +
             "\n\nExample:\n  apimapper_connection_get({ id: 'con_abc123' })",
         inputSchema: {
             id: z.string().describe('Connection ID (e.g., "conn_Mz33OVPF1z3ap8fbbQtpx"). Use apimapper_connection_list.'),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Connection", openWorld: true }),
     }, async ({ id }) => {
         // PHP wraps via fromControllerResponse($response, 'connection') →
         // `{success:true, connection:{…}}`. Unwrap defensively so a future
         // flatten on the PHP side doesn't break us. Audit: F-A1-01.
-        const r = await request(`/connections/${encodeURIComponent(id)}`);
+        // S-MED-1 (Wave-B 2026-06-03): sanitize the connection read. The
+        // Connection shape carries `headers`/`params` arrays that can hold an
+        // inline Authorization / X-API-Key value; {sanitize:true} runs the
+        // response through sanitizeSecrets (which now also scrubs {name,value}
+        // header pairs) so the SECURITY.md "every response is sanitized"
+        // guarantee holds structurally, not only by buildConnectionDetail's
+        // whitelist curation.
+        const r = await request(`/connections/${encodeURIComponent(id)}`, {}, { sanitize: true });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "connection get failed" });
         }
         const conn = unwrapEntity(r.data, "connection");
         if (!conn || Object.keys(conn).length === 0) {
-            return formatResult({ error: "connection not found", status: r.status, context: { id }, hint: hintFor("not_found") }, true);
+            return errorResult({
+                message: "connection not found",
+                code: r.status ? String(r.status) : "not_found",
+                suggestion: hintFor("not_found"),
+                details: { id },
+            });
         }
-        return formatResult(conn, false, { maxChars: 4000 });
+        // W3.1 — detailResult: grouped key-value detail for the Rich Card.
+        // IA-7: opaque IDs are copyable code entries. IA-10: a dedicated
+        // "Next steps" group carries the follow-up calls.
+        return buildConnectionDetail(id, conn);
     });
     // ── apimapper_connection_create ────────────────────────────────────
     server.registerTool("apimapper_connection_create", {
         title: "Create Connection",
-        description: "Create a new connection (custom — not from library)." +
+        description: "Create a custom connection. **Use ONLY when no library template matches your target API.** " +
+            "First call `apimapper_library_featured()` or `apimapper_library_list({ query: '<api-name>' })` — " +
+            "Google Sheets, Calendly, Notion, Airtable, GitHub, Pexels, Unsplash, OpenWeatherMap, REST Countries, " +
+            "Google Drive/Docs/Slides/Tasks all have ready-to-use templates with auto-configured auth and " +
+            "field-detection. Library activation via `apimapper_library_activate({ id })` is the canonical " +
+            "customer path; connection_create is the fallback for niche or unknown APIs. " +
+            "The server enforces this: a custom create on an API already covered by a curated template is " +
+            "blocked with a 409 naming the template to activate — pass `acknowledge_no_library: true` to " +
+            "intentionally override that block." +
             "\n\nExample:\n  apimapper_connection_create({ name: 'Pexels API', endpoint: 'https://api.pexels.com/v1/search', method: 'GET', auth_type: 'bearer', items_path: 'photos' })",
         inputSchema: {
             name: z.string().min(1).describe('Connection name (e.g., "My Blog API")'),
@@ -128,30 +279,117 @@ export function registerConnectionTools(server) {
             items_path: z.string().optional().describe('JSONPath to items array (snake_case wire key)'),
             cache_ttl: z.number().int().min(0).default(3600).describe("Cache TTL in seconds (snake_case wire key)"),
             description: z.string().optional().describe("Free-text description"),
+            // Phase 6 — audited override for the server-side library-first guard.
+            // The PHP guard blocks custom creates on APIs that already have a
+            // curated library template (returning a 409 whose message names the
+            // template via apimapper_library_activate). Setting this flag relays
+            // `acknowledge_no_library: true` into the POST body so the guard lets
+            // the create through. Flows into the body via `resolvedInput = {...input}`.
+            acknowledge_no_library: z.boolean().optional().describe("Set true ONLY when no library template fits and you intentionally need a custom connection. " +
+                "The server blocks custom creates on APIs that already have a curated library template; " +
+                "this flag is the audited override. Prefer apimapper_library_activate({ id }) when a template exists."),
         },
-        annotations: creating(),
+        annotations: creating({ title: "Create Connection", openWorld: true }),
     }, async (input) => {
+        // W3.6 — when the connection's auth_type needs a credential and none is
+        // given: exactly 1 stored credential → auto-pick; >1 → elicitChoice;
+        // elicitChoice null (unsupported client / declined) → structured
+        // candidate-list error. auth_type "none" never needs a credential.
+        let resolvedInput = { ...input };
+        if (input.auth_type !== "none" && !input.credential_id) {
+            const lr = await request("/credentials", {}, { sanitize: true });
+            if (!lr.success) {
+                return restErrorResult(lr, { name: input.name, auth_type: input.auth_type }, { message: "credential lookup failed" });
+            }
+            const creds = Array.isArray(lr.data?.credentials) ? lr.data.credentials : [];
+            if (creds.length === 0) {
+                return errorResult({
+                    message: `auth_type "${input.auth_type}" needs a credential, but none are stored.`,
+                    code: "credential_not_found",
+                    suggestion: "Create one with apimapper_credential_create, then retry with its credential_id.",
+                    details: { name: input.name, auth_type: input.auth_type },
+                });
+            }
+            if (creds.length === 1) {
+                resolvedInput = { ...input, credential_id: creds[0].id };
+            }
+            else {
+                const candidates = creds.map((c) => ({
+                    id: c.id,
+                    label: c.name,
+                }));
+                const picked = elicitation
+                    ? await elicitChoice(elicitation, `The "${input.name}" connection (auth_type: ${input.auth_type}) needs a ` +
+                        "credential. Pick which stored credential to use.", candidates.map((c) => c.id))
+                    : null;
+                if (picked === null) {
+                    return ambiguityFallbackError({
+                        code: "credential_ambiguous",
+                        paramName: "credential_id",
+                        what: "credentials",
+                        candidates,
+                        extraDetails: { name: input.name, auth_type: input.auth_type },
+                    });
+                }
+                resolvedInput = { ...input, credential_id: picked };
+            }
+        }
         // PHP fromControllerResponse(_, 'connection', 201) → {success, connection:{…}}.
         // Audit: F-A1-02.
         const r = await request("/connections", {
             method: "POST",
-            body: JSON.stringify(input),
+            body: JSON.stringify(resolvedInput),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { name: input.name, endpoint: input.endpoint },
-                hint: hintFor(r.errorCode),
-            }, true);
+            // M1 (MCP-relay audit) — wire-shape parity with the admin-ui. On the
+            // library-first guard block the PHP REST body carries a structured
+            // `{error, error_code:'library_template_available', library_suggestion:
+            // {matched_host, templates[], activate_call}}`. The admin-ui consumes
+            // that object; the MCP relay must too. We surface the structured
+            // `library_suggestion` + `error_code` in `details` (→ machine-readable
+            // _meta.ui.payload.details) IN ADDITION to keeping the actionable
+            // `message` string verbatim — the message embeds the activate call so
+            // a text-only agent still recovers. `errorBody` is the parsed non-2xx
+            // body threaded through the shared client (see client.ts request()).
+            const errorBody = r.errorBody;
+            const isLibraryBlock = errorBody !== undefined &&
+                errorBody.error_code === "library_template_available";
+            return restErrorResult(r, 
+            // Per-site nuance: on a library-first guard block (409 / Joomla
+            // com_ajax) the structured `error_code` + `library_suggestion` from
+            // the parsed body are surfaced in details IN ADDITION to the verbatim
+            // message string. Non-library failures keep the plain identity echo.
+            isLibraryBlock
+                ? {
+                    name: input.name,
+                    endpoint: input.endpoint,
+                    error_code: errorBody.error_code,
+                    library_suggestion: errorBody.library_suggestion,
+                }
+                : { name: input.name, endpoint: input.endpoint }, { message: "connection create failed" });
         }
         const conn = unwrapEntity(r.data, "connection");
+        // F-3.2 (Pass-1 consolidation) — mutating-tool payload-shape rationale.
+        //
+        // connection_create + connection_update stay on the flat
+        // `formatResult({ ... })` shape rather than migrating to the
+        // structured detailResult / actionResult builders. The mutating-tool
+        // payload here is intentionally minimal (the wire echo confirms the
+        // op + identity), and the detail builders are tuned for fully
+        // populated entities (badge/group/entry layouts) — wrapping a 3-field
+        // confirmation in a Rich Card would add noise without surfacing more
+        // information. This mirrors the connection_data passthrough rationale:
+        // the LLM benefits from the bare structured echo; UI hosts that want
+        // a richer view re-fetch via connection_get. IA-10 uniformity is
+        // restored via `next_steps[]` (array, single-element) below.
         return formatResult({
             created: true,
             id: conn?.id,
             name: conn?.name,
             source: conn?.source,
+            next_steps: [
+                "Use apimapper_connection_test to verify reachability, then apimapper_flow_create to wire it into a flow.",
+            ],
         }, false, { maxChars: 2000 });
     });
     // ── apimapper_connection_update ────────────────────────────────────
@@ -165,9 +403,16 @@ export function registerConnectionTools(server) {
                 .record(z.string(), z.unknown())
                 .describe('Fields to update — snake_case keys. ' +
                 'Examples: {"name":"Renamed"}, {"cache_ttl":7200}, {"endpoint":"/v2/posts"}, ' +
-                '{"credential_id":"cred_xxx"}'),
+                '{"credential_id":"cred_xxx"}. ' +
+                // DATA-LOW (Wave-B 2026-06-03): kept as an open record on purpose.
+                // The settable column set is large and may widen server-side; the
+                // PHP backend column-whitelists on write (Wave A), so any unknown
+                // key is dropped server-side rather than persisted. Enumerating a
+                // .strict() allow-list here risks rejecting a legit field the
+                // server accepts, so the schema stays permissive.
+                'Unknown keys are dropped by the server (column-whitelisted on write).'),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Connection", openWorld: true }),
     }, async ({ id, patch }) => {
         // PHP fromControllerResponse(_, 'connection') → {success, connection:{…}}.
         // Audit: F-A1-03.
@@ -176,10 +421,123 @@ export function registerConnectionTools(server) {
             body: JSON.stringify(patch),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "connection update failed" });
         }
         const conn = unwrapEntity(r.data, "connection");
-        return formatResult({ updated: true, id: conn?.id, name: conn?.name }, false, { maxChars: 2000 });
+        // F-3.2 (Pass-1 consolidation) — see connection_create for the
+        // mutating-tool payload-shape rationale. next_steps[] restored for
+        // IA-10 uniformity (single-element array, not flat `next:`).
+        return formatResult({
+            updated: true,
+            id: conn?.id,
+            name: conn?.name,
+            next_steps: [
+                "Re-run apimapper_connection_test if endpoint/auth changed; flows referencing this connection may need to be republished.",
+            ],
+        }, false, { maxChars: 2000 });
+    });
+    // ── apimapper_connection_recover ───────────────────────────────────
+    // Friction-6 fix (Task #46, 2026-05-29) — recover from a connection whose
+    // `params` field was persisted as a corrupt JSON-string holding UI metadata
+    // blobs (resource_picker, sheets_range, ...) instead of a proper key-value
+    // object. Pre-fix: connection_update rejected the patch because the existing
+    // shape failed downstream validation; the connection was un-editable.
+    //
+    // This tool issues a forgiving PUT that resets `params` to {} (and optionally
+    // sets a clean replacement via `params_replacement`), letting the customer
+    // / AI proceed with a fresh configuration. It also clears any extra cruft
+    // keys the AI agent identifies via `clear_fields`.
+    server.registerTool("apimapper_connection_recover", {
+        title: "Recover Stuck Connection",
+        description: "Recover a connection that is un-editable because its `params` field " +
+            "is corrupt (e.g. stored as a JSON-string with embedded UI metadata " +
+            "instead of an object). Resets `params` to an empty object — or to " +
+            "the value of `params_replacement` if supplied. Optionally clears " +
+            "additional fields named in `clear_fields`." +
+            "\n\nUse when: `apimapper_connection_data` returns 'Please select an " +
+            "endpoint' AND `apimapper_connection_update` rejects subsequent " +
+            "patches with a validation error about params shape." +
+            "\n\nExample:\n  apimapper_connection_recover({ id: 'con_abc123' })" +
+            "\n  apimapper_connection_recover({ id: 'con_abc123', params_replacement: { per_page: '20' }, endpoint: 'values' })",
+        inputSchema: {
+            id: z
+                .string()
+                .describe("Connection ID. Use apimapper_connection_list to find."),
+            params_replacement: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Clean replacement for params (key-value object). Default: {} (empty). " +
+                // DATA-LOW (Wave-B 2026-06-03): open record by design — the value
+                // becomes the connection's `params` column, which the PHP backend
+                // column-whitelists on write (Wave A). Free-form key-value pairs
+                // are the intended shape here, so no .strict() allow-list applies.
+                "Free-form key-value pairs; the server whitelists the persisted columns."),
+            endpoint: z
+                .string()
+                .optional()
+                .describe("If the connection has no endpoint configured, set it here in the " +
+                "same call (e.g., 'values' for Google Sheets, 'Search' for Pexels). " +
+                "Use apimapper_advanced({tool:'apimapper_connection_get'}) to see " +
+                "available endpoints[]."),
+            clear_fields: z
+                .array(z.string().min(1))
+                .max(20)
+                .optional()
+                .describe("Additional fields to clear (set to null). Example: ['template_fields']."),
+            confirm: z
+                .boolean()
+                .default(false)
+                .describe("Must be true to execute. On confirm:false, returns a preview of " +
+                "the planned reset. Ask user to confirm first."),
+        },
+        annotations: mutating({ title: "Recover Stuck Connection", openWorld: true }),
+    }, async ({ id, params_replacement, endpoint, clear_fields, confirm }) => {
+        const patch = {
+            params: params_replacement ?? {},
+        };
+        if (endpoint !== undefined)
+            patch.endpoint = endpoint;
+        if (Array.isArray(clear_fields)) {
+            for (const field of clear_fields) {
+                patch[field] = null;
+            }
+        }
+        if (!confirm) {
+            return formatResult({
+                preview: true,
+                notice: "RECOVER — Connection will be patched with the reset shown below. " +
+                    "This is a forgiving reset path; existing `params` corrupted shape " +
+                    "will be overwritten.",
+                target: { id },
+                patch_preview: patch,
+                instruction: "Ask user to confirm, then call again with confirm: true.",
+            });
+        }
+        const r = await request(`/connections/${encodeURIComponent(id)}`, {
+            method: "PUT",
+            body: JSON.stringify(patch),
+        });
+        if (!r.success) {
+            return restErrorResult(r, { id, patch_keys: Object.keys(patch) }, {
+                message: "connection recover failed",
+                // Per-site nuance: keep the original `hintFor(...) ?? <deep-corrupt
+                // fallback>` suggestion verbatim (hintFor always returns a string,
+                // so the `??` arm is a defensive no-op preserved for parity).
+                suggestion: hintFor(r.errorCode) ??
+                    "If recover still fails, the connection row may be deeper-corrupt — " +
+                        "delete it via apimapper_connection_delete and re-activate the library template.",
+            });
+        }
+        const conn = unwrapEntity(r.data, "connection");
+        return formatResult({
+            recovered: true,
+            id: conn?.id ?? id,
+            name: conn?.name,
+            applied_patch_keys: Object.keys(patch),
+            next_steps: [
+                "Verify with apimapper_connection_get; re-run apimapper_connection_test before re-publishing flows.",
+            ],
+        }, false, { maxChars: 2000 });
     });
     // ── apimapper_connection_delete ────────────────────────────────────
     server.registerTool("apimapper_connection_delete", {
@@ -194,7 +552,7 @@ export function registerConnectionTools(server) {
                 .default(false)
                 .describe("Must be true to execute. On confirm:false, returns a preview."),
         },
-        annotations: destructive(),
+        annotations: destructive({ title: "Delete Connection", openWorld: true }),
     }, async ({ id, confirm }) => {
         if (!confirm) {
             // PHP fromControllerResponse(_, 'connection') wraps as
@@ -218,7 +576,7 @@ export function registerConnectionTools(server) {
         }
         const r = await request(`/connections/${encodeURIComponent(id)}`, { method: "DELETE" });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "connection delete failed" });
         }
         return formatResult({ deleted: true, id }, false, { maxChars: 1500 });
     });
@@ -231,33 +589,30 @@ export function registerConnectionTools(server) {
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Test Connection", openWorld: true }),
     }, async ({ id }) => {
+        // PHP wraps probe fields one level deeper:
+        //   {success:true, data:{actionType, http_code, duration_ms, body_preview, …}, items_count}
+        // unwrapInnerSuccess sees outer success:true and lets it through, but
+        // probe fields still live under `data.data.*`. Audit: F-A1-05.
         const r = await request("/connections/test", { method: "POST", body: JSON.stringify({ connection_id: id }) }, { unwrapInnerSuccess: true });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                payloadFailed: r.payloadFailed,
-                context: { id },
-                hint: r.payloadFailed
+            return restErrorResult(r, { id, payloadFailed: r.payloadFailed }, {
+                message: "connection test failed",
+                // Per-site nuance: a 200 + success:false (payloadFailed) probe gets
+                // an upstream-status hint; everything else falls back to hintFor().
+                suggestion: r.payloadFailed
                     ? "Probe ran but reported failure — check the upstream API status, credentials, or connection endpoint."
                     : hintFor(r.errorCode),
-            }, true);
+            });
         }
         // Defensive unwrap: prefer `r.data.data` if present, fall back to `r.data` itself
         // so a future PHP flatten doesn't break this tool.
         const outer = (r.data && typeof r.data === "object" ? r.data : {});
         const probe = (outer.data && typeof outer.data === "object" ? outer.data : outer);
-        return formatResult({
-            ok: true,
-            id,
-            actionType: probe.actionType ?? "ok",
-            http_code: probe.http_code,
-            duration_ms: probe.duration_ms,
-            body_preview: probe.body_preview?.slice(0, 500),
-        }, false, { maxChars: 2500 });
+        // W3.1 — statsResult: the probe outcome is a small flat scalar set.
+        // IA-10: the follow-up guidance rides in the stats description.
+        return buildConnectionTestStats(id, probe);
     });
     // ── apimapper_connection_health_check ──────────────────────────────
     server.registerTool("apimapper_connection_health_check", {
@@ -271,20 +626,19 @@ export function registerConnectionTools(server) {
                 .default([])
                 .describe('Connection IDs to probe (empty = all). REST wire-key: connection_ids.'),
         },
-        annotations: readOnly(),
-    }, async ({ connection_ids }) => {
+        annotations: readOnly({ title: "Connection Health Check", openWorld: true }),
+    }, async ({ connection_ids }, extra) => {
+        // W3.5 — coarse progress side-channel. `null` when the caller sent no
+        // progressToken; `progress?.report(...)` then no-ops. The batch probe
+        // can take 10-30s, so a start/done signal keeps the caller informed.
+        const progress = extra ? createProgressReporter(extra) : null;
+        await progress?.report(0, 1, "Probing connections…");
         const r = await request("/connections/health-check", {
             method: "POST",
             body: JSON.stringify({ connection_ids }),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { count: connection_ids.length },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { count: connection_ids.length }, { message: "connection health check failed" });
         }
         const data = (r.data && typeof r.data === "object") ? r.data : {};
         // PHP returns map keyed by connection id, NOT under a 'results' key —
@@ -297,71 +651,165 @@ export function registerConnectionTools(server) {
             const o = x;
             return o.success === true || o.actionType === "ok";
         }).length;
-        return formatResult({
-            ok_count: okCount,
-            fail_count: results.length - okCount,
-            total: results.length,
-            results: data,
-        }, false, { maxChars: 6000 });
+        await progress?.report(1, 1, `Probed ${results.length} connection(s)`);
+        // W3.1 — statsResult: the batch outcome is a counts dashboard.
+        // IA-10: the description routes the AI to connection_test for the
+        // per-connection probe detail (the full result map is too large for
+        // a stat grid).
+        return buildHealthCheckStats(okCount, results.length - okCount, results.length);
     });
     // ── apimapper_connection_data ──────────────────────────────────────
+    // rc.10.1 C (2026-05-19) — exposes `limit` + `offset` to AI agents so
+    // they can constrain large API responses without injecting template
+    // hacks like `template_fields.per_page`. Trim happens IN-MEMORY on
+    // the TS side after the response is unwrapped — this is single-shot
+    // upstream, no multi-page fetch is triggered. Real cursor / page-loop
+    // pagination is a separate roadmap item (see plan Section E1).
     server.registerTool("apimapper_connection_data", {
         title: "Fetch Connection Sample Data",
         description: "Fetch sample data from a connection's configured endpoint. The PHP handler reads ALL " +
-            "query params as source-context for template substitution." +
-            "\n\nExample:\n  apimapper_connection_data({ id: 'con_abc123', params: { query: 'nature', per_page: 10 } })",
+            "query params as source-context for template substitution. Use `limit`/`offset` to trim " +
+            "the response items in-memory — this does NOT trigger multi-page fetch upstream (the " +
+            "request is single-shot). Use `fields` to project each item down to a whitelist of leaf " +
+            "keys, cutting response size on sparse queries." +
+            "\n\nExample:\n" +
+            "  apimapper_connection_data({ id: 'con_abc123', limit: 10 })  // first 10 items\n" +
+            "  apimapper_connection_data({ id: 'con_abc123', limit: 5, offset: 10 })  // skip 10, take 5\n" +
+            "  apimapper_connection_data({ id: 'con_abc123', fields: ['title', 'image.url'] })  // 2 leaf keys per item\n" +
+            "  apimapper_connection_data({ id: 'con_abc123', template_fields: { query: 'nature' } })",
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
-            endpoint: z.string().optional().describe('Override endpoint (e.g., "Scheduled Events")'),
+            endpoint: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Override endpoint (e.g., "Scheduled Events"). Empty-string and whitespace-only values are rejected at the schema boundary to prevent "?endpoint=" query garbage; omit the field entirely to use the connection default.'),
             template_fields: z
-                .record(z.string(), z.string())
+                .record(z.string(), z.union([z.string(), z.number().finite(), z.boolean()]))
+                .optional()
+                .describe('Template field values flattened into the query string. Accepts string/number/boolean values; non-string values are stringified via JS String() (number 25 → "25", true → "true", false → "false"). NaN/Infinity numbers are rejected by schema (defense-in-depth). Nested objects/arrays are rejected. Example: { spreadsheet_id: "abc", per_page: 25, active: true } → ?spreadsheet_id=abc&per_page=25&active=true'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
                 .optional()
-                .describe('Template field values flattened into query string (e.g., {"spreadsheet_id":"...","user_uri":"..."})'),
+                .describe("Trim the returned items array to at most N (1-500). Applied in-memory after the upstream fetch — does NOT request fewer items from the source API. Omit to return the full response."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Skip the first N items before applying `limit`. Applied in-memory. Useful for inspecting later items in a large response when combined with `limit`."),
+            // rc.13 W3.3 (2026-05-20) — optional per-item field whitelist.
+            // When the data payload is an array of objects each item is mapped
+            // through pickFields() so only the named leaf keys survive.
+            fields: z
+                .array(z.string().min(1))
+                .max(40)
+                .optional()
+                .describe("Optional whitelist of fields to keep per item (supports nested paths like 'image.url'). Default: all fields. Cuts response size on sparse queries — e.g. fields:['title','image.url'] keeps only those two leaf keys per record."),
         },
-        annotations: readOnly(),
-    }, async ({ id, endpoint, template_fields }) => {
+        annotations: readOnly({ title: "Get Connection Data", openWorld: true }),
+    }, async ({ id, endpoint, template_fields, limit, offset, fields }) => {
         const params = new URLSearchParams();
         if (endpoint)
             params.set("endpoint", endpoint);
         // Flatten template_fields directly as query params — PHP handler does
         // array_filter() across get_query_params() and uses each key as a
-        // template variable.
+        // template variable. Non-string primitives (number/boolean — F-10/W1.5)
+        // are explicitly stringified via String(): the schema admits
+        // string|number|boolean unions, so the handler must canonicalise
+        // numbers to their decimal repr ("25") and booleans to "true"/"false"
+        // before they hit URLSearchParams. URLSearchParams.set would coerce
+        // implicitly, but the explicit guard documents the contract and keeps
+        // TypeScript happy under the wider schema.
         if (template_fields) {
             for (const [k, v] of Object.entries(template_fields)) {
-                params.set(k, v);
+                params.set(k, typeof v === "string" ? v : String(v));
             }
         }
         const qs = params.toString();
-        const r = await request(`/connections/${encodeURIComponent(id)}/data${qs ? `?${qs}` : ""}`);
+        // S-MED-1 (Wave-B 2026-06-03): sanitize the data read. The {…,connection}
+        // envelope echoes the connection config (incl. `headers`/`params` arrays
+        // that can hold an inline Authorization / X-API-Key value); {sanitize:true}
+        // scrubs it — and {name,value} header pairs — before the payload crosses
+        // the MCP boundary. The data rows themselves are customer data and are not
+        // mutated by the secret-only sanitizer.
+        const r = await request(`/connections/${encodeURIComponent(id)}/data${qs ? `?${qs}` : ""}`, {}, { sanitize: true });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { id, endpoint, template_fields },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { id, endpoint, template_fields, limit, offset }, { message: "connection data fetch failed" });
         }
         // PHP success body: {data:[…items…], connection, body?, content_type?, status?}.
         // Operate on the inner `data` payload, not on the envelope. Surface
         // `body`/`content_type` for the non-JSON path. Audit: F-A1-06.
         const envelope = (r.data && typeof r.data === "object" ? r.data : {});
-        const inner = "data" in envelope ? envelope.data : envelope;
+        const innerRaw = "data" in envelope ? envelope.data : envelope;
         const body = typeof envelope.body === "string" ? envelope.body : undefined;
         const contentType = typeof envelope.content_type === "string" ? envelope.content_type : undefined;
-        const isArray = Array.isArray(inner);
-        const items = isArray
-            ? inner
-            : inner && typeof inner === "object" && Array.isArray(inner.items)
-                ? inner.items
-                : null;
+        // Silent-zero UX gap (2026-06, PR #732 follow-through) — on a 0-row
+        // read the PHP /connections/{id}/data handler attaches a structured
+        // `diagnostic` ({reason, message}) explaining WHY nothing showed
+        // (unresolved endpoint placeholders, items_path mismatch, or a genuine
+        // empty result). Forward it additively into the tool output so the AI
+        // agent sees the explanation instead of a silent {item_count:0,
+        // payload:[]}. Present only when the upstream supplied it (i.e. on
+        // empty results), so the non-empty envelope shape is unchanged. We
+        // keep the value verbatim — the PHP EmptyResultDiagnostic::classify
+        // owns the {reason, message} contract; the TS layer is a pure
+        // passthrough and must not reshape it.
+        const diagnostic = envelope.diagnostic !== null &&
+            typeof envelope.diagnostic === "object" &&
+            !Array.isArray(envelope.diagnostic)
+            ? envelope.diagnostic
+            : undefined;
+        // rc.10.1 C + rc.13 W1.2 (F-01+F-38) — apply in-memory trim via
+        // extracted pure function. See the `applyTrim` JSDoc in
+        // connections-trim.ts for the shape-detection contract and
+        // shallow-clone guarantees.
+        const trim = applyTrim(innerRaw, limit, offset);
+        // rc.13 W3.3 — optional field-projection. Runs AFTER trim: the
+        // trimmed slice is the smallest correct surface to project, and
+        // projection composes cleanly on top of it (project-of-trimmed ≡
+        // narrowing a smaller list). Projection is applied ONLY when the
+        // (trimmed) payload is an array of plain objects — each item is
+        // mapped through pickFields(), which flattens nested paths to leaf
+        // keys and silently drops missing fields. For every other shape
+        // (single object, scalar, nested-items envelope, array of
+        // primitives) projection is skipped and the payload passes through
+        // unchanged — there is no per-record surface to whitelist there, so
+        // narrowing would be lossy or meaningless. `projected_fields` is
+        // still echoed back in the envelope whenever `fields` was supplied,
+        // so the AI client always knows projection was requested even when
+        // the shape made it a no-op.
+        let projectedPayload = trim.payload;
+        if (fields && Array.isArray(trim.payload)) {
+            projectedPayload = trim.payload.map((item) => item !== null && typeof item === "object" && !Array.isArray(item)
+                ? pickFields(item, fields)
+                : item);
+        }
         return formatResult({
             ok: true,
-            shape: isArray ? "array" : typeof inner,
-            item_count: items ? items.length : undefined,
+            // F-38 — surface a stable, narrow shape enum instead of typeof.
+            // "object" is preserved for the legacy non-iterable case so
+            // existing wire-shape pins keep working.
+            shape: trim.detectedShape === "other" ? typeof trim.payload : trim.detectedShape,
+            item_count: trim.itemCount,
+            ...(trim.trimmed && trim.totalBeforeTrim !== undefined
+                ? { total_before_trim: trim.totalBeforeTrim, trimmed: true }
+                : {}),
+            // W3.3 — echo the requested whitelist so the AI knows the
+            // per-item shape was (or was meant to be) reduced.
+            ...(fields ? { projected_fields: fields } : {}),
+            // Silent-zero UX gap (2026-06) — forward the upstream
+            // EmptyResultDiagnostic so a 0-row read explains WHY. Spread
+            // additively: absent on the happy path, so existing non-empty
+            // wire-shape pins are unchanged.
+            ...(diagnostic ? { diagnostic } : {}),
             body,
             content_type: contentType,
-            payload: inner,
+            payload: projectedPayload,
         }, false, { maxChars: 6000 });
     });
     // ── apimapper_connection_resources ─────────────────────────────────
@@ -375,9 +823,15 @@ export function registerConnectionTools(server) {
             field: z
                 .string()
                 .describe('Resource-picker field name (e.g., "spreadsheet_id", "drive_file_id"). REST wire-key: field.'),
-            query: z.string().optional().describe("Free-text search query"),
+            // rc.10 A4 (2026-05-19): min(3) blocks the single-char "p", "j", "u"
+            // probing pattern observed in Maria-walkthrough logs.
+            // rc.13 W1.17 (F-29): Master-Doc-Drift — Master requested min(2), kept
+            // min(3) (stricter is OK, less regression-risk). Pin-test in
+            // connections.test.ts "F-29 connection_resources query min length pin"
+            // guards against loosening.
+            query: z.string().min(3).optional().describe("Free-text search query. Must be 3+ characters — single-char and 2-char probes are blocked because the resource lists are small enough to scan without typeahead."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Connection Resources", openWorld: true }),
     }, async ({ id, field, query }) => {
         const params = new URLSearchParams();
         params.set("field", field);
@@ -385,42 +839,47 @@ export function registerConnectionTools(server) {
             params.set("query", query);
         const r = await request(`/connections/${encodeURIComponent(id)}/resources?${params.toString()}`);
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { id, field, query },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { id, field, query }, { message: "connection resources failed" });
         }
-        const data = r.data;
-        const resources = Array.isArray(data)
-            ? data
-            : data && typeof data === "object" && Array.isArray(data.resources)
-                ? data.resources
-                : data && typeof data === "object" && Array.isArray(data.items)
-                    ? data.items
-                    : [];
-        return formatResult({
-            field,
-            query: query || null,
-            resource_count: resources.length,
-            resources: resources.slice(0, 100),
-            note: resources.length > 100 ? `Showing first 100 of ${resources.length} resources.` : undefined,
-        }, false, { maxChars: 6000 });
+        // A1-P3-1: pure helper handles the three wire-shapes (bare array,
+        // `{ resources }`, `{ items }`) + fallback to `[]` for unknown
+        // shapes. Pinned per-branch in connections.test.ts.
+        const resources = extractResourceList(r.data);
+        // W3.1 — tableResult: resources are a flat row list. IA-7: opaque id
+        // stays llmOnly. IA-10: the footer carries the next-step guidance and
+        // the truncation note when more than 100 resources are returned.
+        const truncated = resources.length > 100;
+        const footerLines = [
+            `Picker field: ${field}${query ? ` · filter: "${query}"` : ""}.`,
+        ];
+        if (truncated) {
+            footerLines.push(`Showing first 100 of ${resources.length} resources — narrow with the query filter.`);
+        }
+        footerLines.push("Next: pass a chosen resource ID into apimapper_connection_update " +
+            "({ id, patch }) or the connection's pipeline default_params.");
+        return tableResult(resources.slice(0, 100), {
+            columns: RESOURCE_TABLE_COLUMNS,
+            map: mapResourceRow,
+            header: (n) => `${n} resources on ${id}`,
+            footer: footerLines.join("\n"),
+        });
     });
     // ── apimapper_connection_pipeline_update ───────────────────────────
     server.registerTool("apimapper_connection_pipeline_update", {
         title: "Update Connection Pipeline",
-        description: "Update the connection's pipeline (endpoints, default_params, headers, items_path, items_shape)." +
-            "\n\nExample:\n  apimapper_connection_pipeline_update({ id: 'con_abc123', items_path: 'photos', items_shape: 'auto', default_params: { per_page: '20' } })",
+        description: "Update the connection's pipeline (endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type)." +
+            "\n\nitems_shape values: 'flat' (default, list of objects), 'auto' (best-effort detection), 'headers_rows' (pivot 2D array [[h1,h2],[v1,v2],...] into named-object rows — use this for Google-Sheets-style responses), 'object_keys' (turn a keyed object into a list)." +
+            "\n\nExample:\n  apimapper_connection_pipeline_update({ id: 'con_abc123', pipeline: { items_path: 'photos', items_shape: 'auto', default_params: { per_page: '20' } } })" +
+            "\n\nGoogle-Sheets 2D array example:\n  apimapper_connection_pipeline_update({ id: 'con_sheet', pipeline: { items_shape: 'headers_rows' } })",
         inputSchema: {
             id: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
             pipeline: z
                 .record(z.string(), z.unknown())
-                .describe('Pipeline JSON (e.g., {"endpoints":[...], "items_path":"data", "items_shape":"flat"})'),
+                .describe('Pipeline JSON. Accepts connection-column keys: endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type. ' +
+                'items_shape options: "flat" | "auto" | "headers_rows" | "object_keys". ' +
+                'Example: {"items_path":"data","items_shape":"headers_rows"}.'),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Connection Pipeline", openWorld: true }),
     }, async ({ id, pipeline }) => {
         // PHP ConnectionPipelineHandler uses fromControllerResponse(_, 'connection')
         // → {success, connection:{…}}. Unwrap defensively. Audit: F-A1-07.
@@ -429,7 +888,7 @@ export function registerConnectionTools(server) {
             body: JSON.stringify(pipeline),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "connection pipeline update failed" });
         }
         const conn = unwrapEntity(r.data, "connection");
         return formatResult({ updated: true, id: conn?.id, name: conn?.name }, false, { maxChars: 2000 });