@cloudinary/asset-management-mcp 0.9.0 → 0.9.2

package/src/mcp-server/apps/asset-upload-app.ts

@@ -18,6 +18,7 @@ import { toJSONSchema } from "zod";
 import {
   SHARED_CSS_TOKENS,
   SHARED_CSS_COMPONENTS,
+  SHARED_JS_ICONS,
   SHARED_JS_MCP_CLIENT,
   SHARED_JS_HELPERS,
   SHARED_JS_TOOLTIPS,
@@ -61,15 +62,8 @@ const UPLOAD_CSS = /* css */ `
 .upload-header h1 {
   font-size: var(--cld-font-sm); font-weight: 600; color: var(--cld-text);
 }
-.upload-header-icon { font-size: 20px; }
-.upload-header { position: relative; }
-.back-link {
-  position: absolute; top: -2px; right: 0;
-  background: none; border: none; cursor: pointer;
-  color: var(--cld-accent); font-size: var(--cld-font-xs);
-  padding: 2px 6px; border-radius: 4px;
-}
-.back-link:hover { text-decoration: underline; background: var(--cld-accent-bg); }
+.upload-header-icon { display: flex; align-items: center; justify-content: center; }
+.upload-header-icon svg { width: 20px; height: 20px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
 
 .upload-result .detail-section { padding: 14px 16px; }
 .upload-result .detail-section:first-child { padding-top: 0; }
@@ -508,16 +502,18 @@ function renderPicker() {
   var h = "";
 
   h += '<div class="upload-header">';
+  h += '<span class="upload-header-icon icon-accent">' + IC.uploadCloud + '</span>';
+  h += "<h1>Upload to Cloudinary</h1>";
+  h += '<div id="header-actions" style="display:flex;align-items:center;gap:6px;margin-left:auto">';
   if (lastResult) {
-    h += '<button class="back-link" id="back-to-result-btn">\\u2190 Back to Result</button>';
+    h += '<button class="icon-btn" id="back-to-result-btn">' + IC.chevronLeft + ' Back</button>';
   }
-  h += '<span class="upload-header-icon">\\u2B06\\uFE0F</span>';
-  h += "<h1>Upload to Cloudinary</h1>";
+  h += '</div>';
   h += "</div>";
 
   if (stagedFile) {
     h += '<div class="upload-staged">';
-    h += '<div class="upload-staged-icon">\\u{1F4C4}</div>';
+    h += '<div class="upload-staged-icon">' + IC.file + '</div>';
     h += '<div class="upload-staged-info">';
     h += '<div class="upload-staged-name">' + esc(stagedFile.name) + "</div>";
     if (stagedFile.size) {
@@ -528,11 +524,11 @@ function renderPicker() {
       h += '<div class="upload-staged-meta">Remote URL</div>';
     }
     h += "</div>";
-    h += '<button class="upload-staged-clear" id="clear-staged-btn" title="Remove">\\u2715</button>';
+    h += '<button class="upload-staged-clear icon-btn icon-only" id="clear-staged-btn" title="Remove">' + IC.x + '</button>';
     h += "</div>";
   } else {
     h += '<div class="upload-zone" id="drop-zone">';
-    h += '<div class="upload-zone-icon">\\u{1F4C1}</div>';
+    h += '<div class="upload-zone-icon">' + IC.folderOpen + '</div>';
     h += '<div class="upload-zone-text">Drag & drop a file here</div>';
     h += '<div class="upload-zone-hint">Images, videos, PDFs, and other files up to 60 MB</div>';
     h += '<button class="upload-zone-btn" id="browse-btn">Browse Files</button>';
@@ -556,6 +552,7 @@ function renderPicker() {
   }
 
   root.innerHTML = h;
+  renderThemeToggle();
 
   var backBtn = document.getElementById("back-to-result-btn");
   if (backBtn && lastResult) {
@@ -635,12 +632,13 @@ function renderUploading(name, meta) {
   var h = "";
 
   h += '<div class="upload-header">';
-  h += '<span class="upload-header-icon">\\u2B06\\uFE0F</span>';
-  h += "<h1>Uploading\\u2026</h1>";
+  h += '<span class="upload-header-icon icon-accent">' + IC.uploadCloud + '</span>';
+  h += '<h1>Uploading…</h1>';
+  h += '<div id="header-actions" style="display:flex;align-items:center;gap:6px;margin-left:auto"></div>';
   h += "</div>";
 
   h += '<div class="upload-preview">';
-  h += '<div class="upload-preview-icon">\\u{1F4C4}</div>';
+  h += '<div class="upload-preview-icon">' + IC.file + '</div>';
   h += '<div class="upload-preview-info">';
   h += '<div class="upload-preview-name">' + esc(name) + "</div>";
   h += '<div class="upload-preview-meta">' + esc(meta) + "</div>";
@@ -652,6 +650,7 @@ function renderUploading(name, meta) {
   h += "</div>";
 
   root.innerHTML = h;
+  renderThemeToggle();
   animateProgress();
 }
 
@@ -705,7 +704,7 @@ function renderUploadError(title, msg) {
     var header = document.querySelector(".upload-header h1");
     if (header) header.textContent = title;
     var icon = document.querySelector(".upload-header-icon");
-    if (icon) icon.textContent = "\\u26A0\\uFE0F";
+    if (icon) { icon.innerHTML = IC.alertTriangle; icon.className = "upload-header-icon icon-warning"; }
 
     var safeMsg = esc(msg).replace(/\\n/g, "<br>");
     var h = '<div class="upload-error-msg">' + safeMsg + "</div>";
@@ -717,14 +716,16 @@ function renderUploadError(title, msg) {
     var root = document.getElementById("app");
     var safeMsg = esc(msg).replace(/\\n/g, "<br>");
     var h = '<div class="upload-header">';
-    h += '<span class="upload-header-icon">\\u26A0\\uFE0F</span>';
+    h += '<span class="upload-header-icon icon-warning">' + IC.alertTriangle + '</span>';
     h += "<h1>" + esc(title) + "</h1>";
+    h += '<div id="header-actions" style="display:flex;align-items:center;gap:6px;margin-left:auto"></div>';
     h += "</div>";
     h += '<div class="upload-error-msg">' + safeMsg + "</div>";
     h += '<div class="upload-another" style="margin-top:14px;text-align:center">';
     h += '<button class="prompt-btn prompt-btn-primary" id="retry-upload-btn">Try from App</button>';
     h += "</div>";
     root.innerHTML = h;
+    renderThemeToggle();
   }
 
   var btn = document.getElementById("retry-upload-btn");
@@ -769,8 +770,9 @@ function renderLocalFileNeeded(expectedName, errMsg) {
   var classified = classifyFileError(errMsg);
   var root = document.getElementById("app");
   var h = '<div class="upload-header">';
-  h += '<span class="upload-header-icon">\\u{1F4C1}</span>';
+  h += '<span class="upload-header-icon icon-accent">' + IC.folderOpen + '</span>';
   h += "<h1>" + esc(classified.title) + "</h1>";
+  h += '<div id="header-actions" style="display:flex;align-items:center;gap:6px;margin-left:auto"></div>';
   h += "</div>";
   h += '<div class="prompt" style="margin-bottom:16px">';
   h += '<div class="prompt-desc">The file <strong>' + esc(expectedName)
@@ -785,13 +787,14 @@ function renderLocalFileNeeded(expectedName, errMsg) {
   }
   h += "</div>";
   h += '<div class="upload-zone" id="drop-zone">';
-  h += '<div class="upload-zone-icon">\\u{1F4C1}</div>';
+  h += '<div class="upload-zone-icon">' + IC.folderOpen + '</div>';
   h += '<div class="upload-zone-text">Drop <strong>' + esc(expectedName) + "</strong> here</div>";
   h += '<div class="upload-zone-hint">Or click to browse your files</div>';
   h += '<button class="upload-zone-btn" id="browse-btn">Browse Files</button>';
   h += '<input type="file" id="file-input" style="display:none">';
   h += "</div>";
   root.innerHTML = h;
+  renderThemeToggle();
 
   function onFileSelected(file) {
     var reader = new FileReader();
@@ -904,8 +907,9 @@ function renderResult(r) {
   var h = "";
 
   h += '<div class="upload-header">';
-  h += '<span class="upload-header-icon">' + (isPending ? "\\u23F3" : "\\u2705") + '</span>';
+  h += '<span class="upload-header-icon ' + (isPending ? "icon-accent" : "icon-success") + '">' + (isPending ? IC.clock : IC.checkCircle) + '</span>';
   h += "<h1>" + (isPending ? "Upload Queued" : "Upload Complete") + "</h1>";
+  h += '<div id="header-actions" style="display:flex;align-items:center;gap:6px;margin-left:auto"></div>';
   h += "</div>";
 
   h += '<div class="upload-result">';
@@ -966,6 +970,7 @@ function renderResult(r) {
   h += "</div></div>";
 
   root.innerHTML = h;
+  renderThemeToggle();
 
   root.addEventListener("click", function handler(e) {
     var el = e.target;
@@ -1102,6 +1107,7 @@ ${UPLOAD_CSS}
 <div id="app"><div class="status">Preparing upload&hellip;</div></div>
 
 <script>
+${SHARED_JS_ICONS}
 ${SHARED_JS_MCP_CLIENT}
 ${SHARED_JS_HELPERS}
 ${SHARED_JS_TOOLTIPS}

package/src/mcp-server/apps/config.ts

@@ -12,8 +12,7 @@ export const MCP_APPS: readonly McpApp[] = [
   "asset-upload",
 ];
 
-// Flip to [...MCP_APPS] to enable MCP Apps by default.
-export const DEFAULT_MCP_APPS: readonly McpApp[] = [];
+export const DEFAULT_MCP_APPS: readonly McpApp[] = [...MCP_APPS];
 
 export function parseMcpAppsList(value: string): McpApp[] {
   const parts = value.split(",").map((s) => s.trim()).filter(Boolean);

package/src/mcp-server/apps/extensions.ts

@@ -66,7 +66,12 @@ function appResourceContent(uri: URL, html: string) {
       uri: uri.toString(),
       mimeType: MCP_APP_MIME_TYPE,
       text: html,
-      _meta: { ui: { csp: { resourceDomains: CSP_RESOURCE_DOMAINS } } },
+      _meta: {
+        ui: {
+          csp: { resourceDomains: CSP_RESOURCE_DOMAINS },
+          permissions: { clipboardWrite: {} },
+        },
+      },
       // deno-lint-ignore no-explicit-any
     } as any],
   };

package/src/mcp-server/cli/serve/impl.ts

@@ -42,7 +42,7 @@ async function startStreamableHTTP(cliFlags: ServeCommandFlags) {
   app.use((req, res, next) => {
     res.header("Access-Control-Allow-Origin", "*");
     res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-    res.header("Access-Control-Allow-Headers", "Content-Type, *");
+    res.header("Access-Control-Allow-Headers", "*");
     if (req.method === "OPTIONS") {
       res.sendStatus(204);
       return;

package/src/mcp-server/mcp-server.ts

@@ -22,7 +22,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "0.9.0",
+    currentVersion: "0.9.2",
   },
 });
 

package/src/mcp-server/server.ts

@@ -60,7 +60,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "CloudinaryAssetMgmt",
-    version: "0.9.0",
+    version: "0.9.2",
   });
 
   const getClient = deps.getSDK || (() =>

package/src/mcp-server/tools/searchSearchAssets.ts

@@ -19,9 +19,53 @@ export const tool$searchSearchAssets: ToolDefinition<typeof args> = {
 
 Returns a list of resources matching the specified search criteria.
 
-Uses Lucene-like query language to search by descriptive attributes (public_id, filename, folder, tags, context), file details (resource_type, format, bytes, width, height), embedded data (image_metadata), and analyzed data (face_count, colors, quality_score). Supports aggregate counts and complex Boolean expressions.
+Uses a Lucene-like query language to filter assets by descriptive attributes (\`public_id\`, \`asset_id\`, \`filename\`, \`display_name\`, \`folder\` / \`asset_folder\`, \`tags\`, \`context.<key>\`), file details (\`resource_type\`, \`type\`, \`format\`, \`bytes\`, \`width\`, \`height\`, \`duration\`, \`pages\`, \`aspect_ratio\`, \`transparent\`, \`grayscale\`), lifecycle dates (\`uploaded_at\`, \`created_at\`, \`taken_at\`, \`updated_at\`, \`last_updated.<kind>\`), moderation and lifecycle state (\`status\`, \`moderation_status\`, \`moderation_kind\`), embedded data (\`image_metadata.*\`), structured metadata (\`metadata.<external_id>\`), and analysis fields (\`face_count\`, \`colors\`, \`quality_score\`, \`illustration_score\`, \`accessibility_analysis.*\`). Supports sorting, aggregate counts, and complex boolean expressions. See the \`expression\` parameter for the full field reference.
 
-Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics
+## Expression syntax
+
+- **Match**: \`field:value\` (token match) or \`field=value\` (exact match). Examples: \`tags:shirt\`, \`tags=cotton\`.
+- **Comparisons**: \`>\`, \`<\`, \`>=\`, \`<=\` for numbers and dates. Example: \`bytes>10000000\`.
+- **Ranges**: \`field:[from TO to]\` inclusive, \`field:{from TO to}\` exclusive. Example: \`width:{200 TO 1028}\`.
+- **Booleans**: \`AND\`, \`OR\`, \`NOT\` (uppercase), or \`+\` (must), \`-\` (must not). \`NOT\` must appear between clauses — a bare leading \`NOT\` is a parse error; use \`-field:value\` to negate the first clause. Group with parentheses: \`(shirt OR pants) AND clothes\`.
+- **Wildcards**: trailing \`*\` only, for prefix match (\`public_id:shoes_*\`, \`format:jp*\`, \`tags:shirt*\`). Not supported on \`folder\`, \`asset_folder\`, \`resource_type\`, or \`type\`. Leading \`*\`, middle \`*\`, \`?\`, and bare \`*\` (\`folder:*\`, \`context.alt:*\`) are all parse errors — wildcards cannot be used as a "field is present" probe.
+- **Tokenized vs exact fields**: \`tags\`, \`filename\`, \`display_name\`, \`context.<key>\`, and \`metadata.<id>\` match on tokens split by whitespace and punctuation — \`tags:analysis\` matches the tag \`full-analysis\`. \`public_id\`, \`folder\`, \`asset_folder\`, and \`format\` match the whole value — \`public_id:dog\` will not match \`dog_pldcwy\`; use \`public_id="dog_pldcwy"\` (exact) or \`public_id:dog*\` (prefix). These exact-match fields still accept a trailing \`*\` for prefix match (except \`folder\` / \`asset_folder\`, where wildcards are ignored).
+- **Dates**: ISO-8601 in quotes (\`uploaded_at>"2024-01-15"\`) or relative shorthand \`Nh\`, \`Nd\`, \`Nw\`, \`Nm\`, \`Ny\` (\`uploaded_at>1d\`, \`created_at:[4w TO 1w]\`). Send raw \`<\`/\`>\`, never HTML-escaped.
+- **Quoting**: wrap any value containing a space, colon, or other reserved character (\`! ( ) { } [ ] ^ ~ ?  \\ = & < > |\`) in double quotes, or escape each character with \`\\\`. Examples: \`tags:"service:mantels"\`, \`aspect_ratio:"16:9"\`, \`folder:"My Folder"\`.
+
+## Common mistakes
+
+- Use \`folder:\` or \`asset_folder:\` (singular); \`folders:\`, \`asset_folder_id:\`, and other invented variants are not valid fields. Pass the exact folder name — wildcards do not apply here.
+- There is no "has any value" / presence probe. \`folder:*\`, \`metadata.alt:*\`, \`context.key:*\`, \`tags:*\`, and \`-tags:*\` are all parse errors. See *"Which assets have any value for \`metadata.<id>\`?"* under **Common tasks** for workarounds.
+- \`NOT foo AND bar\` is a parse error. Write it as \`bar AND NOT foo\` or \`-foo AND bar\`, and keep every \`NOT\` between two clauses (\`a AND NOT b AND NOT c\` is fine; \`NOT b AND NOT c …\` is not).
+- \`public_id:dog\` will not match \`dog_pldcwy\`. Use \`public_id="dog_pldcwy"\` (exact) or \`public_id:dog*\` (prefix).
+- \`tags=service:mantels\` fails because the unquoted colon is parsed as a field separator. Use \`tags="service:mantels"\` or \`tags=service\\:mantels\`.
+- Do not HTML-escape operators. Send \`uploaded_at<1h\`, not \`uploaded_at&lt;1h\`.
+- Do not leave an operand empty (e.g. \`tags: AND -tags:foo\`). Omit the empty clause entirely.
+
+## Tips
+
+- Set \`max_results: 0\` to return only \`total_count\` and \`aggregations\` without any resource payload — useful for counts and aggregation-only queries.
+- \`total_count\` is always present in the response; prefer it over running an aggregation just to get a count.
+- \`aggregate\` (both simple and range variants) and the \`metadata\`, \`image_metadata\`, \`image_analysis\` values of \`with_field\` require a Tier 2 search plan.
+- Range aggregations require each range to include a \`key\` label (1–20 chars, \`[a-zA-Z0-9_-]+\`) and at least one of \`from\` / \`to\`.
+
+## Common tasks
+
+- **Count matching assets** — put the filter in \`expression\` with \`max_results: 0\` and read \`total_count\` from the response. Works on every tier; no \`aggregate\` needed.
+- **Preview one matching asset** — set \`max_results: 1\`; add \`with_field: ["tags", "context"]\` (or \`metadata\`, Tier 2) to inspect values. Prefer this over fetching and scanning a full page.
+- **Distribution of values for a field** — Tier 2: \`aggregate: [format|resource_type|type]\` for enum counts, or range aggregations on \`bytes\`, \`image_pixels\`, \`video_pixels\`, or \`duration\`. Tier 1 fallback: run N small queries with \`max_results: 0\`, one per candidate value, and read \`total_count\` from each.
+- **"Which assets have any value for \`metadata.<id>\`?"** — not expressible directly (\`metadata.X:*\` is a parse error; there is no presence probe). Workarounds: (a) if the field has a known value set, enumerate — \`metadata.region:(apac OR emea OR amer)\`; (b) query broadly with \`with_field: ["metadata"]\` (Tier 2) and filter client-side for entries where the field is set; (c) at ingest time, attach a sentinel tag whenever the field is set, then search by that tag.
+- **Newest / largest N** — keep the filter in \`expression\` and sort explicitly: \`sort_by: [{uploaded_at: "desc"}]\` with \`max_results: 10\`.
+- **Filter by folder** — both \`asset_folder:"parent/child"\` and \`folder:"parent/child"\` match an exact folder path; there is no wildcard or "contains". To query across multiple folders, enumerate: \`asset_folder:("campaigns/2024" OR "campaigns/2025")\`.
+- **Filter by metadata when you only know the label** — first call \`list-metadata-fields\` to resolve the label to an \`external_id\`, then query \`metadata.<external_id>:value\`.
+- **Multiple independent filters in one turn** — prefer one \`expression\` with \`OR\` / parentheses over firing many parallel calls: \`metadata.region:apac OR metadata.region:emea\` in a single request is faster and more reliable than two parallel requests.
+
+## Examples
+
+- \`tags:shirt AND uploaded_at>1d\`
+- \`resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)\`
+- \`folder:products AND context.category:electronics\`
+- \`tags:"service:mantels" AND -tags:discontinued\`
 `,
   scopes: ["librarian"],
   annotations: {

package/src/models/searchparameters.ts

@@ -23,20 +23,30 @@ export const Type$zodSchema = z.enum([
 ]);
 
 export type SearchParametersRange = {
+  key: string;
   from?: number | undefined;
   to?: number | undefined;
 };
 
 export const SearchParametersRange$zodSchema: z.ZodType<SearchParametersRange> =
   z.object({
-    from: z.number().optional().describe("Start of the range (inclusive)"),
-    to: z.number().optional().describe("End of the range (exclusive)"),
+    from: z.number().optional().describe(
+      "Start of the range (inclusive). At least one of `from` / `to` is required.",
+    ),
+    key: z.string().describe(
+      "A label for the bucket, returned in the aggregation response. 1–20 chars, alphanumeric plus `-` and `_`.",
+    ),
+    to: z.number().optional().describe(
+      "End of the range (exclusive). At least one of `from` / `to` is required.",
+    ),
   });
 
 export type Aggregate = { type: Type; ranges: Array<SearchParametersRange> };
 
 export const Aggregate$zodSchema: z.ZodType<Aggregate> = z.object({
-  ranges: z.array(z.lazy(() => SearchParametersRange$zodSchema)),
+  ranges: z.array(z.lazy(() => SearchParametersRange$zodSchema)).describe(
+    "One or more ranges for the numeric field. Each range must include a `key` label and at least one of `from` / `to`.\n",
+  ),
   type: Type$zodSchema,
 });
 
@@ -54,14 +64,18 @@ export const AggregateEnum$zodSchema = z.enum([
 ]);
 
 /**
- * Fields or ranges to aggregate search results by.
+ * Fields or ranges to aggregate search results by. Requires a Tier 2 search plan; on Tier 1 the field is accepted but aggregations are omitted from the response.
+ *
+ * @remarks
  */
 export type AggregateUnion = Array<AggregateEnum> | Array<Aggregate>;
 
 export const AggregateUnion$zodSchema: z.ZodType<AggregateUnion> = z.union([
   z.array(AggregateEnum$zodSchema),
   z.array(z.lazy(() => Aggregate$zodSchema)),
-]).describe("Fields or ranges to aggregate search results by.");
+]).describe(
+  "Fields or ranges to aggregate search results by. Requires a Tier 2 search plan; on Tier 1 the field is accepted but aggregations are omitted from the response.\n",
+);
 
 export const WithField = {
   Context: "context",
@@ -102,15 +116,17 @@ export const SearchParameters$zodSchema: z.ZodType<SearchParameters> = z.object(
     aggregate: z.union([
       z.array(AggregateEnum$zodSchema),
       z.array(z.lazy(() => Aggregate$zodSchema)),
-    ]).optional().describe("Fields or ranges to aggregate search results by."),
+    ]).optional().describe(
+      "Fields or ranges to aggregate search results by. Requires a Tier 2 search plan; on Tier 1 the field is accepted but aggregations are omitted from the response.\n",
+    ),
     expression: z.string().optional().describe(
-      "The search expression. Supports exact match, wildcard match, presence, greater/less than, and range. For details on building expressions, see the Search API documentation.",
+      "The Lucene-like search expression. Supports token match (`:`), exact match (`=`), trailing `*` for prefix match, ranges (`[a TO b]`, `{a TO b}`), and comparisons (`>`, `<`, `>=`, `<=`). Combine terms with uppercase `AND`, `OR`, `NOT`, or `+`/`-`. `NOT` must appear between clauses — a leading `NOT` is a parse error; use `-field:value` to negate the first clause. Group with parentheses.\n\nWrap values containing spaces, colons, or other reserved characters (`! ( ) { } [ ] ^ ~ ?  \\ = & < > |`) in double quotes, e.g. `tags:\"service:mantels\"`, `aspect_ratio:\"16:9\"`. Send raw `<`/`>`, never HTML-escaped.\n\nWildcards are prefix-only (trailing `*`). A bare `*` (e.g. `folder:*`, `context.alt:*`, `metadata.key:*`, `tags:*`, `-tags:*`) is a parse error — there is no \"has any value\" / presence probe. Either drop the clause, use a concrete prefix, or filter on a known token.\n\nDates: ISO-8601 in quotes, or relative shorthand `1h`, `1d`, `1w`, `1m`, `1y` (`uploaded_at>1d`, `created_at:[4w TO 1w]`).\n\nSupported fields: `public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder` (singular, not `folders`), `tags`, `context.<key>`, `metadata.<external_id>`, `resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`, `status`, `moderation_status`, `moderation_kind`, `uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`, `face_count`, `illustration_score`, `quality_score`. Fields under `image_metadata.*`, `image_analysis.*`, `quality_analysis.*`, and `accessibility_analysis.*` also require the matching `with_field` to be returned in the response.\n\nSee the [search expressions guide](https://cloudinary.com/documentation/search_expressions.md) for the full reference.\n",
     ),
     fields: z.string().optional().describe(
       "A comma-separated list of fields to include in the response.\nNotes:\n- This parameter takes precedence over the with_field parameter, so if you want any additional asset attributes returned, make sure to also include them in this list (e.g., tags or context).\n- The following fields are always included in the response: public_id, asset_id, asset_folder, created_at, status, type, and resource_type.\n",
     ),
     max_results: z.int().optional().describe(
-      "The maximum number of results to return. Default - 50. Maximum - 500.",
+      "The maximum number of results to return. Default - 50. Maximum - 500.\nSet to `0` to get only `total_count` and `aggregations` without any resources in the response — useful for counting or aggregation-only queries.\n",
     ),
     next_cursor: z.string().optional().describe(
       "The cursor value to get the next page of results. Available when a previous search returned more results than max_results.",
@@ -120,7 +136,7 @@ export const SearchParameters$zodSchema: z.ZodType<SearchParameters> = z.object(
         "An array of single-key objects mapping a field to a sort direction. Each object must contain exactly one field name mapped to 'asc' or 'desc'.\nDefault: [{\"created_at\": \"desc\"}].\n",
       ),
     with_field: z.array(WithField$zodSchema).optional().describe(
-      "The additional fields to include in the response. Note that the fields parameter takes precedence over this parameter.",
+      "The additional asset attributes to include in each search result. The `fields` parameter takes precedence over this parameter. `image_metadata`, `image_analysis`, and `metadata` require a Tier 2 search plan.\n",
     ),
   },
 ).describe("Common parameters for resource search operations.");

