@wix/mcp 1.0.85 → 1.0.87

package/build/cjs/toolkit.cjs

@@ -17655,6 +17655,7 @@ function rethrowIfUnauthorized(error) {
 
 // src/config/api-request-rules.ts
 var ARRAY_QUERY_PARAMS_RULE = "Repeat array query params once per value: `?fieldsets=URL&fieldsets=RICH_CONTENT`. Do NOT comma-join values (`fieldsets=URL,RICH_CONTENT`), do NOT leave a trailing comma, and do NOT use a value the method schema does not list, even if a sibling method accepts it (draft posts have no `SEO` fieldset).";
+var WQL_FILTER_RULE = "Query and search filters are written in WQL: each field takes a single operator, so combine conditions with the logical operators \u2014 `$and` and `$or` take an array of expressions, `$not` takes one, and they can nest.";
 
 // src/config/default-config.ts
 var AGENT_GOAL = dedent_default`
@@ -17755,7 +17756,7 @@ var SITE_CREATION_COPY = {
 var SITE_GUIDANCE = dedent_default`
   A new-site request has two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
 
-  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. Send them to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. For a full agentic flow, read the recipe first and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it walks you through creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply (you can't reach the file bytes, or something fails), fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
 
   Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
   If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
@@ -17814,12 +17815,25 @@ var ACCOUNT_SITE_EXECUTE_SCOPE = dedent_default`
     siteId?: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     url: string;
+    // Plain object → JSON. A string is sent verbatim (set your own Content-Type,
+    // e.g. multipart/form-data). A Uint8Array/ArrayBuffer is sent as raw bytes
+    // for binary uploads (set your own Content-Type).
     body?: unknown;
     headers?: Record<string, string>;
+    // "base64" returns the response body as a base64 string (data), with
+    // encoding: "base64" on the result — use it for binary downloads (zip,
+    // image, pdf); decoding those as text corrupts them. Binary content types
+    // are returned as base64 automatically even without this. Decode, edit and
+    // re-upload binary WITHIN this script and return only a small summary. If you
+    // must return the bytes, return the wix.request response object itself (so
+    // encoding: "base64" is preserved and it isn't truncated); a bare base64
+    // string you return is treated as plain text and may be truncated.
+    responseType?: "base64";
   }
   interface WixResponse<T = unknown> {
     status: number;
     data: T;
+    encoding?: "base64";
     json(): Promise<T>;
   }
   declare const wix: {
@@ -17958,6 +17972,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     ReadFullDocsArticle: dedent_default`
     Fetches the full Wix docs article or method article with code examples for using the method.
     Docs articles looks like this: https://dev.wix.com/docs/... and they can either be general docs articles or method articles.
+    Take the URL from the user's message or an earlier tool result. To reach an article you have no URL for, search or browse the docs first.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
   `,
@@ -18090,7 +18105,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
   `,
     "import-claude-design-from-url": dedent_default`
     Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
-    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
   `,
     RunWixCliCommand: dedent_default`
     Executes Wix CLI commands for Wix app development and management.
@@ -18517,7 +18532,7 @@ function buildToolDescriptions(includeReadme, includeImageUploadGuidance = true)
     CreateWixBusinessGuide: dedent_default`
     Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
     Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
-    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool — send them to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
+    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 
@@ -18804,6 +18819,22 @@ function renderApps(apps, knownApps) {
   }
   return lines.join("\n");
 }
+function sanitizeCustomAppName(raw) {
+  return raw.replace(/[\x00-\x1f\x7f]/g, " ").replace(/[`*_[\]|<>]/g, "").replace(/\s+/g, " ").trim().slice(0, 60);
+}
+function renderCustomAppsWithSkillsTools(apps) {
+  const relevant = apps.filter((a) => a.appId && (a.hasSkills || a.hasTools)).sort(
+    (a, b) => (a.appName ?? a.appId ?? "").localeCompare(b.appName ?? b.appId ?? "")
+  );
+  if (!relevant.length) return "";
+  const lines = [];
+  for (const app of relevant) {
+    const sanitizedName = app.appName ? sanitizeCustomAppName(app.appName) : "";
+    const name = sanitizedName || app.appId;
+    lines.push(`- \`${name}\` (ID: \`${app.appId}\`)`);
+  }
+  return lines.join("\n");
+}
 function renderProperties(props) {
   const sections = [];
   const regionalFormat = [];
@@ -18866,6 +18897,15 @@ function renderSite(site, index, knownApps) {
     lines.push("");
     lines.push(appsContent);
   }
+  const customAppsWithSkillsToolsContent = renderCustomAppsWithSkillsTools(
+    site.customApps ?? []
+  );
+  if (customAppsWithSkillsToolsContent) {
+    lines.push("");
+    lines.push("### Custom Apps with skills and tools");
+    lines.push("");
+    lines.push(customAppsWithSkillsToolsContent);
+  }
   lines.push("");
   lines.push("---");
   lines.push("");
@@ -19129,7 +19169,10 @@ var paramDescriptions = {
       ARRAY_QUERY_PARAMS_RULE
     ].join("\n"),
     method: "The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)",
-    body: 'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+    body: [
+      'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+      WQL_FILTER_RULE
+    ].join("\n"),
     reason: "One sentence explaining the original user request and why you are calling this API to complete it.",
     sourceDocUrl: [
       "The URL of the documentation or recipe where you found this API endpoint.",
@@ -19453,15 +19496,17 @@ Failed to fetch content: ${errorMsg}`
       const baseContentsPromise = Promise.all(
         baseDocsWithoutRecipes.map(fetchDoc)
       );
-      const skillsContentPromise = getSkillsByPortal(httpClient, {
+      const skillsContentPromise = skillsTags?.length ? getSkillsByPortal(httpClient, {
         portalId: REST_PORTAL_ID,
         ...repo && { repo },
         ...commitHash && { commitHash },
-        ...skillsTags && skillsTags.length > 0 && { tags: skillsTags }
+        tags: skillsTags
       }).catch((err) => {
         console.error("[WixREADME] Failed to fetch skills by portal:", err);
         return null;
-      });
+      }) : fetchDoc({ action: "include", url: RECIPES_INDEX_URL }).then(
+        (doc) => doc?.text ?? null
+      );
       const filter = {};
       if (siteId) filter.siteId = siteId;
       else if (siteName) filter.siteName = siteName;
@@ -19657,7 +19702,9 @@ function getErrorMessage(error) {
 }
 function shouldTryMenuFallbackForDocsRead(error, articleUrl) {
   const message = getErrorMessage(error);
-  if (!message.includes("404") || !articleUrl.includes("/api-reference/")) {
+  const { pathname } = new URL(articleUrl);
+  const isMenuFallbackUrl = articleUrl.includes("/api-reference/") || pathname.startsWith("/docs/velo");
+  if (!message.includes("404") || !isMenuFallbackUrl) {
     return false;
   }
   return !["This resource is deprecated", "No schema found"].some(
@@ -20310,7 +20357,7 @@ var addDocsTools = (server, allowedTools = [
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -20402,7 +20449,7 @@ ${text}`
                   content: [
                     {
                       type: "text",
-                      text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.
+                      text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.
 
 ${text}`
                     }
@@ -20498,6 +20545,14 @@ var import_http_client2 = __toESM(require_index_node(), 1);
 
 // src/tool-utils.ts
 var REST_METHOD_CONTRACT_RETRY_HINT = "Before retrying, make sure you have everything needed for a correct call: the right endpoint URL, HTTP method, request body shape, and response shape. Use the SearchWixRESTDocumentation tool or BrowseWixRESTDocsMenu tool to find the correct method or relevant related articles, the ReadFullDocsArticle tool to read the method description and all code examples, and the SearchWixAPISpec tool for precise field names and schema details.";
+var SINGLE_OPERATOR_PER_FIELD_HINT = 'WQL takes one operator per field object. Split the conditions into separate expressions under the matching logical operator \u2014 `{"$and": [{"field": {"$gte": ...}}, {"field": {"$lte": ...}}]}` \u2014 and retry without re-searching the docs.';
+var FIELD_CAPABILITIES_HINT = "This endpoint declares its filterable and sortable fields with their operators. Read the map with SearchWixAPISpec (`queryMethodData.queryFieldsCapabilitiesMap`, or `searchMethodData.searchFieldsCapabilitiesMap` on search methods) and use only what it lists; otherwise fetch a bounded page and filter or sort the results yourself.";
+var getRetryHint = (errorDetails) => {
+  if (!/Filter contains unsupported operator/i.test(errorDetails)) {
+    return REST_METHOD_CONTRACT_RETRY_HINT;
+  }
+  return /"operator":"\{/.test(errorDetails) ? SINGLE_OPERATOR_PER_FIELD_HINT : FIELD_CAPABILITIES_HINT;
+};
 var safeParseJSON = (text) => {
   try {
     return JSON.parse(text);
@@ -20521,7 +20576,7 @@ var buildErrorMessage = ({
   ].filter((str) => !!str).join("\n");
   return `${baseMessage}
 
-${REST_METHOD_CONTRACT_RETRY_HINT}`;
+${getRetryHint(String(errorDetails))}`;
 };
 var handleWixAPIResponse = async (response) => {
   const requestId = response.headers?.["x-wix-request-id"];
@@ -22188,12 +22243,31 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
   reportBi?.({
     originalLength: typeof data.result === "string" ? data.result.length : JSON.stringify(data.result)?.length
   });
+  const base64Text = base64PayloadText(data.result);
+  if (base64Text !== null) {
+    if (base64Text.length <= MAX_ALLOWED_RESPONSE_CHARS) {
+      return { content: [{ type: "text", text: base64Text }] };
+    }
+    const approxKb = Math.ceil(base64Text.length / 1024).toLocaleString();
+    const limitKb = Math.floor(
+      MAX_ALLOWED_RESPONSE_CHARS / 1024
+    ).toLocaleString();
+    return executeErrorResult(
+      `Binary (base64) result is ~${approxKb} KB, too large to return intact (limit ~${limitKb} KB); truncating it would corrupt the base64. Process the bytes inside your ExecuteWixAPI script \u2014 decode, edit, and re-upload in the same call \u2014 and return only a small summary.`
+    );
+  }
   return {
     content: [
       { type: "text", text: truncateResponse(data.result, maxResponseSize) }
     ]
   };
 }
+function base64PayloadText(result) {
+  if (result !== null && typeof result === "object" && result.encoding === "base64" && typeof result.data === "string") {
+    return JSON.stringify(result);
+  }
+  return null;
+}
 function addExecuteTool(server, options) {
   const {
     codeModeBaseUrl,
@@ -22395,7 +22469,25 @@ function extractText(result) {
   return result.content.filter((content) => content.type === "text" && content.text != null).map((content) => content.text).join("\n");
 }
 var TOOL_RESULT_PREVIEW_MAX_CHARS = 4e3;
-function formatToolResultAdditionalFields(result, extras) {
+var CODEX_OUTPUT_BUDGET_BYTES = 4e4;
+function getCodexTruncation(resultText, client) {
+  const isCodex = [client?.name, client?.userAgent].some(
+    (identity) => identity?.toLowerCase().includes("codex")
+  );
+  if (!isCodex) {
+    return void 0;
+  }
+  const resultBytes = new TextEncoder().encode(resultText).length;
+  if (resultBytes <= CODEX_OUTPUT_BUDGET_BYTES) {
+    return void 0;
+  }
+  return {
+    resultBytes,
+    budgetBytes: CODEX_OUTPUT_BUDGET_BYTES,
+    truncatedBytes: resultBytes - CODEX_OUTPUT_BUDGET_BYTES
+  };
+}
+function formatToolResultAdditionalFields(result, extras, client) {
   const resultText = extractText(result);
   const contentTypes = [
     ...new Set(
@@ -22412,6 +22504,7 @@ function formatToolResultAdditionalFields(result, extras) {
     resultTextLength: resultText.length,
     resultPreviewTruncated: resultText.length > TOOL_RESULT_PREVIEW_MAX_CHARS,
     resultContentTypes: contentTypes,
+    codexTruncation: getCodexTruncation(resultText, client),
     ...extras
   });
 }
@@ -22667,10 +22760,14 @@ function createWixToolkit(options) {
         if (!toolSucceeded) {
           errorBody = extractText(cbResult);
         } else {
-          additionalFields = formatToolResultAdditionalFields(cbResult, {
-            returnedRows: toolBiParams.returnedRows,
-            originalLength: toolBiParams.originalLength
-          });
+          additionalFields = formatToolResultAdditionalFields(
+            cbResult,
+            {
+              returnedRows: toolBiParams.returnedRows,
+              originalLength: toolBiParams.originalLength
+            },
+            { name: clientName }
+          );
         }
         if (!isDevEnvironment) {
           if (toolSucceeded) {

package/build/dts/code-mode/index.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { logger } from '../infra/logger.js';
 import { defaultToolDescriptions } from '../config/default-config.js';
 import { truncateResponse } from './truncate-response.js';
+import { MAX_ALLOWED_RESPONSE_CHARS } from '../infra/response-size-limits.js';
 import { validateExecuteCode } from './validation.js';
 import { desc } from '../config/param-descriptions.js';
 import { rethrowIfUnauthorized } from '../auth/index.js';
@@ -176,12 +177,39 @@ function formatExecuteResult(data, maxResponseSize, reportBi) {
             ? data.result.length
             : JSON.stringify(data.result)?.length
     });
+    // A base64/binary payload (a downloaded zip, image, …) must never be sliced:
+    // a cut base64 string decodes to garbage, so the usual char-limit truncation
+    // would silently corrupt it. Return it whole up to the hard ceiling; past
+    // that, fail cleanly rather than hand back a broken blob.
+    const base64Text = base64PayloadText(data.result);
+    if (base64Text !== null) {
+        if (base64Text.length <= MAX_ALLOWED_RESPONSE_CHARS) {
+            return { content: [{ type: 'text', text: base64Text }] };
+        }
+        const approxKb = Math.ceil(base64Text.length / 1024).toLocaleString();
+        const limitKb = Math.floor(MAX_ALLOWED_RESPONSE_CHARS / 1024).toLocaleString();
+        return executeErrorResult(`Binary (base64) result is ~${approxKb} KB, too large to return intact (limit ~${limitKb} KB); truncating it would corrupt the base64. Process the bytes inside your ExecuteWixAPI script — decode, edit, and re-upload in the same call — and return only a small summary.`);
+    }
     return {
         content: [
             { type: 'text', text: truncateResponse(data.result, maxResponseSize) }
         ]
     };
 }
+// A base64 payload the caller returned as a WixResponse carrying
+// `encoding: "base64"` — the shape `wix.request` produces for a binary body.
+// We key off that explicit marker, never a content heuristic: a long string in
+// the base64 alphabet can be ordinary text (e.g. "x".repeat(30000)) and must
+// still truncate normally. Returns the text to keep intact, or null otherwise.
+function base64PayloadText(result) {
+    if (result !== null &&
+        typeof result === 'object' &&
+        result.encoding === 'base64' &&
+        typeof result.data === 'string') {
+        return JSON.stringify(result);
+    }
+    return null;
+}
 function addExecuteTool(server, options) {
     const { codeModeBaseUrl, codeModeFetch, authStrategy, visitor, toolDescriptions, maxResponseSize } = options;
     const executeUrl = `${codeModeBaseUrl}/api/code-mode/execute`;

package/build/dts/config/api-request-rules.d.ts

@@ -8,4 +8,5 @@
  * single unknown enum member and rejected with HTTP 400.
  */
 export declare const ARRAY_QUERY_PARAMS_RULE = "Repeat array query params once per value: `?fieldsets=URL&fieldsets=RICH_CONTENT`. Do NOT comma-join values (`fieldsets=URL,RICH_CONTENT`), do NOT leave a trailing comma, and do NOT use a value the method schema does not list, even if a sibling method accepts it (draft posts have no `SEO` fieldset).";
+export declare const WQL_FILTER_RULE = "Query and search filters are written in WQL: each field takes a single operator, so combine conditions with the logical operators \u2014 `$and` and `$or` take an array of expressions, `$not` takes one, and they can nest.";
 //# sourceMappingURL=api-request-rules.d.ts.map

package/build/dts/config/api-request-rules.js

@@ -8,4 +8,5 @@
  * single unknown enum member and rejected with HTTP 400.
  */
 export const ARRAY_QUERY_PARAMS_RULE = 'Repeat array query params once per value: `?fieldsets=URL&fieldsets=RICH_CONTENT`. Do NOT comma-join values (`fieldsets=URL,RICH_CONTENT`), do NOT leave a trailing comma, and do NOT use a value the method schema does not list, even if a sibling method accepts it (draft posts have no `SEO` fieldset).';
+export const WQL_FILTER_RULE = 'Query and search filters are written in WQL: each field takes a single operator, so combine conditions with the logical operators — `$and` and `$or` take an array of expressions, `$not` takes one, and they can nest.';
 //# sourceMappingURL=api-request-rules.js.map

package/build/dts/config/default-config.js

@@ -80,7 +80,7 @@ export const SITE_CREATION_COPY = {
 const SITE_GUIDANCE = dedent `
   A new-site request has two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
 
-  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. Send them to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. For a full agentic flow, read the recipe first and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it walks you through creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply (you can't reach the file bytes, or something fails), fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
 
   Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
   If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
@@ -142,12 +142,25 @@ const ACCOUNT_SITE_EXECUTE_SCOPE = dedent `
     siteId?: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     url: string;
+    // Plain object → JSON. A string is sent verbatim (set your own Content-Type,
+    // e.g. multipart/form-data). A Uint8Array/ArrayBuffer is sent as raw bytes
+    // for binary uploads (set your own Content-Type).
     body?: unknown;
     headers?: Record<string, string>;
+    // "base64" returns the response body as a base64 string (data), with
+    // encoding: "base64" on the result — use it for binary downloads (zip,
+    // image, pdf); decoding those as text corrupts them. Binary content types
+    // are returned as base64 automatically even without this. Decode, edit and
+    // re-upload binary WITHIN this script and return only a small summary. If you
+    // must return the bytes, return the wix.request response object itself (so
+    // encoding: "base64" is preserved and it isn't truncated); a bare base64
+    // string you return is treated as plain text and may be truncated.
+    responseType?: "base64";
   }
   interface WixResponse<T = unknown> {
     status: number;
     data: T;
+    encoding?: "base64";
     json(): Promise<T>;
   }
   declare const wix: {
@@ -283,6 +296,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         ReadFullDocsArticle: dedent `
     Fetches the full Wix docs article or method article with code examples for using the method.
     Docs articles looks like this: https://dev.wix.com/docs/... and they can either be general docs articles or method articles.
+    Take the URL from the user's message or an earlier tool result. To reach an article you have no URL for, search or browse the docs first.
     For REST docs, use the URL as-is. For SDK docs, the URL SHOULD include ?apiView=SDK.
     ${reminder}
   `,
@@ -415,7 +429,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
   `,
         'import-claude-design-from-url': dedent `
     Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
-    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
   `,
         RunWixCliCommand: dedent `
     Executes Wix CLI commands for Wix app development and management.
@@ -842,7 +856,7 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
         CreateWixBusinessGuide: dedent `
     Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
     Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
-    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool — send them to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
+    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, fall back to sending the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 

package/build/dts/config/param-descriptions.js

@@ -1,5 +1,5 @@
 import { ALLOWED_HOSTNAMES } from '../api-call/validation.js';
-import { ARRAY_QUERY_PARAMS_RULE } from './api-request-rules.js';
+import { ARRAY_QUERY_PARAMS_RULE, WQL_FILTER_RULE } from './api-request-rules.js';
 /**
  * Centralized parameter descriptions organized by tool.
  * Each tool has all its parameter descriptions in one place.
@@ -15,7 +15,10 @@ export const paramDescriptions = {
             ARRAY_QUERY_PARAMS_RULE
         ].join('\n'),
         method: 'The HTTP method to use for the API call (e.g. GET, POST, PUT, DELETE)',
-        body: 'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+        body: [
+            'The request body as a JSON object or array with all the required fields and values, including nested objects. Pass the actual value (object or array), NOT a JSON string. YOU MUST NEVER MAKE UP A BODY - the body should be based on the conversation context, i.e from the user prompt OR got into the conversation context by the "ReadFullDocsArticle" tool OR by the "SearchWixAPISpec" tool OR by the "ReadFullDocsMethodSchema" tool - i.e based on the API docs, a relevant recipe you read (preferably), a code example you found in the docs, a schema you read etc.. YOU MUST NEVER ASSUME YOU KNOW WHAT THE BODY SCHEMA IS WITHOUT CONCRETE EXAMPLES OR SCHEMA DEFINITIONS FROM THE CONVERSATION CONTEXT. Prefer reading relevant recipes if you have them in context for understand the body schema for API calls.',
+            WQL_FILTER_RULE
+        ].join('\n'),
         reason: 'One sentence explaining the original user request and why you are calling this API to complete it.',
         sourceDocUrl: [
             'The URL of the documentation or recipe where you found this API endpoint.',

package/build/dts/docs/docs.js

@@ -47,7 +47,9 @@ function getErrorMessage(error) {
 }
 function shouldTryMenuFallbackForDocsRead(error, articleUrl) {
     const message = getErrorMessage(error);
-    if (!message.includes('404') || !articleUrl.includes('/api-reference/')) {
+    const { pathname } = new URL(articleUrl);
+    const isMenuFallbackUrl = articleUrl.includes('/api-reference/') || pathname.startsWith('/docs/velo');
+    if (!message.includes('404') || !isMenuFallbackUrl) {
         return false;
     }
     return !['This resource is deprecated', 'No schema found'].some((knownArticleError) => message.includes(knownArticleError));
@@ -671,7 +673,7 @@ export const addDocsTools = (server, allowedTools = [
                                 content: [
                                     {
                                         type: 'text',
-                                        text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.\n\n${text}`
+                                        text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.\n\n${text}`
                                     }
                                 ]
                             };
@@ -746,7 +748,7 @@ export const addDocsTools = (server, allowedTools = [
                                 content: [
                                     {
                                         type: 'text',
-                                        text: `Note: "${articleUrl}" is a documentation category, not an article. Showing its menu contents below. For category URLs, use BrowseWixRESTDocsMenu directly next time.\n\n${text}`
+                                        text: `Note: "${articleUrl}" is not an article. Showing the closest documentation menu below; read the article you need from its links. For category URLs, use BrowseWixRESTDocsMenu directly next time.\n\n${text}`
                                     }
                                 ]
                             };

package/build/dts/docs/get-to-know.js

@@ -169,17 +169,20 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
         //     return '';
         //   });
         const baseContentsPromise = Promise.all(baseDocsWithoutRecipes.map(fetchDoc));
-        // Fetch the skills index from the portal. In PR mode, pass repo+commitHash
-        // to get the PR-aware index (includes recipes added via YAML in the PR).
-        const skillsContentPromise = getSkillsByPortal(httpClient, {
-            portalId: REST_PORTAL_ID,
-            ...(repo && { repo }),
-            ...(commitHash && { commitHash }),
-            ...(skillsTags && skillsTags.length > 0 && { tags: skillsTags })
-        }).catch((err) => {
-            console.error('[WixREADME] Failed to fetch skills by portal:', err);
-            return null;
-        });
+        // Filtered lists still come from the portal. The full management index is
+        // authored alongside the recipes and is fetched like any other article,
+        // using its commit version when a PR override is configured.
+        const skillsContentPromise = skillsTags?.length
+            ? getSkillsByPortal(httpClient, {
+                portalId: REST_PORTAL_ID,
+                ...(repo && { repo }),
+                ...(commitHash && { commitHash }),
+                tags: skillsTags
+            }).catch((err) => {
+                console.error('[WixREADME] Failed to fetch skills by portal:', err);
+                return null;
+            })
+            : fetchDoc({ action: 'include', url: RECIPES_INDEX_URL }).then((doc) => doc?.text ?? null);
         // Auto-inject site context. With no site targeted this is the account-wide
         // view: single-site accounts "just work", and accounts with more than the
         // cap show the first N sites plus a note to use GetSiteContext for the rest.

package/build/dts/import-claude-design-tool/index.js

@@ -86,11 +86,11 @@ export function addImportClaudeDesignTool(server, authStrategy, options) {
             designUrl = new URL(args.url);
         }
         catch {
-            return errorResult('Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site.');
+            return errorResult("Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site.");
         }
         if (designUrl.protocol !== 'https:' ||
             !designUrl.hostname.endsWith(CLAUDE_USER_CONTENT_HOST_SUFFIX)) {
-            return errorResult('Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site.');
+            return errorResult("Invalid design URL — this tool only accepts the claudeusercontent.com URL produced by Claude Design. For site files the user provided themselves, do not retry this tool. For a full agentic flow, read the recipe and publish the files yourself: https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md — it covers creating the site and uploading the files end to end. If you can't follow it, or it doesn't apply, send the user to https://www.wix.com/headless/drop?utm_campaign=mcp to upload them and get a live hosted site.");
         }
         // Resolve the caller's account identity BEFORE the design fetch — the
         // design URL is single-use, so an unauthenticated caller must fail

package/build/dts/infra/tool-bi.d.ts

@@ -6,7 +6,11 @@ import { wixMcpRequestSrc39Evid1607, executeWixApiToolRequestSrc39Evid1612 } fro
  * and concatenates text blocks with newlines.
  */
 export declare function extractText(result: WixToolCallResult): string;
-export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>): string | undefined;
+export interface ToolResultClient {
+    name?: string;
+    userAgent?: string;
+}
+export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>, client?: ToolResultClient): string | undefined;
 export declare function createToolBiEvent(params: Parameters<typeof wixMcpRequestSrc39Evid1607>[0]): import("@wix/bi-logger-api-infra-data/v2/types").LogObject<import("@wix/bi-logger-api-infra-data/v2/types").wixMcpRequestSrc39Evid1607Params>;
 export declare function createExecuteWixAPICallToolBiEvent(params: Parameters<typeof executeWixApiToolRequestSrc39Evid1612>[0]): import("@wix/bi-logger-api-infra-data/v2/types").LogObject<import("@wix/bi-logger-api-infra-data/v2/types").executeWixApiToolRequestSrc39Evid1612Params>;
 //# sourceMappingURL=tool-bi.d.ts.map

package/build/dts/infra/tool-bi.js

@@ -11,7 +11,27 @@ export function extractText(result) {
         .join('\n');
 }
 const TOOL_RESULT_PREVIEW_MAX_CHARS = 4000;
-export function formatToolResultAdditionalFields(result, extras) {
+// Codex keeps 10,000 tokens of a tool result by default, estimated at 4 bytes
+// per token, and drops the middle of anything longer.
+const CODEX_OUTPUT_BUDGET_BYTES = 40_000;
+// Predicted from the default budget: a user who raised Codex's
+// tool_output_token_limit is flagged here but not actually truncated.
+function getCodexTruncation(resultText, client) {
+    const isCodex = [client?.name, client?.userAgent].some((identity) => identity?.toLowerCase().includes('codex'));
+    if (!isCodex) {
+        return undefined;
+    }
+    const resultBytes = new TextEncoder().encode(resultText).length;
+    if (resultBytes <= CODEX_OUTPUT_BUDGET_BYTES) {
+        return undefined;
+    }
+    return {
+        resultBytes,
+        budgetBytes: CODEX_OUTPUT_BUDGET_BYTES,
+        truncatedBytes: resultBytes - CODEX_OUTPUT_BUDGET_BYTES
+    };
+}
+export function formatToolResultAdditionalFields(result, extras, client) {
     const resultText = extractText(result);
     const contentTypes = [
         ...new Set(result.content?.map((content) => content.type) ?? [])
@@ -24,6 +44,7 @@ export function formatToolResultAdditionalFields(result, extras) {
         resultTextLength: resultText.length,
         resultPreviewTruncated: resultText.length > TOOL_RESULT_PREVIEW_MAX_CHARS,
         resultContentTypes: contentTypes,
+        codexTruncation: getCodexTruncation(resultText, client),
         ...extras
     });
 }

package/build/dts/tool-utils.js

@@ -1,5 +1,16 @@
 const REST_METHOD_CONTRACT_RETRY_HINT = 'Before retrying, make sure you have everything needed for a correct call: the right endpoint URL, HTTP method, request body shape, and response shape. ' +
     'Use the SearchWixRESTDocumentation tool or BrowseWixRESTDocsMenu tool to find the correct method or relevant related articles, the ReadFullDocsArticle tool to read the method description and all code examples, and the SearchWixAPISpec tool for precise field names and schema details.';
+const SINGLE_OPERATOR_PER_FIELD_HINT = 'WQL takes one operator per field object. Split the conditions into separate expressions under the matching logical operator — `{"$and": [{"field": {"$gte": ...}}, {"field": {"$lte": ...}}]}` — and retry without re-searching the docs.';
+const FIELD_CAPABILITIES_HINT = 'This endpoint declares its filterable and sortable fields with their operators. Read the map with SearchWixAPISpec (`queryMethodData.queryFieldsCapabilitiesMap`, or `searchMethodData.searchFieldsCapabilitiesMap` on search methods) and use only what it lists; otherwise fetch a bounded page and filter or sort the results yourself.';
+const getRetryHint = (errorDetails) => {
+    if (!/Filter contains unsupported operator/i.test(errorDetails)) {
+        return REST_METHOD_CONTRACT_RETRY_HINT;
+    }
+    // The API reports a field object with several operators as one unknown operator whose name is that object.
+    return /"operator":"\{/.test(errorDetails)
+        ? SINGLE_OPERATOR_PER_FIELD_HINT
+        : FIELD_CAPABILITIES_HINT;
+};
 export const DEFAULT_OPENAI_SECURITY_SCHEMES = [
     { type: 'oauth2', scopes: ['offline_access'] }
 ];
@@ -28,7 +39,7 @@ export const buildErrorMessage = ({ status, statusText, requestId, responseData
     ]
         .filter((str) => !!str)
         .join('\n');
-    return `${baseMessage}\n\n${REST_METHOD_CONTRACT_RETRY_HINT}`;
+    return `${baseMessage}\n\n${getRetryHint(String(errorDetails))}`;
 };
 export const handleWixAPIResponse = async (response) => {
     const requestId = response.headers?.['x-wix-request-id'];

package/build/dts/toolkit-entry.d.cts

@@ -175,7 +175,11 @@ export type CodeModeFetch = (url: string, init: RequestInit) => Promise<Response
  * and concatenates text blocks with newlines.
  */
 export declare function extractText(result: WixToolCallResult): string;
-export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>): string | undefined;
+export interface ToolResultClient {
+	name?: string;
+	userAgent?: string;
+}
+export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>, client?: ToolResultClient): string | undefined;
 /** A single tool extracted from @wix/mcp, ready to execute. */
 export interface WixTool {
 	/** Tool name (e.g. 'CallWixSiteAPI', 'SearchWixRESTDocumentation') */

package/build/dts/toolkit-entry.d.ts

@@ -175,7 +175,11 @@ export type CodeModeFetch = (url: string, init: RequestInit) => Promise<Response
  * and concatenates text blocks with newlines.
  */
 export declare function extractText(result: WixToolCallResult): string;
-export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>): string | undefined;
+export interface ToolResultClient {
+	name?: string;
+	userAgent?: string;
+}
+export declare function formatToolResultAdditionalFields(result: WixToolCallResult, extras?: Record<string, unknown>, client?: ToolResultClient): string | undefined;
 /** A single tool extracted from @wix/mcp, ready to execute. */
 export interface WixTool {
 	/** Tool name (e.g. 'CallWixSiteAPI', 'SearchWixRESTDocumentation') */