@zackbart/connecta 0.15.0 → 0.16.0

package/dist/providers/cloudflare.js

@@ -16,6 +16,7 @@
  * required-key list, and a declared output shape.
  */
 import { api } from "../connectors/api.js";
+import { guardedFetch, } from "../connectors/guarded-fetch.js";
 import { ConnectorCallError } from "../errors.js";
 /** Cloudflare's v4 REST base. Override only for a proxy or a test double. */
 export const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4";
@@ -91,11 +92,52 @@ function admissionPolicy(maxConcurrency) {
         ],
     };
 }
-const DEFAULT_CREDENTIAL = {
+const API_TOKEN_CREDENTIAL = {
     label: "Cloudflare API token",
     description: "A scoped API token (My Profile → API Tokens → Create Token), not a Global API Key. Grant only the permissions the deployment needs: zone-scoped \"Zone Read\", \"Zone Settings Write\", \"DNS Write\", \"Cache Purge\", and the phase-specific Rules product Read permissions as needed; account-scoped \"Workers Scripts Read/Write\", \"Workers KV Storage Read/Write\", \"Workers R2 Storage Read/Write\", or \"Cloudflare Pages Read/Write\" for the platform tools.",
     placeholder: "Paste API token",
 };
+const GLOBAL_API_KEY_CREDENTIAL = {
+    label: "Cloudflare Global API Key",
+    description: "Legacy user-scoped authentication. The key has the same access as its Cloudflare user across every account and zone that user can reach. Prefer a scoped API token when possible.",
+    fields: [
+        {
+            name: "email",
+            label: "Account email",
+            description: "The verified email address for the Cloudflare user that owns the Global API Key.",
+            placeholder: "you@example.com",
+            inputType: "email",
+        },
+        {
+            name: "apiKey",
+            label: "Global API Key",
+            description: "The legacy Global API Key from My Profile → API Tokens.",
+            placeholder: "Paste Global API Key",
+            inputType: "password",
+        },
+    ],
+};
+function credentialConfig(authentication, override) {
+    if (authentication === "apiToken") {
+        const credential = override ?? API_TOKEN_CREDENTIAL;
+        if (credential.fields?.length) {
+            throw new Error("cloudflare() API token authentication requires a single-value credential.");
+        }
+        return credential;
+    }
+    const credential = override
+        ? {
+            ...GLOBAL_API_KEY_CREDENTIAL,
+            ...override,
+            fields: override.fields ?? GLOBAL_API_KEY_CREDENTIAL.fields,
+        }
+        : GLOBAL_API_KEY_CREDENTIAL;
+    const fields = credential.fields?.map((field) => field.name).sort();
+    if (fields?.join(",") !== "apiKey,email") {
+        throw new Error('cloudflare() Global API Key authentication requires credential fields named "email" and "apiKey".');
+    }
+    return credential;
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -188,7 +230,7 @@ function failureFor(status, headers, errors) {
     }
     const authCoded = [...codes].some((code) => AUTH_ERROR_CODES.has(code));
     if (status === 401 || status === 403 || authCoded) {
-        return new ConnectorCallError("auth_required", `Cloudflare rejected the API token (HTTP ${status}). ${detail} Check that the token is valid and carries the permission this call needs.`);
+        return new ConnectorCallError("auth_required", `Cloudflare rejected the configured credential (HTTP ${status}). ${detail} Check that it is valid and has permission to access this resource.`);
     }
     if (status === 400 || status === 409 || status === 422) {
         return new ConnectorCallError("invalid_args", `Cloudflare rejected the request (HTTP ${status}). ${detail}`);
@@ -201,72 +243,93 @@ function failureFor(status, headers, errors) {
     }
     return new ConnectorCallError("connector_call_failed", `Cloudflare request failed (HTTP ${status}). ${detail}`);
 }
-async function readToken(ctx) {
+// --- The request path --------------------------------------------------------
+/**
+ * The largest response this connection will read.
+ *
+ * Generous rather than tight, because `cloudflare_api_get` legitimately
+ * downloads Worker scripts and R2 objects. It is a ceiling on absurdity, not a
+ * quota: anything approaching it is already far past whatever `maxResultBytes`
+ * the deployment set, so the caller was never going to see it whole.
+ */
+const CLOUDFLARE_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const AUTHENTICATION_CONTEXT = Symbol("cloudflareAuthentication");
+function withAuthentication(ctx, authentication) {
+    return { ...ctx, [AUTHENTICATION_CONTEXT]: authentication };
+}
+async function readAuthenticationHeaders(ctx) {
+    if (ctx[AUTHENTICATION_CONTEXT] === "globalApiKey") {
+        const values = await ctx.credential?.getAll();
+        const email = values?.["email"];
+        const apiKey = values?.["apiKey"];
+        if (!email || !apiKey) {
+            throw new ConnectorCallError("auth_required", "No Cloudflare Global API Key and account email are configured for this connector. An operator must add both before any call can run.");
+        }
+        return { "X-Auth-Email": email, "X-Auth-Key": apiKey };
+    }
     const token = await ctx.credential?.get();
     if (!token) {
         throw new ConnectorCallError("auth_required", "No Cloudflare API token is configured for this connector. An operator must add one before any call can run.");
     }
-    return token;
+    return { Authorization: `Bearer ${token}` };
 }
-function buildUrl(base, spec) {
-    const url = new URL(`${base.replace(/\/+$/, "")}${spec.path}`);
-    for (const [key, value] of Object.entries(spec.query ?? {})) {
-        if (value === undefined)
-            continue;
-        url.searchParams.set(key, String(value));
-    }
-    return url.toString();
-}
-async function fetchCloudflare(base, spec, ctx) {
-    const token = await readToken(ctx);
-    if (spec.body !== undefined && spec.rawBody !== undefined) {
-        throw new Error("A Cloudflare request cannot have both JSON and raw bodies.");
-    }
-    let response;
-    try {
-        response = await fetch(buildUrl(base, spec), {
-            method: spec.method,
-            headers: {
-                Authorization: `Bearer ${token}`,
-                Accept: "application/json",
-                ...(spec.body !== undefined
-                    ? { "Content-Type": "application/json" }
-                    : {}),
-                ...Object.fromEntries(Object.entries(spec.headers ?? {}).filter((entry) => entry[1] !== undefined)),
-            },
-            ...(spec.body !== undefined
-                ? { body: JSON.stringify(spec.body) }
-                : spec.rawBody !== undefined
-                    ? { body: spec.rawBody }
-                    : {}),
-            ...(ctx.signal ? { signal: ctx.signal } : {}),
-        });
-    }
-    catch (cause) {
-        throw new ConnectorCallError("unavailable", `Could not reach the Cloudflare API: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-    }
-    return response;
+/**
+ * The one transport every Cloudflare tool goes through.
+ *
+ * URL confinement, `ctx.signal`, redirect refusal, bounded reads, and the
+ * "could not reach the provider" normalization all live in the shared helper.
+ * What stays here is what only Cloudflare knows: which headers prove identity,
+ * and what a status code means once it arrives.
+ */
+function cloudflareTransport(baseUrl) {
+    return guardedFetch({
+        provider: "Cloudflare",
+        baseUrl,
+        headers: { Accept: "application/json" },
+        maxResponseBytes: CLOUDFLARE_MAX_RESPONSE_BYTES,
+        authenticate: (ctx) => readAuthenticationHeaders(ctx),
+    });
 }
-async function callCloudflare(base, spec, ctx) {
-    const response = await fetchCloudflare(base, spec, ctx);
-    let envelope;
-    try {
-        envelope = (await response.json());
-    }
-    catch (cause) {
-        // A gateway error page, not JSON: the status is the only real signal left.
-        throw response.ok
-            ? new ConnectorCallError("unavailable", "Cloudflare returned a non-JSON body for a successful status.", { cause })
-            : failureFor(response.status, response.headers, []);
-    }
-    const errors = Array.isArray(envelope.errors) ? envelope.errors : [];
-    if (!response.ok || envelope.success === false) {
-        throw failureFor(response.status, response.headers, errors);
-    }
-    return {
-        result: envelope.result,
-        resultInfo: envelope.result_info,
-    };
+async function callCloudflare(send, spec, ctx) {
+    return await send(spec, ctx, async (response) => {
+        let envelope;
+        let parseFailure;
+        try {
+            envelope = (await response.json());
+        }
+        catch (cause) {
+            // A transport failure is not a parse failure. The connector's byte
+            // ceiling fires from inside this read and is deliberately non-retryable;
+            // routing it through the branch below would relabel it as a retryable
+            // `unavailable` and tell an agent to retry a response that will exceed
+            // the ceiling every time.
+            if (cause instanceof ConnectorCallError)
+                throw cause;
+            parseFailure = cause;
+        }
+        if (envelope === undefined) {
+            // A gateway error page or an empty body, not an envelope: the status is
+            // the only real signal left.
+            throw response.ok
+                ? new ConnectorCallError("unavailable", "Cloudflare returned a non-JSON body for a successful status.", parseFailure !== undefined ? { cause: parseFailure } : {})
+                : failureFor(response.status, response.headers, []);
+        }
+        const errors = Array.isArray(envelope.errors) ? envelope.errors : [];
+        if (!response.ok || envelope.success === false) {
+            throw failureFor(response.status, response.headers, errors);
+        }
+        const isV4Envelope = "success" in envelope ||
+            "result" in envelope ||
+            "result_info" in envelope ||
+            "messages" in envelope;
+        return {
+            // `/graphql` and a small number of product APIs return ordinary JSON
+            // instead of the standard v4 envelope. Preserve that document whole so
+            // the raw tools cover them too.
+            result: isV4Envelope ? envelope.result : envelope,
+            resultInfo: isV4Envelope ? envelope.result_info : undefined,
+        };
+    });
 }
 function base64FromBytes(bytes) {
     let binary = "";
@@ -275,33 +338,34 @@ function base64FromBytes(bytes) {
     }
     return btoa(binary);
 }
-async function callCloudflareContent(base, spec, ctx, responseType) {
-    const response = await fetchCloudflare(base, spec, ctx);
-    if (!response.ok) {
-        let errors = [];
-        try {
-            const envelope = (await response.clone().json());
-            if (Array.isArray(envelope.errors))
-                errors = envelope.errors;
+async function callCloudflareContent(send, spec, ctx, responseType) {
+    return await send(spec, ctx, async (response) => {
+        if (!response.ok) {
+            let errors = [];
+            try {
+                const envelope = (await response.json());
+                if (envelope && Array.isArray(envelope.errors))
+                    errors = envelope.errors;
+            }
+            catch {
+                // A raw or gateway error body has no structured detail to preserve,
+                // and one past the byte ceiling has none worth reporting over the
+                // status that already failed this call. Either way the throw below
+                // classifies the status, so nothing is swallowed into a success.
+            }
+            throw failureFor(response.status, response.headers, errors);
         }
-        catch {
-            // A raw or gateway error body has no structured detail to preserve.
+        const common = {
+            contentType: response.headers.get("content-type") ?? "application/octet-stream",
+            ...(response.headers.get("etag")
+                ? { etag: response.headers.get("etag") }
+                : {}),
+        };
+        if (responseType === "text") {
+            return { ...common, text: await response.text() };
         }
-        throw failureFor(response.status, response.headers, errors);
-    }
-    const common = {
-        contentType: response.headers.get("content-type") ?? "application/octet-stream",
-        ...(response.headers.get("etag")
-            ? { etag: response.headers.get("etag") }
-            : {}),
-    };
-    if (responseType === "text") {
-        return { ...common, text: await response.text() };
-    }
-    return {
-        ...common,
-        base64: base64FromBytes(new Uint8Array(await response.arrayBuffer())),
-    };
+        return { ...common, base64: base64FromBytes(await response.bytes()) };
+    });
 }
 /**
  * Cloudflare's `result_info` reshaped into the one question an agent actually
@@ -570,8 +634,8 @@ const RAW_INPUT_PROPERTY = {
  * an out-of-range value with a 400, so each caller passes its own. Encoding
  * them in the schema turns a wasted round trip into a local repair — but only
  * where the bound is really Cloudflare's. `bounds` records who chose the
- * range, because `strictValidation` refuses an out-of-range `perPage` locally
- * and an agent deserves to know whether the wall it hit is the API's or ours:
+ * range, because `api()` refuses an out-of-range `perPage` locally and an
+ * agent deserves to know whether the wall it hit is the API's or ours:
  *
  * - `"cloudflare"` — the schema's own documented minimum and maximum.
  * - `"clamped"` — Cloudflare accepts more; this connection caps it lower.
@@ -602,6 +666,24 @@ function pagingInputProperties(minPerPage, maxPerPage, options = {}) {
         },
     };
 }
+/**
+ * The second pagination convention, and the schemas say so.
+ *
+ * Rulesets, KV keys, and both R2 listings page by cursor rather than by page
+ * number, because that is how Cloudflare built them. The guide names the four,
+ * but an agent reading one tool's schema should not have to fetch the guide to
+ * learn that the `page` object it expected is not coming: absence of
+ * `nextCursor` is the loop condition here, and it is stated on both ends
+ * ([#342](https://github.com/zackbart/connecta/issues/342)).
+ */
+const CURSOR_INPUT_PROPERTY = {
+    type: "string",
+    description: "Opaque cursor from a previous call's nextCursor. This endpoint pages by cursor, not page number.",
+};
+const NEXT_CURSOR_OUTPUT_PROPERTY = {
+    type: "string",
+    description: "Pass back as `cursor` to continue. Absent when the listing is complete — this is the only signal; there is no page object.",
+};
 function listOutputSchema(key, item) {
     return {
         type: "object",
@@ -787,6 +869,8 @@ function headersFromArgs(value) {
     const headers = {};
     const forbidden = new Set([
         "authorization",
+        "x-auth-email",
+        "x-auth-key",
         "cookie",
         "host",
         "content-length",
@@ -865,7 +949,7 @@ const OPEN_OBJECT_OUTPUT_SCHEMA = {
 };
 const QUERY_INPUT_PROPERTY = {
     type: "array",
-    description: "Optional query parameters as name/value pairs. Each parameter name may appear once.",
+    description: "Query parameters as name/value pairs; each name may appear once.",
     items: {
         type: "object",
         properties: {
@@ -876,9 +960,14 @@ const QUERY_INPUT_PROPERTY = {
         additionalProperties: false,
     },
 };
+// Shared by all three escape hatches, and the compact renderer inlines it
+// three times over. The refused-header list is the connector's boundary rather
+// than a fact the caller composes with, so it lives in the usage guide; keeping
+// it here pushed cloudflare_api_upload's compact input past the 1,024-byte
+// budget ([#342](https://github.com/zackbart/connecta/issues/342)).
 const HEADERS_INPUT_PROPERTY = {
     type: "array",
-    description: "Optional provider headers as name/value pairs, for example cf-r2-jurisdiction, Range, If-None-Match, or Cloudflare product metadata. Authorization, Cookie, Host, Content-Length, Content-Type, and Transfer-Encoding are connector-owned and refused.",
+    description: "Endpoint headers as name/value pairs, e.g. cf-r2-jurisdiction or Range. Connector-owned headers are refused.",
     items: {
         type: "object",
         properties: {
@@ -924,53 +1013,82 @@ const R2_OBJECT_SCHEMA = {
     },
     required: ["key"],
 };
-function buildTools(scope) {
-    const { base } = scope;
+function buildTools(scope, authentication) {
+    const { send } = scope;
     const zoneArg = (args) => requireScope(args["zoneId"], scope.zoneId, "zoneId");
     const accountArg = (args) => requireScope(args["accountId"], scope.accountId, "accountId");
     const readOnly = { readOnlyHint: true, destructiveHint: false };
-    return [
-        {
-            name: "verify_api_token",
-            description: "Verify the configured Cloudflare API token and report its status. Use this first when any other tool fails with an authentication error, to separate a bad token from a missing permission.",
-            annotations: readOnly,
-            inputSchema: {
-                type: "object",
-                properties: {},
-                required: [],
-                additionalProperties: false,
-            },
-            outputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string" },
-                    status: {
-                        type: "string",
-                        description: "\"active\" for a usable token.",
+    const tools = [
+        authentication === "apiToken"
+            ? {
+                name: "verify_api_token",
+                description: "Verify the configured Cloudflare API token and report its status. Use this first when any other tool fails with an authentication error, to separate a bad token from a missing permission.",
+                annotations: readOnly,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                    additionalProperties: false,
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        status: {
+                            type: "string",
+                            description: "\"active\" for a usable token.",
+                        },
+                        notBefore: { type: "string" },
+                        expiresOn: { type: "string" },
+                    },
+                    required: ["status"],
+                },
+                handler: async (_args, ctx) => {
+                    const { result } = await callCloudflare(send, { method: "GET", path: "/user/tokens/verify" }, ctx);
+                    const token = asRecord(result);
+                    return {
+                        id: token["id"],
+                        status: token["status"],
+                        ...(token["not_before"] !== undefined
+                            ? { notBefore: token["not_before"] }
+                            : {}),
+                        ...(token["expires_on"] !== undefined
+                            ? { expiresOn: token["expires_on"] }
+                            : {}),
+                    };
+                },
+            }
+            : {
+                name: "verify_global_api_key",
+                description: "Verify the configured Cloudflare Global API Key and account email by retrieving the authenticated user. Use this first when another tool fails with an authentication error.",
+                annotations: readOnly,
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                    additionalProperties: false,
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        email: { type: "string" },
+                        status: {
+                            type: "string",
+                            description: "\"active\" when Cloudflare accepts the email and key.",
+                        },
                     },
-                    notBefore: { type: "string" },
-                    expiresOn: { type: "string" },
+                    required: ["email", "status"],
+                },
+                handler: async (_args, ctx) => {
+                    const { result } = await callCloudflare(send, { method: "GET", path: "/user" }, ctx);
+                    const user = asRecord(result);
+                    return { id: user["id"], email: user["email"], status: "active" };
                 },
-                required: ["status"],
-            },
-            handler: async (_args, ctx) => {
-                const { result } = await callCloudflare(base, { method: "GET", path: "/user/tokens/verify" }, ctx);
-                const token = asRecord(result);
-                return {
-                    id: token["id"],
-                    status: token["status"],
-                    ...(token["not_before"] !== undefined
-                        ? { notBefore: token["not_before"] }
-                        : {}),
-                    ...(token["expires_on"] !== undefined
-                        ? { expiresOn: token["expires_on"] }
-                        : {}),
-                };
             },
-        },
         {
             name: "cloudflare_api_get",
-            description: "Call any GET endpoint under Cloudflare's v4 API with this connector's token. Use a named tool when one exists; use this read-only escape hatch for Images, Stream, Email Routing, D1, Queues, Access, Tunnels, Analytics, and newer product endpoints the curated surface does not yet name.",
+            description: "Call any GET endpoint under Cloudflare's v4 API with this connector's credential. Prefer a named tool when one exists; this read-only hatch covers the products the named surface does not reach, such as Images, Stream, D1, and Queues.",
             annotations: readOnly,
             inputSchema: {
                 type: "object",
@@ -1019,9 +1137,9 @@ function buildTools(scope) {
                     ...(headers !== undefined ? { headers } : {}),
                 };
                 if (responseType === "text" || responseType === "base64") {
-                    return await callCloudflareContent(base, spec, ctx, responseType);
+                    return await callCloudflareContent(send, spec, ctx, responseType);
                 }
-                const { result, resultInfo } = await callCloudflare(base, spec, ctx);
+                const { result, resultInfo } = await callCloudflare(send, spec, ctx);
                 return {
                     result,
                     ...(resultInfo !== undefined ? { resultInfo } : {}),
@@ -1030,7 +1148,7 @@ function buildTools(scope) {
         },
         {
             name: "cloudflare_api_mutate",
-            description: "Call any JSON POST, PUT, PATCH, or DELETE endpoint under Cloudflare's v4 API with this connector's token. This is the approval-gated escape hatch for managing Cloudflare products without waiting for a named tool. It does not support multipart or binary uploads.",
+            description: "Call any JSON POST, PUT, PATCH, or DELETE endpoint under Cloudflare's v4 API with this connector's credential. The approval-gated write hatch for products the named surface does not reach. No multipart or binary uploads.",
             annotations: { readOnlyHint: false, destructiveHint: true },
             inputSchema: {
                 type: "object",
@@ -1072,7 +1190,7 @@ function buildTools(scope) {
                 const method = String(args["method"]);
                 const query = queryFromArgs(args["query"]);
                 const headers = headersFromArgs(args["headers"]);
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method,
                     path: cloudflareApiPath(args["path"]),
                     ...(query !== undefined ? { query } : {}),
@@ -1095,31 +1213,31 @@ function buildTools(scope) {
                     method: {
                         type: "string",
                         enum: ["POST", "PUT"],
-                        description: "HTTP upload method required by the Cloudflare endpoint.",
+                        description: "Upload method the Cloudflare endpoint requires.",
                     },
                     path: {
                         type: "string",
                         minLength: 1,
-                        description: "Relative path below /client/v4, beginning with '/'. Do not include a query string.",
+                        description: "Path below /client/v4, beginning with '/'. No query string.",
                     },
                     query: QUERY_INPUT_PROPERTY,
                     headers: HEADERS_INPUT_PROPERTY,
                     contentType: {
                         type: "string",
                         minLength: 1,
-                        description: "Content-Type for a raw text/base64 body. Omit for multipart because fetch supplies the boundary.",
+                        description: "Content-Type for a raw text or base64 body. Omit for multipart.",
                     },
                     textBody: {
                         type: "string",
-                        description: "Raw UTF-8 request body. Mutually exclusive with base64Body and multipart fields/files.",
+                        description: "Raw UTF-8 body. Exclusive with base64Body and fields/files.",
                     },
                     base64Body: {
                         type: "string",
-                        description: "Base64-encoded request bytes. Mutually exclusive with textBody and multipart fields/files.",
+                        description: "Base64-encoded body bytes. Exclusive with textBody and fields/files.",
                     },
                     fields: {
                         type: "array",
-                        description: "String fields for a multipart/form-data request.",
+                        description: "String fields of a multipart/form-data request.",
                         items: {
                             type: "object",
                             properties: {
@@ -1134,7 +1252,7 @@ function buildTools(scope) {
                     },
                     files: {
                         type: "array",
-                        description: "File parts for multipart/form-data. Each file needs exactly one of text or base64.",
+                        description: "Multipart file parts. Each needs exactly one of text or base64.",
                         items: {
                             type: "object",
                             properties: {
@@ -1165,7 +1283,7 @@ function buildTools(scope) {
                 const query = queryFromArgs(args["query"]);
                 const headers = headersFromArgs(args["headers"]);
                 const upload = uploadBody(args);
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: String(args["method"]),
                     path: cloudflareApiPath(args["path"]),
                     ...(query !== undefined ? { query } : {}),
@@ -1196,7 +1314,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("accounts", ACCOUNT_SCHEMA),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: "/accounts",
                     query: {
@@ -1241,7 +1359,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("zones", ZONE_SCHEMA),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: "/zones",
                     query: {
@@ -1279,7 +1397,7 @@ function buildTools(scope) {
             },
             outputSchema: ZONE_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, { method: "GET", path: `/zones/${encodeURIComponent(zoneArg(args))}` }, ctx);
+                const { result } = await callCloudflare(send, { method: "GET", path: `/zones/${encodeURIComponent(zoneArg(args))}` }, ctx);
                 return args["raw"] === true ? result : projectZone(result);
             },
         },
@@ -1297,7 +1415,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("settings", OPEN_OBJECT_OUTPUT_SCHEMA),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodePathSegment(zoneArg(args))}/settings`,
                 }, ctx);
@@ -1323,7 +1441,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodePathSegment(zoneArg(args))}/settings/${encodePathSegment(requireString(args, "settingId"))}`,
                 }, ctx);
@@ -1354,7 +1472,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "PATCH",
                     path: `/zones/${encodePathSegment(zoneArg(args))}/settings/${encodePathSegment(requireString(args, "settingId"))}`,
                     body: { value: args["value"] },
@@ -1376,10 +1494,7 @@ function buildTools(scope) {
                         maximum: 50,
                         description: "Rulesets per request, 1 to 50.",
                     },
-                    cursor: {
-                        type: "string",
-                        description: "Opaque cursor returned as nextCursor by the previous call.",
-                    },
+                    cursor: CURSOR_INPUT_PROPERTY,
                 },
                 required: scopeRequired("zoneId", scope.zoneId),
                 additionalProperties: false,
@@ -1388,12 +1503,12 @@ function buildTools(scope) {
                 type: "object",
                 properties: {
                     rulesets: { type: "array", items: OPEN_OBJECT_OUTPUT_SCHEMA },
-                    nextCursor: { type: "string" },
+                    nextCursor: NEXT_CURSOR_OUTPUT_PROPERTY,
                 },
                 required: ["rulesets"],
             },
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodePathSegment(zoneArg(args))}/rulesets`,
                     query: {
@@ -1429,7 +1544,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodePathSegment(zoneArg(args))}/rulesets/${encodePathSegment(requireString(args, "rulesetId"))}`,
                 }, ctx);
@@ -1481,7 +1596,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("records", DNS_RECORD_SCHEMA),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodeURIComponent(zoneArg(args))}/dns_records`,
                     query: {
@@ -1521,7 +1636,7 @@ function buildTools(scope) {
             },
             outputSchema: DNS_RECORD_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/zones/${encodeURIComponent(zoneArg(args))}/dns_records/${encodeURIComponent(String(args["recordId"]))}`,
                 }, ctx);
@@ -1552,7 +1667,7 @@ function buildTools(scope) {
                 required: ["id"],
             }),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodeURIComponent(accountArg(args))}/workers/scripts`,
                 }, ctx);
@@ -1583,7 +1698,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/workers/scripts/${encodePathSegment(requireString(args, "scriptName"))}/settings`,
                 }, ctx);
@@ -1609,7 +1724,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("deployments", OPEN_OBJECT_OUTPUT_SCHEMA),
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/workers/scripts/${encodePathSegment(requireString(args, "scriptName"))}/deployments`,
                 }, ctx);