package/src/tool-names.ts

@@ -78,7 +78,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "search-assets",
-    "description": "Provides a powerful query interface to filter and retrieve assets and their details\n\nReturns a list of resources matching the specified search criteria.\n\nUses Lucene-like query language to search by descriptive attributes (public_id, filename, folder, tags, context), file details (resource_type, format, bytes, width, height), embedded data (image_metadata), and analyzed data (face_count, colors, quality_score). Supports aggregate counts and complex Boolean expressions.\n\nExamples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics\n"
+    "description": "Provides a powerful query interface to filter and retrieve assets and their details\n\nReturns a list of resources matching the specified search criteria.\n\nUses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference.\n\n## Expression syntax\n\n- **Match**: `field:value` (token match) or `field=value` (exact match). Examples: `tags:shirt`, `tags=cotton`.\n- **Comparisons**: `>`, `<`, `>=`, `<=` for numbers and dates. Example: `bytes>10000000`.\n- **Ranges**: `field:[from TO to]` inclusive, `field:{from TO to}` exclusive. Example: `width:{200 TO 1028}`.\n- **Booleans**: `AND`, `OR`, `NOT` (uppercase), or `+` (must), `-` (must not). `NOT` must appear between clauses — a bare leading `NOT` is a parse error; use `-field:value` to negate the first clause. Group with parentheses: `(shirt OR pants) AND clothes`.\n- **Wildcards**: trailing `*` only, for prefix match (`public_id:shoes_*`, `format:jp*`, `tags:shirt*`). Not supported on `folder`, `asset_folder`, `resource_type`, or `type`. Leading `*`, middle `*`, `?`, and bare `*` (`folder:*`, `context.alt:*`) are all parse errors — wildcards cannot be used as a \"field is present\" probe.\n- **Tokenized vs exact fields**: `tags`, `filename`, `display_name`, `context.<key>`, and `metadata.<id>` match on tokens split by whitespace and punctuation — `tags:analysis` matches the tag `full-analysis`. `public_id`, `folder`, `asset_folder`, and `format` match the whole value — `public_id:dog` will not match `dog_pldcwy`; use `public_id=\"dog_pldcwy\"` (exact) or `public_id:dog*` (prefix). These exact-match fields still accept a trailing `*` for prefix match (except `folder` / `asset_folder`, where wildcards are ignored).\n- **Dates**: ISO-8601 in quotes (`uploaded_at>\"2024-01-15\"`) or relative shorthand `Nh`, `Nd`, `Nw`, `Nm`, `Ny` (`uploaded_at>1d`, `created_at:[4w TO 1w]`). Send raw `<`/`>`, never HTML-escaped.\n- **Quoting**: wrap any value containing a space, colon, or other reserved character (`! ( ) { } [ ] ^ ~ ?  \\ = & < > |`) in double quotes, or escape each character with `\\`. Examples: `tags:\"service:mantels\"`, `aspect_ratio:\"16:9\"`, `folder:\"My Folder\"`.\n\n## Common mistakes\n\n- Use `folder:` or `asset_folder:` (singular); `folders:`, `asset_folder_id:`, and other invented variants are not valid fields. Pass the exact folder name — wildcards do not apply here.\n- There is no \"has any value\" / presence probe. `folder:*`, `metadata.alt:*`, `context.key:*`, `tags:*`, and `-tags:*` are all parse errors. See *\"Which assets have any value for `metadata.<id>`?\"* under **Common tasks** for workarounds.\n- `NOT foo AND bar` is a parse error. Write it as `bar AND NOT foo` or `-foo AND bar`, and keep every `NOT` between two clauses (`a AND NOT b AND NOT c` is fine; `NOT b AND NOT c …` is not).\n- `public_id:dog` will not match `dog_pldcwy`. Use `public_id=\"dog_pldcwy\"` (exact) or `public_id:dog*` (prefix).\n- `tags=service:mantels` fails because the unquoted colon is parsed as a field separator. Use `tags=\"service:mantels\"` or `tags=service\\:mantels`.\n- Do not HTML-escape operators. Send `uploaded_at<1h`, not `uploaded_at&lt;1h`.\n- Do not leave an operand empty (e.g. `tags: AND -tags:foo`). Omit the empty clause entirely.\n\n## Tips\n\n- Set `max_results: 0` to return only `total_count` and `aggregations` without any resource payload — useful for counts and aggregation-only queries.\n- `total_count` is always present in the response; prefer it over running an aggregation just to get a count.\n- `aggregate` (both simple and range variants) and the `metadata`, `image_metadata`, `image_analysis` values of `with_field` require a Tier 2 search plan.\n- Range aggregations require each range to include a `key` label (1–20 chars, `[a-zA-Z0-9_-]+`) and at least one of `from` / `to`.\n\n## Common tasks\n\n- **Count matching assets** — put the filter in `expression` with `max_results: 0` and read `total_count` from the response. Works on every tier; no `aggregate` needed.\n- **Preview one matching asset** — set `max_results: 1`; add `with_field: [\"tags\", \"context\"]` (or `metadata`, Tier 2) to inspect values. Prefer this over fetching and scanning a full page.\n- **Distribution of values for a field** — Tier 2: `aggregate: [format|resource_type|type]` for enum counts, or range aggregations on `bytes`, `image_pixels`, `video_pixels`, or `duration`. Tier 1 fallback: run N small queries with `max_results: 0`, one per candidate value, and read `total_count` from each.\n- **\"Which assets have any value for `metadata.<id>`?\"** — not expressible directly (`metadata.X:*` is a parse error; there is no presence probe). Workarounds: (a) if the field has a known value set, enumerate — `metadata.region:(apac OR emea OR amer)`; (b) query broadly with `with_field: [\"metadata\"]` (Tier 2) and filter client-side for entries where the field is set; (c) at ingest time, attach a sentinel tag whenever the field is set, then search by that tag.\n- **Newest / largest N** — keep the filter in `expression` and sort explicitly: `sort_by: [{uploaded_at: \"desc\"}]` with `max_results: 10`.\n- **Filter by folder** — both `asset_folder:\"parent/child\"` and `folder:\"parent/child\"` match an exact folder path; there is no wildcard or \"contains\". To query across multiple folders, enumerate: `asset_folder:(\"campaigns/2024\" OR \"campaigns/2025\")`.\n- **Filter by metadata when you only know the label** — first call `list-metadata-fields` to resolve the label to an `external_id`, then query `metadata.<external_id>:value`.\n- **Multiple independent filters in one turn** — prefer one `expression` with `OR` / parentheses over firing many parallel calls: `metadata.region:apac OR metadata.region:emea` in a single request is faster and more reliable than two parallel requests.\n\n## Examples\n\n- `tags:shirt AND uploaded_at>1d`\n- `resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)`\n- `folder:products AND context.category:electronics`\n- `tags:\"service:mantels\" AND -tags:discontinued`\n"
   },
   {
     "name": "visual-search-assets",

package/src/types/bigint.ts

@@ -25,23 +25,24 @@ export function bigint(): z.ZodType<bigint | string> {
 }
 
 export function bigintOptional(): z.ZodType<bigint | string | undefined> {
-  return z.union([
-    z.bigint().transform((v) => String(v)),
-    z.string().transform((v, ctx) => {
-      try {
-        return BigInt(v);
-      } catch {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Invalid bigint value",
-        });
-        return z.NEVER;
-      }
-    }),
-    z.number().transform((v) => BigInt(Math.trunc(v))),
-    z.undefined(),
-    z.null().transform(() => undefined),
-  ]);
+  return z
+    .union([
+      z.bigint().transform((v) => String(v)),
+      z.string().transform((v, ctx) => {
+        try {
+          return BigInt(v);
+        } catch {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Invalid bigint value",
+          });
+          return z.NEVER;
+        }
+      }),
+      z.number().transform((v) => BigInt(Math.trunc(v))),
+      z.null().transform(() => undefined),
+    ])
+    .optional();
 }
 
 export function bigintNullable(): z.ZodType<bigint | string | null> {