@cloudinary/asset-management-mcp 0.9.0-rc.0 → 0.9.1

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

@@ -6,7 +6,7 @@
 import * as z from "zod";
 import { assetsGetResourceByAssetId } from "../../funcs/assetsGetResourceByAssetId.js";
 import { formatResult, ToolDefinition } from "../tools.js";
-import { ASSET_DETAILS_RESOURCE_URI } from "../widgets/asset-details-widget.js";
+import { appUri } from "../apps/uri.js";
 
 const args = {
   asset_id: z.string().describe(
@@ -61,7 +61,7 @@ Returns the details of a single resource specified by its asset ID.`,
     "readOnlyHint": true,
   },
   _meta: {
-    ui: { resourceUri: ASSET_DETAILS_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-details", "get-asset-details") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -5,39 +5,43 @@
 
 import * as z from "zod";
 import { assetsListImages } from "../../funcs/assetsListImages.js";
-import { Direction$zodSchema } from "../../models/direction.js";
-import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
-import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
-import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
+import { DeliveryTypeAll$zodSchema } from "../../models/deliverytypeall.js";
+import { DirectionEnum$zodSchema } from "../../models/directionenum.js";
+import { Fields$zodSchema } from "../../models/fields.js";
+import { appUri } from "../apps/uri.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional().describe(
-    `The storage type of the assets. Necessary for prefix filtering.`,
+  type: DeliveryTypeAll$zodSchema.optional().describe(
+    `The delivery type to filter by. When omitted, returns assets of all delivery types.`,
   ),
   prefix: z.string().describe(
-    "Find resources with a public ID prefix. Requires the `type` parameter.",
+    "A public_id prefix. When specified, all assets with that prefix are returned.",
   ).optional(),
   public_ids: z.array(z.string()).describe("An array of public IDs to return.")
     .optional(),
-  tags: z.boolean().describe(
-    "Whether to include the list of tag names assigned to each asset. Default: false",
-  ).optional(),
+  tags: z.boolean().default(false).describe(
+    "Whether to include the list of tag names assigned to each asset. Default is false.",
+  ),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
+  direction: DirectionEnum$zodSchema.optional().describe(
+    `The sort direction for the results. Default is "desc".`,
+  ),
   start_at: z.iso.datetime({ offset: true }).describe(
-    "Retrieve resources uploaded after this timestamp.",
+    "An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
-  fields: z.array(FieldsSpec$zodSchema).optional(),
+  fields: Fields$zodSchema.optional().describe(
+    `Additional fields to include in the response. The fields public_id and asset_id are always included.`,
+  ),
 };
 
 export const tool$assetsListImages: ToolDefinition<typeof args> = {
   name: "list-images",
   description: `Get image assets
 
-Retrieves a list of image assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.
+Retrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
 `,
   scopes: ["librarian"],
   annotations: {
@@ -48,7 +52,7 @@ Retrieves a list of image assets. Results can be filtered by various criteria li
     "readOnlyHint": true,
   },
   _meta: {
-    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-gallery", "list-images") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -5,39 +5,43 @@
 
 import * as z from "zod";
 import { assetsListRawFiles } from "../../funcs/assetsListRawFiles.js";
-import { Direction$zodSchema } from "../../models/direction.js";
-import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
-import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
+import { DeliveryTypeAll$zodSchema } from "../../models/deliverytypeall.js";
+import { DirectionEnum$zodSchema } from "../../models/directionenum.js";
+import { Fields$zodSchema } from "../../models/fields.js";
 import { formatResult, ToolDefinition } from "../tools.js";
-import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
+import { appUri } from "../apps/uri.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional().describe(
-    `The delivery type. Necessary for prefix filtering.`,
+  type: DeliveryTypeAll$zodSchema.optional().describe(
+    `The delivery type to filter by. When omitted, returns assets of all delivery types.`,
   ),
   prefix: z.string().describe(
-    "A public_id prefix. When specified, all assets with that prefix are returned. When using this, the `type` parameter must also be specified.",
+    "A public_id prefix. When specified, all assets with that prefix are returned.",
   ).optional(),
   public_ids: z.array(z.string()).describe("An array of public IDs to return.")
     .optional(),
-  tags: z.boolean().describe(
-    "Whether to include the list of tag names assigned to each asset. Default: false",
-  ).optional(),
+  tags: z.boolean().default(false).describe(
+    "Whether to include the list of tag names assigned to each asset. Default is false.",
+  ),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
+  direction: DirectionEnum$zodSchema.optional().describe(
+    `The sort direction for the results. Default is "desc".`,
+  ),
   start_at: z.iso.datetime({ offset: true }).describe(
-    "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
+    "An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
-  fields: z.array(FieldsSpec$zodSchema).optional(),
+  fields: Fields$zodSchema.optional().describe(
+    `Additional fields to include in the response. The fields public_id and asset_id are always included.`,
+  ),
 };
 
 export const tool$assetsListRawFiles: ToolDefinition<typeof args> = {
   name: "list-files",
   description: `Get raw assets
 
-Retrieves a list of raw assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.
+Retrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
 `,
   scopes: ["librarian"],
   annotations: {
@@ -48,7 +52,7 @@ Retrieves a list of raw assets. Results can be filtered by various criteria like
     "readOnlyHint": true,
   },
   _meta: {
-    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-gallery", "list-files") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -9,9 +9,11 @@ import { ResourceType$zodSchema } from "../../models/resourcetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: ResourceType$zodSchema.describe(`The type of resource.`),
+  resource_type: ResourceType$zodSchema.describe(
+    `The type of resource (image, video, or raw).`,
+  ),
   prefix: z.string().describe(
-    "The prefix to use if you want to limit the returned tags to those that start with the specified prefix.",
+    "Limit the returned tags to those that start with the specified prefix.",
   ).optional(),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")

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

@@ -5,39 +5,43 @@
 
 import * as z from "zod";
 import { assetsListVideos } from "../../funcs/assetsListVideos.js";
-import { Direction$zodSchema } from "../../models/direction.js";
-import { FieldsSpec$zodSchema } from "../../models/fieldsspec.js";
-import { ListStorageType$zodSchema } from "../../models/liststoragetype.js";
+import { DeliveryTypeAll$zodSchema } from "../../models/deliverytypeall.js";
+import { DirectionEnum$zodSchema } from "../../models/directionenum.js";
+import { Fields$zodSchema } from "../../models/fields.js";
 import { formatResult, ToolDefinition } from "../tools.js";
-import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
+import { appUri } from "../apps/uri.js";
 
 const args = {
-  type: ListStorageType$zodSchema.optional().describe(
-    `The delivery type. Necessary for prefix filtering.`,
+  type: DeliveryTypeAll$zodSchema.optional().describe(
+    `The delivery type to filter by. When omitted, returns assets of all delivery types.`,
   ),
   prefix: z.string().describe(
-    "A public_id prefix. When specified, all assets with that prefix are returned. When using this, the `type` parameter must also be specified.",
+    "A public_id prefix. When specified, all assets with that prefix are returned.",
   ).optional(),
   public_ids: z.array(z.string()).describe("An array of public IDs to return.")
     .optional(),
-  tags: z.boolean().describe(
-    "Whether to include the list of tag names assigned to each asset. Default: false",
-  ).optional(),
+  tags: z.boolean().default(false).describe(
+    "Whether to include the list of tag names assigned to each asset. Default is false.",
+  ),
   next_cursor: z.string().describe("Cursor for pagination.").optional(),
   max_results: z.int().describe("Maximum number of results to return (1-500).")
     .optional(),
-  direction: Direction$zodSchema.optional().describe(`Sort direction.`),
+  direction: DirectionEnum$zodSchema.optional().describe(
+    `The sort direction for the results. Default is "desc".`,
+  ),
   start_at: z.iso.datetime({ offset: true }).describe(
-    "An ISO-8601 formatted timestamp. When specified, assets created since that timestamp are returned.  Supported only if neither `prefix` nor `public_ids` were passed.",
+    "An ISO-8601 formatted timestamp. When specified, returns resources created since that timestamp. Supported only if neither `prefix` nor `public_ids` were passed.",
   ).optional(),
-  fields: z.array(FieldsSpec$zodSchema).optional(),
+  fields: Fields$zodSchema.optional().describe(
+    `Additional fields to include in the response. The fields public_id and asset_id are always included.`,
+  ),
 };
 
 export const tool$assetsListVideos: ToolDefinition<typeof args> = {
   name: "list-videos",
   description: `Get video assets
 
-Retrieves a list of video assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.
+Retrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.
 `,
   scopes: ["librarian"],
   annotations: {
@@ -48,7 +52,7 @@ Retrieves a list of video assets. Results can be filtered by various criteria li
     "readOnlyHint": true,
   },
   _meta: {
-    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-gallery", "list-videos") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -9,8 +9,12 @@ import { ResourceType$zodSchema } from "../../models/resourcetype.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  resource_type: ResourceType$zodSchema.describe(`The type of resource.`),
-  RequestBody: RenameAssetRequestBody$zodSchema,
+  resource_type: ResourceType$zodSchema.describe(
+    `The type of resource (image, video, or raw).`,
+  ),
+  RequestBody: RenameAssetRequestBody$zodSchema.describe(
+    `The rename request parameters.`,
+  ),
 };
 
 export const tool$assetsRenameAsset: ToolDefinition<typeof args> = {

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

@@ -12,7 +12,9 @@ const args = {
   asset_id: z.string().describe(
     "The asset ID of the resource. Must be a 32-character hexadecimal string.",
   ),
-  ResourceUpdateRequest: ResourceUpdateRequest$zodSchema,
+  ResourceUpdateRequest: ResourceUpdateRequest$zodSchema.describe(
+    `The asset attributes to update.`,
+  ),
 };
 
 export const tool$assetsUpdateResourceByAssetId: ToolDefinition<typeof args> = {
@@ -20,7 +22,7 @@ export const tool$assetsUpdateResourceByAssetId: ToolDefinition<typeof args> = {
   description:
     `Updates an existing asset's metadata, tags, and other attributes using its asset ID
 
-Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. Note that you can also update many attributes of an existing asset using the explicit method, which is not rate-limited.
+Updates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. Note that you can also update attributes of an existing asset using the explicit API endpoint.
 `,
   scopes: ["librarian"],
   annotations: {

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

@@ -8,7 +8,9 @@ import { foldersCreateFolder } from "../../funcs/foldersCreateFolder.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  folder: z.string(),
+  folder: z.string().describe(
+    "The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.",
+  ),
 };
 
 export const tool$foldersCreateFolder: ToolDefinition<typeof args> = {

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

@@ -8,7 +8,9 @@ import { foldersDestroyFolder } from "../../funcs/foldersDestroyFolder.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  folder: z.string(),
+  folder: z.string().describe(
+    "The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.",
+  ),
 };
 
 export const tool$foldersDestroyFolder: ToolDefinition<typeof args> = {

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

@@ -5,15 +5,15 @@
 
 import * as z from "zod";
 import { foldersSearchFolders } from "../../funcs/foldersSearchFolders.js";
-import { ExpressionUnion$zodSchema } from "../../models/searchfoldersop.js";
+import { DirectionEnum$zodSchema } from "../../models/directionenum.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  expression: ExpressionUnion$zodSchema.optional().describe(
-    `The (Lucene-like) string expression specifying the search query, or an object for advanced queries. If not passed, returns all folders (up to max_results).`,
-  ),
-  sort_by: z.array(z.string()).describe(
-    "An array of key-value pairs for sorting. Each value is a key and direction (asc/desc).",
+  expression: z.string().describe(
+    "The (Lucene-like) string expression specifying the search query. If not passed, returns all folders (up to max_results).",
+  ).optional(),
+  sort_by: z.array(z.record(z.string(), DirectionEnum$zodSchema)).describe(
+    "Sort order for the results. Each item maps a field name to a direction.",
   ).optional(),
   max_results: z.int().default(50).describe(
     "Maximum number of folders to return (max 500, default 50).",

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

@@ -5,12 +5,16 @@
 
 import * as z from "zod";
 import { foldersUpdateFolder } from "../../funcs/foldersUpdateFolder.js";
-import { UpdateFolderRequestBody$zodSchema } from "../../models/updatefolderop.js";
+import { MoveFolderRequest$zodSchema } from "../../models/movefolderrequest.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  folder: z.string(),
-  RequestBody: UpdateFolderRequestBody$zodSchema,
+  folder: z.string().describe(
+    "The full path of the folder, including any nested folders. Must not be empty, and must not contain double slashes or leading/trailing slashes.",
+  ),
+  move_folder_request: MoveFolderRequest$zodSchema.describe(
+    `The new folder path.`,
+  ),
 };
 
 export const tool$foldersUpdateFolder: ToolDefinition<typeof args> = {
@@ -32,7 +36,7 @@ Renames or moves an entire folder (along with all assets it contains) to a new l
     const [result] = await foldersUpdateFolder(
       client,
       args.folder,
-      args.RequestBody,
+      args.move_folder_request,
       { fetchOptions: { signal: ctx.signal } },
     ).$inspect();
 

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

@@ -6,10 +6,10 @@
 import { searchSearchAssets } from "../../funcs/searchSearchAssets.js";
 import { SearchParameters$zodSchema } from "../../models/searchparameters.js";
 import { formatResult, ToolDefinition } from "../tools.js";
-import { ASSET_GALLERY_RESOURCE_URI } from "../widgets/asset-gallery-widget.js";
+import { appUri } from "../apps/uri.js";
 
 const args = {
-  request: SearchParameters$zodSchema,
+  request: SearchParameters$zodSchema.describe(`The search query parameters.`),
 };
 
 export const tool$searchSearchAssets: ToolDefinition<typeof args> = {
@@ -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: {
@@ -32,7 +76,7 @@ Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, fold
     "readOnlyHint": true,
   },
   _meta: {
-    ui: { resourceUri: ASSET_GALLERY_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-gallery", "search-assets") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -8,7 +8,9 @@ import { VisualSearchParametersUnion$zodSchema } from "../../models/visualsearch
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  request: VisualSearchParametersUnion$zodSchema,
+  request: VisualSearchParametersUnion$zodSchema.describe(
+    `The visual search parameters.`,
+  ),
 };
 
 export const tool$searchVisualSearchAssets: ToolDefinition<typeof args> = {
@@ -18,7 +20,7 @@ export const tool$searchVisualSearchAssets: ToolDefinition<typeof args> = {
 
 Returns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways:
 - Provide a URL of an image
-- Specify the public ID or asset ID of an existing image
+- Specify the asset ID of an existing image
 - Provide a textual description
 `,
   scopes: ["librarian"],

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

@@ -6,19 +6,16 @@
 import { uploadUpload } from "../../funcs/uploadUpload.js";
 import { UploadRequest$zodSchema } from "../../models/uploadrequest.js";
 import { UploadResourceType$zodSchema } from "../../models/uploadresourcetype.js";
-import { ASSET_UPLOAD_RESOURCE_URI } from "../widgets/asset-upload-widget.js";
+import { appUri } from "../apps/uri.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
   resource_type: UploadResourceType$zodSchema.default("auto").describe(
-    `The type of resource to upload:
-- "image" for uploading strictly images
-- "video" for uploading strictly videos
-- "raw" for uploading non-media files
-- "auto" for allowing Cloudinary to automatically detect the type of the uploaded file
-`,
+    `The type of resource (image, video, raw, or auto).`,
+  ),
+  upload_request: UploadRequest$zodSchema.describe(
+    `The file to upload and associated parameters.`,
   ),
-  upload_request: UploadRequest$zodSchema,
 };
 
 export const tool$uploadUpload: ToolDefinition<typeof args> = {
@@ -50,7 +47,7 @@ Transform media files using transformation syntax in delivery URLs, which create
     "readOnlyHint": false,
   },
   _meta: {
-    ui: { resourceUri: ASSET_UPLOAD_RESOURCE_URI },
+    ui: { resourceUri: appUri("asset-upload", "upload-asset") },
   },
   args,
   tool: async (client, args, ctx) => {

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

@@ -8,7 +8,9 @@ import { usageGetUsage } from "../../funcs/usageGetUsage.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 const args = {
-  date: z.string().date().optional(),
+  date: z.string().date().describe(
+    "The date for which to retrieve usage details (YYYY-MM-DD). If not specified, returns the current usage.",
+  ).optional(),
 };
 
 export const tool$usageGetUsage: ToolDefinition<typeof args> = {

package/src/mcp-server/tools.ts

@@ -17,6 +17,8 @@ import {
 import * as z from "zod";
 import { CloudinaryAssetMgmtCore } from "../core.js";
 import { ServerRegion$zodSchema } from "../lib/config.js";
+import { enabledAppUriPrefixes, type McpApp } from "./apps/config.js";
+import { shouldForwardToolMeta } from "./apps/tool-hooks.js";
 import { ConsoleLogger } from "./console-logger.js";
 import { MCPServerFlags } from "./flags.js";
 import { MCPScope, mcpScopes } from "./scopes.js";
@@ -139,11 +141,13 @@ export function createRegisterTool(
   allowedTools?: Set<string>,
   dynamic?: boolean,
   annotationFilter?: MCPToolAnnotationFilter,
+  mcpApps?: McpApp[],
 ): [
   <A extends ZodRawShapeCompat | undefined>(tool: ToolDefinition<A>) => void,
   Array<{ name: string; description: string }>,
   Map<string, ToolDefinition<ZodRawShapeCompat | undefined>>,
 ] {
+  const enabledUris = enabledAppUriPrefixes(mcpApps ?? []);
   const tools: Array<{ name: string; description: string }> = [];
   const toolMap = new Map<
     string,
@@ -214,7 +218,9 @@ export function createRegisterTool(
           description: tool.description,
           inputSchema: tool.args,
           annotations: tool.annotations,
-          ...(tool._meta ? { _meta: tool._meta } : {}),
+          ...(shouldForwardToolMeta(tool._meta, enabledUris)
+            ? { _meta: tool._meta }
+            : {}),
         },
         async (args, ctx) => {
           return tool.tool(getSDK(), args, ctx);
@@ -226,7 +232,9 @@ export function createRegisterTool(
         {
           description: tool.description,
           annotations: tool.annotations,
-          ...(tool._meta ? { _meta: tool._meta } : {}),
+          ...(shouldForwardToolMeta(tool._meta, enabledUris)
+            ? { _meta: tool._meta }
+            : {}),
         },
         async (ctx) => {
           return tool.tool(getSDK(), ctx);
@@ -364,16 +372,16 @@ export function registerDynamicTools(
 
     return { content: [{ type: "text", text: parts.join("\n\n") }] };
   });
-  logger.debug("Registered dynamic meta-tool", { name: "describe_tool" });
+  logger.debug("Registered dynamic meta-tool", { name: "describe_tool_input" });
 
   // 3. execute_tool
   server.registerTool("execute_tool", {
     description:
-      "Execute a tool by name with the provided input parameters. If executing a given tool for the first time, it is recommended to call describe_tool_input first to understand the expected input schema.",
+      "Execute a tool by name with its arguments. If executing a given tool for the first time, it is recommended to call describe_tool_input first to understand the expected `arguments` shape.",
     inputSchema: {
-      tool_name: z.string().describe("The name of the tool to execute"),
-      input: z.record(z.string(), z.unknown()).optional().describe(
-        "Input parameters for the tool as a JSON object",
+      name: z.string().describe("The name of the tool to execute"),
+      arguments: z.looseObject({}).optional().describe(
+        "Arguments for the target tool as a JSON object, matching the schema returned by describe_tool_input.",
       ),
     },
     annotations: {
@@ -384,17 +392,17 @@ export function registerDynamicTools(
       openWorldHint: true,
     },
   }, async (args, ctx) => {
-    const def = toolMap.get(args.tool_name);
+    const def = toolMap.get(args.name);
     if (!def) {
       return {
-        content: [{ type: "text", text: `Unknown tool: ${args.tool_name}` }],
+        content: [{ type: "text", text: `Unknown tool: ${args.name}` }],
         isError: true,
       };
     }
 
     let validatedInput: Record<string, unknown> = {};
     if (def.args) {
-      const vres = z.object(def.args).safeParse(args.input ?? {});
+      const vres = z.object(def.args).safeParse(args.arguments ?? {});
       if (vres.success) {
         validatedInput = vres.data;
       } else {
@@ -404,7 +412,7 @@ export function registerDynamicTools(
           content: [{
             type: "text",
             text:
-              `Invalid input for tool ${args.tool_name}:\n<issues>\n${issues}\n</issues>`,
+              `Invalid input for tool ${args.name}:\n<issues>\n${issues}\n</issues>`,
           }],
           isError: true,
         };
@@ -422,7 +430,7 @@ export function registerDynamicTools(
       return {
         content: [{
           type: "text",
-          text: `Error executing tool ${args.tool_name}: ${message}`,
+          text: `Error executing tool ${args.name}: ${message}`,
         }],
         isError: true,
       };