@@ -1648,7 +1763,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/workers/scripts/${encodePathSegment(requireString(args, "scriptName"))}/deployments/${encodePathSegment(requireString(args, "deploymentId"))}`,
                 }, ctx);
@@ -1686,7 +1801,7 @@ function buildTools(scope) {
             },
             handler: async (args, ctx) => {
                 const scriptName = requireString(args, "scriptName");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/workers/scripts/${encodePathSegment(scriptName)}`,
                     query: { force: optionalBoolean(args, "force") },
@@ -1718,7 +1833,7 @@ function buildTools(scope) {
                 required: ["id", "title"],
             }),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodeURIComponent(accountArg(args))}/storage/kv/namespaces`,
                     query: {
@@ -1753,7 +1868,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}`,
                 }, ctx);
@@ -1780,7 +1895,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces`,
                     body: { title: requireString(args, "title") },
@@ -1817,7 +1932,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "PUT",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}`,
                     body: { title: requireString(args, "title") },
@@ -1852,7 +1967,7 @@ function buildTools(scope) {
             },
             handler: async (args, ctx) => {
                 const namespaceId = requireString(args, "namespaceId");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(namespaceId)}`,
                 }, ctx);
@@ -1882,10 +1997,7 @@ function buildTools(scope) {
                         maximum: 1000,
                         description: "Keys per request, 10 to 1000. Defaults to 1000.",
                     },
-                    cursor: {
-                        type: "string",
-                        description: "Opaque cursor returned as nextCursor by the previous call.",
-                    },
+                    cursor: CURSOR_INPUT_PROPERTY,
                 },
                 required: [...scopeRequired("accountId", scope.accountId), "namespaceId"],
                 additionalProperties: false,
@@ -1894,12 +2006,12 @@ function buildTools(scope) {
                 type: "object",
                 properties: {
                     keys: { type: "array", items: OPEN_OBJECT_OUTPUT_SCHEMA },
-                    nextCursor: { type: "string" },
+                    nextCursor: NEXT_CURSOR_OUTPUT_PROPERTY,
                 },
                 required: ["keys"],
             },
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}/keys`,
                     query: {
@@ -1956,7 +2068,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}/bulk/get`,
                     body: {
@@ -1991,12 +2103,34 @@ function buildTools(scope) {
                         items: {
                             type: "object",
                             properties: {
-                                key: { type: "string", minLength: 1, maxLength: 512 },
-                                value: { type: "string", maxLength: 26_214_400 },
-                                expiration: { type: "number" },
-                                expiration_ttl: { type: "number", minimum: 60 },
-                                metadata: { type: ["object", "array", "string", "number", "boolean", "null"] },
-                                base64: { type: "boolean" },
+                                key: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 512,
+                                    description: "Key name, up to Cloudflare's 512 bytes.",
+                                },
+                                value: {
+                                    type: "string",
+                                    maxLength: 26_214_400,
+                                    description: "Value, up to Cloudflare's 25 MiB.",
+                                },
+                                expiration: {
+                                    type: "number",
+                                    description: "Absolute expiry as a Unix timestamp in seconds.",
+                                },
+                                expiration_ttl: {
+                                    type: "number",
+                                    minimum: 60,
+                                    description: "Relative expiry in seconds; Cloudflare's floor is 60.",
+                                },
+                                metadata: {
+                                    type: ["object", "array", "string", "number", "boolean", "null"],
+                                    description: "JSON metadata returned beside the key by list_kv_keys.",
+                                },
+                                base64: {
+                                    type: "boolean",
+                                    description: "Treat value as base64 and store the decoded bytes.",
+                                },
                             },
                             required: ["key", "value"],
                             additionalProperties: false,
@@ -2012,7 +2146,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "PUT",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}/bulk`,
                     body: args["entries"],
@@ -2050,7 +2184,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/storage/kv/namespaces/${encodePathSegment(requireString(args, "namespaceId"))}/bulk/delete`,
                     body: args["keys"],
@@ -2076,10 +2210,7 @@ function buildTools(scope) {
                         maximum: 1000,
                         description: "Buckets per request, 1 to 1000. Defaults to 20.",
                     },
-                    cursor: {
-                        type: "string",
-                        description: "Opaque cursor from a previous call's nextCursor. R2 paginates by cursor, not page number.",
-                    },
+                    cursor: CURSOR_INPUT_PROPERTY,
                     jurisdiction: R2_JURISDICTION_PROPERTY,
                     raw: RAW_INPUT_PROPERTY,
                 },
@@ -2103,15 +2234,12 @@ function buildTools(scope) {
                             required: ["name"],
                         },
                     },
-                    nextCursor: {
-                        type: "string",
-                        description: "Pass back as `cursor` to continue. Absent when the listing is complete.",
-                    },
+                    nextCursor: NEXT_CURSOR_OUTPUT_PROPERTY,
                 },
                 required: ["buckets"],
             },
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodeURIComponent(accountArg(args))}/r2/buckets`,
                     query: {
@@ -2151,7 +2279,7 @@ function buildTools(scope) {
             },
             outputSchema: R2_BUCKET_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}`,
                     headers: r2Headers(args),
@@ -2185,7 +2313,7 @@ function buildTools(scope) {
             },
             outputSchema: R2_BUCKET_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets`,
                     headers: r2Headers(args),
@@ -2227,7 +2355,7 @@ function buildTools(scope) {
             },
             outputSchema: R2_BUCKET_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "PATCH",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}`,
                     headers: {
@@ -2262,7 +2390,7 @@ function buildTools(scope) {
             },
             handler: async (args, ctx) => {
                 const bucketName = requireString(args, "bucketName");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(bucketName)}`,
                     headers: r2Headers(args),
@@ -2300,10 +2428,7 @@ function buildTools(scope) {
                         maximum: 1000,
                         description: "Objects per request, 1 to 1000.",
                     },
-                    cursor: {
-                        type: "string",
-                        description: "Opaque cursor returned as nextCursor by the previous call.",
-                    },
+                    cursor: CURSOR_INPUT_PROPERTY,
                 },
                 required: [...scopeRequired("accountId", scope.accountId), "bucketName"],
                 additionalProperties: false,
@@ -2313,13 +2438,13 @@ function buildTools(scope) {
                 properties: {
                     objects: { type: "array", items: R2_OBJECT_SCHEMA },
                     commonPrefixes: { type: "array", items: { type: "string" } },
-                    nextCursor: { type: "string" },
+                    nextCursor: NEXT_CURSOR_OUTPUT_PROPERTY,
                     truncated: { type: "boolean" },
                 },
                 required: ["objects", "truncated"],
             },
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}/objects`,
                     headers: r2Headers(args),
@@ -2377,7 +2502,7 @@ function buildTools(scope) {
             },
             handler: async (args, ctx) => {
                 const objectKey = requireString(args, "objectKey");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}/objects/${encodeObjectKey(objectKey)}`,
                     headers: r2Headers(args),
@@ -2385,25 +2510,17 @@ function buildTools(scope) {
                 return { deleted: true, objectKey };
             },
         },
-        {
-            name: "get_r2_metrics",
-            description: "Get account-level R2 object-count and storage-size metrics split by storage class and publication state.",
-            annotations: readOnly,
-            inputSchema: {
-                type: "object",
-                properties: { accountId: scopeProperty("accountId", scope.accountId) },
-                required: scopeRequired("accountId", scope.accountId),
-                additionalProperties: false,
-            },
-            outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
-            handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
-                    method: "GET",
-                    path: `/accounts/${encodePathSegment(accountArg(args))}/r2/metrics`,
-                }, ctx);
-                return asRecord(result);
-            },
-        },
+        // No `get_r2_metrics`, `set_r2_cors`, or `delete_r2_cors` here on purpose.
+        // The #350 measurement found `get_r2_metrics` an unprojected,
+        // output-schema-less wrapper around a path, and `set_r2_cors` carrying a
+        // free-form `additionalProperties: true` rule body, so its schema did not
+        // validate the part of the call that actually fails. `delete_r2_cors`
+        // measured clean — a fixed `{deleted}` confirmation behind a closed output
+        // schema — and went anyway, as the other half of one policy pair: with the
+        // write unnamed, a named delete would change a CORS policy through a
+        // different route than setting it does. Reading a policy is still named;
+        // changing one takes the approval-gated raw route, exactly as
+        // structured-data DNS records already do.
         {
             name: "get_r2_cors",
             description: "Get the browser CORS rules configured on an R2 bucket.",
@@ -2420,7 +2537,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}/cors`,
                     headers: r2Headers(args),
@@ -2428,65 +2545,6 @@ function buildTools(scope) {
                 return asRecord(result);
             },
         },
-        {
-            name: "set_r2_cors",
-            description: "Replace an R2 bucket's CORS policy. Supply the complete desired rule list; omitted existing rules are removed.",
-            annotations: { readOnlyHint: false, destructiveHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    accountId: scopeProperty("accountId", scope.accountId),
-                    bucketName: R2_BUCKET_NAME_PROPERTY,
-                    jurisdiction: R2_JURISDICTION_PROPERTY,
-                    rules: {
-                        type: "array",
-                        maxItems: 100,
-                        description: "Complete CORS rule list using Cloudflare fields: allowed.methods, allowed.origins, optional allowed.headers, id, exposeHeaders, and maxAgeSeconds.",
-                        items: { type: "object", additionalProperties: true },
-                    },
-                },
-                required: [...scopeRequired("accountId", scope.accountId), "bucketName", "rules"],
-                additionalProperties: false,
-            },
-            outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
-            handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
-                    method: "PUT",
-                    path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}/cors`,
-                    headers: r2Headers(args),
-                    body: { rules: args["rules"] },
-                }, ctx);
-                return asRecord(result);
-            },
-        },
-        {
-            name: "delete_r2_cors",
-            description: "Remove the complete CORS policy from an R2 bucket.",
-            annotations: { readOnlyHint: false, destructiveHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    accountId: scopeProperty("accountId", scope.accountId),
-                    bucketName: R2_BUCKET_NAME_PROPERTY,
-                    jurisdiction: R2_JURISDICTION_PROPERTY,
-                },
-                required: [...scopeRequired("accountId", scope.accountId), "bucketName"],
-                additionalProperties: false,
-            },
-            outputSchema: {
-                type: "object",
-                properties: { deleted: { type: "boolean" } },
-                required: ["deleted"],
-            },
-            handler: async (args, ctx) => {
-                await callCloudflare(base, {
-                    method: "DELETE",
-                    path: `/accounts/${encodePathSegment(accountArg(args))}/r2/buckets/${encodePathSegment(requireString(args, "bucketName"))}/cors`,
-                    headers: r2Headers(args),
-                }, ctx);
-                return { deleted: true };
-            },
-        },
         {
             name: "list_pages_projects",
             description: "List Cloudflare Pages projects in an account, with their production branch and latest deployment.",
@@ -2522,7 +2580,7 @@ function buildTools(scope) {
                 required: ["name"],
             }),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodeURIComponent(accountArg(args))}/pages/projects`,
                     query: {
@@ -2558,7 +2616,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}`,
                 }, ctx);
@@ -2590,7 +2648,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("deployments", OPEN_OBJECT_OUTPUT_SCHEMA),
             handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(base, {
+                const { result, resultInfo } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/deployments`,
                     query: {
@@ -2634,7 +2692,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/deployments/${encodePathSegment(requireString(args, "deploymentId"))}`,
                 }, ctx);
@@ -2657,7 +2715,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/deployments/${encodePathSegment(requireString(args, "deploymentId"))}/retry`,
                 }, ctx);
@@ -2680,7 +2738,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/deployments/${encodePathSegment(requireString(args, "deploymentId"))}/rollback`,
                 }, ctx);
@@ -2704,7 +2762,7 @@ function buildTools(scope) {
             outputSchema: { type: "object", properties: { deleted: { type: "boolean" }, deploymentId: { type: "string" } }, required: ["deleted", "deploymentId"] },
             handler: async (args, ctx) => {
                 const deploymentId = requireString(args, "deploymentId");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/deployments/${encodePathSegment(deploymentId)}`,
                 }, ctx);
@@ -2726,7 +2784,7 @@ function buildTools(scope) {
             },
             outputSchema: listOutputSchema("domains", OPEN_OBJECT_OUTPUT_SCHEMA),
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "GET",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/domains`,
                 }, ctx);
@@ -2749,7 +2807,7 @@ function buildTools(scope) {
             },
             outputSchema: OPEN_OBJECT_OUTPUT_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/domains`,
                     body: { name: requireString(args, "domain") },
@@ -2774,7 +2832,7 @@ function buildTools(scope) {
             outputSchema: { type: "object", properties: { deleted: { type: "boolean" }, domain: { type: "string" } }, required: ["deleted", "domain"] },
             handler: async (args, ctx) => {
                 const domain = requireString(args, "domain");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/domains/${encodePathSegment(domain)}`,
                 }, ctx);
@@ -2796,7 +2854,7 @@ function buildTools(scope) {
             },
             outputSchema: { type: "object", properties: { purged: { type: "boolean" } }, required: ["purged"] },
             handler: async (args, ctx) => {
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "POST",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(requireString(args, "projectName"))}/purge_build_cache`,
                 }, ctx);
@@ -2819,7 +2877,7 @@ function buildTools(scope) {
             outputSchema: { type: "object", properties: { deleted: { type: "boolean" }, projectName: { type: "string" } }, required: ["deleted", "projectName"] },
             handler: async (args, ctx) => {
                 const projectName = requireString(args, "projectName");
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/accounts/${encodePathSegment(accountArg(args))}/pages/projects/${encodePathSegment(projectName)}`,
                 }, ctx);
@@ -2831,7 +2889,7 @@ function buildTools(scope) {
             // `destructiveHint` stays unset. `readOnlyHint: false` already routes it
             // through call_destructive_tool.
             name: "create_dns_record",
-            description: "Create a content-based DNS record (A, AAAA, CNAME, MX, NS, OPENPGPKEY, PTR, TXT) in a zone. Check for an existing record with list_dns_records first: Cloudflare rejects a duplicate rather than replacing it. Record types that carry structured data, such as SRV and CAA, are readable here but not creatable.",
+            description: "Create a content-based DNS record in a zone; the type enum lists the creatable types. Check list_dns_records first — Cloudflare rejects a duplicate rather than replacing it. Structured types like SRV and CAA are readable but not creatable.",
             annotations: { readOnlyHint: false },
             inputSchema: {
                 type: "object",
@@ -2886,7 +2944,7 @@ function buildTools(scope) {
             },
             outputSchema: DNS_RECORD_SCHEMA,
             handler: async (args, ctx) => {
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "POST",
                     path: `/zones/${encodeURIComponent(zoneArg(args))}/dns_records`,
                     body: {
@@ -2987,7 +3045,7 @@ function buildTools(scope) {
                         },
                     });
                 }
-                const { result } = await callCloudflare(base, {
+                const { result } = await callCloudflare(send, {
                     method: "PATCH",
                     path: `/zones/${encodeURIComponent(zoneArg(args))}/dns_records/${encodeURIComponent(String(args["recordId"]))}`,
                     body,
@@ -3021,7 +3079,7 @@ function buildTools(scope) {
             },
             handler: async (args, ctx) => {
                 const recordId = String(args["recordId"]);
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "DELETE",
                     path: `/zones/${encodeURIComponent(zoneArg(args))}/dns_records/${encodeURIComponent(recordId)}`,
                 }, ctx);
@@ -3121,7 +3179,7 @@ function buildTools(scope) {
                     });
                 }
                 const variant = everything ? "everything" : targeted[0];
-                await callCloudflare(base, {
+                await callCloudflare(send, {
                     method: "POST",
                     path: `/zones/${encodeURIComponent(zoneId)}/purge_cache`,
                     body: everything
@@ -3132,8 +3190,12 @@ function buildTools(scope) {
             },
         },
     ];
+    return tools.map((tool) => ({
+        ...tool,
+        handler: (args, ctx) => tool.handler(args, withAuthentication(ctx, authentication)),
+    }));
 }
-function usageGuide(purpose, scope, instructions) {
+function usageGuide(purpose, scope, instructions, authentication) {
     const accountInstructions = instructions?.trim();
     const zoneLine = scope.zoneId
         ? `This connector defaults to zone \`${scope.zoneId}\`; omit \`zoneId\` unless the request names a different domain.`
@@ -3141,18 +3203,22 @@ function usageGuide(purpose, scope, instructions) {
     const accountLine = scope.accountId
         ? `It defaults to account \`${scope.accountId}\`; omit \`accountId\` unless the request names a different account.`
         : "It declares no default account. `list_accounts` supplies the `accountId` the Workers, KV, R2, and Pages tools need.";
+    const authenticationLine = authentication === "apiToken"
+        ? "The API token is operator-managed and scoped by permission. An `auth_required` failure means the token is missing, invalid, or lacks that call's permission. Call `verify_api_token` first."
+        : "The Global API Key and account email are operator-managed. The key has the same access as its Cloudflare user. An `auth_required` failure means one field is missing, the pair is invalid, or the user lacks access. Call `verify_global_api_key` first.";
     return `# Cloudflare usage
 
 Account purpose: ${purpose}
 
 - ${zoneLine}
 - ${accountLine}
-- Prefer a named tool: its schema is complete, projected, and enough to call it without provider documentation. For an operation without a named tool, use \`cloudflare_api_get\` for GET, \`cloudflare_api_mutate\` for JSON POST/PUT/PATCH/DELETE, or \`cloudflare_api_upload\` for raw and multipart content. Raw tools take a path below \`/client/v4\`; their argument schemas are complete, but endpoint-specific query, header, and body fields come from Cloudflare's API reference. Use \`headers\` for endpoint-specific controls such as \`cf-r2-jurisdiction\`, ETags, and object metadata; authentication, host, content type, and request framing remain connector-owned.
-- The raw tools cover the wider control plane without weakening routing: GET is explicitly read-only; every mutation and upload is destructive and must cross the host's approval boundary. The API token remains the hard provider-side permission boundary. Absolute URLs, traversal, and query strings embedded in \`path\` are refused locally.
+- Prefer a named tool: its schema is complete, projected, and enough to call it without provider documentation. For an operation without a named tool, use \`cloudflare_api_get\` for GET, \`cloudflare_api_mutate\` for JSON POST/PUT/PATCH/DELETE, or \`cloudflare_api_upload\` for raw and multipart content. Raw tools take a path below \`/client/v4\`; their argument schemas are complete, but endpoint-specific query, header, and body fields come from Cloudflare's API reference. Use \`headers\` for endpoint-specific controls such as \`cf-r2-jurisdiction\`, \`Range\`, \`If-None-Match\`, and Cloudflare product metadata. \`Authorization\`, \`Cookie\`, \`Host\`, \`Content-Length\`, \`Content-Type\`, and \`Transfer-Encoding\` are connector-owned and refused: authentication, host, content type, and request framing are not the caller's to set.
+- The raw tools cover the wider control plane without weakening routing: GET is explicitly read-only; every mutation and upload is destructive and must cross the host's approval boundary. The configured Cloudflare credential remains the hard provider-side permission boundary. Absolute URLs, traversal, and query strings embedded in \`path\` are refused locally.
 - Useful raw paths include \`/accounts/{accountId}/images/v1\` (Images), \`/accounts/{accountId}/stream\` (Stream), \`/zones/{zoneId}/email/routing/rules\` (Email Routing), \`/accounts/{accountId}/d1/database\` (D1), and \`/accounts/{accountId}/queues\` (Queues). On GET, use \`responseType: "text"\` or \`"base64"\` for non-JSON content. Direct-upload endpoints can issue upload URLs; \`cloudflare_api_upload\` can also send explicit text, base64 bytes, or multipart fields/files.
-- Lists paginate with \`page\` and \`perPage\` and return a \`page\` object; request the next page only when \`page.hasMore\` is true. \`list_zone_rulesets\`, \`list_r2_buckets\`, \`list_r2_objects\`, and \`list_kv_keys\` instead return \`nextCursor\`; \`list_worker_scripts\` is unpaginated.
+- Two R2 areas are deliberately unnamed. Read a bucket's CORS policy with \`get_r2_cors\`, then change it with \`cloudflare_api_mutate\` — \`PUT\` or \`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors\`, rule fields per Cloudflare's reference — and read account storage totals with \`cloudflare_api_get\` at \`/accounts/{accountId}/r2/metrics\`.
+- Lists paginate with \`page\` and \`perPage\` and return a \`page\` object; request the next page only when \`page.hasMore\` is true. \`list_zone_rulesets\`, \`list_r2_buckets\`, \`list_r2_objects\`, and \`list_kv_keys\` page by cursor instead: pass \`cursor\`, continue while \`nextCursor\` is present, and expect no \`page\` object. Their schemas say so too. \`list_worker_scripts\` is unpaginated.
 - Results are projected to the fields that identify and describe a resource. Pass \`raw: true\` on a read when you genuinely need a field the projection drops.
-- The API token is operator-managed and scoped by permission, not by role. An \`auth_required\` failure means the token is missing, invalid, or lacks that call's permission — it is never fixed by retrying. Call \`verify_api_token\` to tell a dead token from a missing permission, then report which permission is needed rather than trying other tools.
+- ${authenticationLine}
 - A \`rate_limited\` failure carries the wait window. Cloudflare's limit is 1,200 requests per five minutes per user, counted across the dashboard and every token, so do not fan out speculatively; filter server-side with \`name\`, \`type\`, and \`content\` instead of listing everything and filtering locally.
 - Named creates that only add a resource are write-routed without claiming destruction. Updates, overwrites, deletes, rollbacks, cache purges, \`cloudflare_api_mutate\`, and \`cloudflare_api_upload\` are destructive. Read current state before changing it, and prefer a targeted \`purge_cache\` over \`everything\`.
 ${accountInstructions
@@ -3169,42 +3235,83 @@ export function cloudflare(id, options) {
     if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
         throw new Error("cloudflare() maxConcurrency must be a positive integer.");
     }
+    const authentication = options.authentication ?? "apiToken";
+    if (authentication !== "apiToken" && authentication !== "globalApiKey") {
+        throw new Error('cloudflare() authentication must be "apiToken" or "globalApiKey".');
+    }
     const scope = {
-        base: options.baseUrl?.trim() || CLOUDFLARE_API_BASE,
+        send: cloudflareTransport(options.baseUrl?.trim() || CLOUDFLARE_API_BASE),
         accountId: options.accountId?.trim() || undefined,
         zoneId: options.zoneId?.trim() || undefined,
     };
     return api(id, {
         title: options.title ?? "Cloudflare",
         description: `Cloudflare control-plane access for zones, DNS, Workers, KV, R2, Pages, media, email, and other v4 APIs — ${purpose}`,
-        credential: options.credential ?? DEFAULT_CREDENTIAL,
+        credential: credentialConfig(authentication, options.credential),
         callAdmission: admissionPolicy(maxConcurrency),
-        usageGuide: usageGuide(purpose, scope, options.instructions),
-        // The schemas are hand-written and closed; a schema that cannot be
-        // enforced is a bug in this file, not input to pass through.
-        strictValidation: true,
+        usageGuide: {
+            content: usageGuide(purpose, scope, options.instructions, authentication),
+            // Explicit rather than derived: the first content line is the zone
+            // scoping rule, which varies per deployment and reads as an instruction
+            // rather than as the routing fact a browsing agent needs.
+            summary: "Zone and account scoping, named-vs-raw routing, two pagination shapes, and lean-vs-raw results.",
+            // Deliberately not `required`. Every named tool's schema is complete
+            // enough to call it correctly on its own, and the scoping convention the
+            // guide carries is repeated on each `zoneId` and `accountId` property —
+            // so forcing the guide into context before every operation would spend
+            // tokens on a sequence the schemas already express.
+        },
         ...(options.maxResultBytes !== undefined
             ? { maxResultBytes: options.maxResultBytes }
             : {}),
-        tools: buildTools(scope),
-        async testCredential(value, ctx) {
-            try {
-                const { result } = await callCloudflare(scope.base, { method: "GET", path: "/user/tokens/verify" }, {
-                    ...ctx,
-                    credential: { get: async () => value, getAll: async () => ({ value }) },
-                });
-                const status = asRecord(result)["status"];
-                return status === "active"
-                    ? { ok: true, message: "Token verified: active." }
-                    : { ok: false, message: `Token status is "${String(status)}".` };
-            }
-            catch (error) {
-                return {
-                    ok: false,
-                    message: error instanceof Error ? error.message : String(error),
-                };
+        tools: buildTools(scope, authentication),
+        ...(authentication === "apiToken"
+            ? {
+                async testCredential(value, ctx) {
+                    try {
+                        const { result } = await callCloudflare(scope.send, { method: "GET", path: "/user/tokens/verify" }, withAuthentication({
+                            ...ctx,
+                            credential: {
+                                get: async () => value,
+                                getAll: async () => ({ value }),
+                            },
+                        }, authentication));
+                        const status = asRecord(result)["status"];
+                        return status === "active"
+                            ? { ok: true, message: "Token verified: active." }
+                            : { ok: false, message: `Token status is "${String(status)}".` };
+                    }
+                    catch (error) {
+                        return {
+                            ok: false,
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                },
             }
-        },
+            : {
+                async testCredentials(values, ctx) {
+                    try {
+                        const { result } = await callCloudflare(scope.send, { method: "GET", path: "/user" }, withAuthentication({
+                            ...ctx,
+                            credential: {
+                                get: async (field) => field ? values[field] ?? null : null,
+                                getAll: async () => values,
+                            },
+                        }, authentication));
+                        const email = asRecord(result)["email"];
+                        return {
+                            ok: true,
+                            message: `Global API Key verified for ${String(email)}.`,
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            ok: false,
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                },
+            }),
     });
 }
-//# sourceMappingURL=cloudflare.js.map