@kolbo/mcp 1.53.1 → 1.55.0

package/src/tools/media.js

@@ -5,16 +5,70 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { resolveToBuffer } = require('./_shared');
+const { resolveToBuffer, DEFAULT_MAX_FILE_MB, compactList } = require('./_shared');
 const { UI, uiResult, appsEnabled } = require('../apps');
 
+// How many tiles the media grid renders. A rendering limit only — the text
+// payload always carries the full page, and `total` reports the real library
+// count, so a capped grid can never be mistaken for "that's everything".
+const GRID_CAP = 24;
+
+async function mintUploadTicket(client) {
+  const ticket = await client.post('/v1/media/upload-ticket', {});
+  if (!ticket || !ticket.token) throw new Error('Could not create an upload ticket — try again.');
+  return ticket;
+}
+
+// Shape a /v1/media/upload-ticket response for a TEXT consumer (an agent that
+// will POST the file itself). The widget path needs different keys (`expires_at`
+// as an absolute ms timestamp for the countdown), so it builds its own payload.
+//
+// This carries the full recipe, not a pointer to it: both callers are agents
+// holding a token they must use immediately, and telling one of them to go call
+// another tool to learn the POST shape would spend the round trip this whole
+// path exists to remove.
+function uploadTicketPayload(ticket) {
+  return {
+    upload_url: ticket.upload_url,
+    token: ticket.token,
+    expires_in_seconds: ticket.expires_in,
+    max_file_mb: ticket.max_file_mb || DEFAULT_MAX_FILE_MB,
+    accepted: ticket.accepted,
+    how_to_upload: {
+      example: 'curl -X POST "<upload_url>" -H "Authorization: Bearer <token>" -F "file=@/absolute/path/to/file.mp3"',
+      optional_fields: ['project_id', 'description'],
+      response: 'JSON — the stable CDN URL is at media.url. One POST per file; reuse the ticket for a batch.',
+      // Git Bash hands curl a POSIX-style /c/Users/... path that Windows curl
+      // cannot open (exit 26). Real trap — it cost a round trip to find.
+      windows_note: 'Give curl a native path (C:/Users/...) — a Git Bash /c/Users/... path fails to open.',
+    },
+    // The one thing the server cannot detect: a caller with no shell that got
+    // here anyway. Without this it is left holding a token it can never use.
+    if_you_cannot_run_shell_or_http: 'Discard this ticket and call `media_upload_widget` instead so the user can pick the file.',
+  };
+}
+
 function registerMediaTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
 
+  // `opts.apps` is set only by kolbo-api's per-request server (see createServer
+  // in ../index.js), which makes it a TRANSPORT signal — deliberately not
+  // `appsEnabled()`, which also returns true for stdio hosts that advertise UI.
+  // Transport is what decides whether a local path can resolve at all, so state
+  // it in the descriptions rather than making the model infer it. What the
+  // server still cannot know is whether the CALLER has a shell (one connector
+  // serves both claude.ai and Claude Code), hence the fallback hint in the
+  // ticket payload.
+  const isRemoteConnector = options.apps === true;
+
+  const ticketRouting = isRemoteConnector
+    ? 'You are reached over a REMOTE connector: this server cannot read the caller\'s disk, so `upload_media` with a local path will always fail here — do not try it. If you can run shell commands or issue HTTP requests yourself, this tool is the right path. If you cannot (claude.ai web/mobile), ignore this tool and call `media_upload_widget` so the user picks the file.'
+    : 'You are a LOCAL (stdio) install: server and client share a filesystem, so for an ordinary local file prefer `upload_media` with the absolute path — one call, no ticket needed. Use this tool only when you specifically want to stream files up yourself (large batches, CI, an external uploader).';
+
   // ─── media_upload_widget ───────────────────────────────────
   server.tool(
     'media_upload_widget',
-    'Open an interactive file-upload card in the chat so the user can upload LOCAL files (images, videos, audio, documents) into their Kolbo media library. USE THIS IMMEDIATELY whenever a claude.ai (browser/mobile) user wants to use a local file, or references a file they attached to the chat — remote MCP tools CANNOT read chat attachments, so the user must re-upload through this widget; do not ask them to re-attach the file in chat. Each uploaded file gets a stable Kolbo CDN URL that arrives in a follow-up user message — then pass those URLs to generation tools (generate_image_edit, generate_video_from_image, generate_lipsync, transcribe_audio, visual DNA, etc.). On Claude Desktop / Claude Code with filesystem access, prefer `upload_media` with the local path instead.',
+    'Open an interactive file-upload card in the chat so the user can upload LOCAL files (images, videos, audio, documents) into their Kolbo media library. USE THIS IMMEDIATELY whenever a claude.ai (browser/mobile) user wants to use a local file, or references a file they attached to the chat — remote MCP tools CANNOT read chat attachments, so the user must re-upload through this widget; do not ask them to re-attach the file in chat. Each uploaded file gets a stable Kolbo CDN URL that arrives in a follow-up user message — then pass those URLs to generation tools (generate_image_edit, generate_video_from_image, generate_lipsync, transcribe_audio, visual DNA, etc.). ROUTING depends on where the SERVER runs, not on which client you are: `upload_media` with a local path only works on a LOCAL (stdio) install, where server and client share a filesystem. Over a remote connector a local path is unreachable however capable the client is — there, if you can run shell commands, call `create_upload_ticket` and POST the file yourself (no user interaction needed); use this widget when you cannot reach the filesystem (claude.ai web/mobile) or when the user should choose the file.',
     {
       purpose: z.string().optional().describe('Short title shown on the card, e.g. "Upload the photo to animate". Helps the user know what to drop.'),
       media_types: z.array(z.enum(['image', 'video', 'audio', 'document'])).optional().describe('Restrict which file kinds the widget accepts. Omit to accept all types.'),
@@ -22,8 +76,7 @@ function registerMediaTools(server, client, options = {}) {
       project_id: z.string().optional().describe('Project ObjectId to file the uploads into (resolve names via `list_projects`).')
     },
     async ({ purpose, media_types, max_files, project_id }) => {
-      const ticket = await client.post('/v1/media/upload-ticket', {});
-      if (!ticket || !ticket.token) throw new Error('Could not create an upload ticket — try again.');
+      const ticket = await mintUploadTicket(client);
 
       const info = {
         status: 'upload_widget_opened',
@@ -41,18 +94,41 @@ function registerMediaTools(server, client, options = {}) {
           expires_at: Date.now() + (ticket.expires_in || 900) * 1000,
           kinds: media_types && media_types.length ? media_types : undefined,
           max_files: Math.min(Math.max(Number(max_files) || 10, 1), 20),
-          max_mb: ticket.max_file_mb || { image: 50, video: 500, audio: 200, document: 50 },
+          max_mb: ticket.max_file_mb || DEFAULT_MAX_FILE_MB,
           ...(project_id ? { project_id } : {}),
         });
       }
 
-      // Text-only host: no iframe to render — steer to upload_media.
+      // Text-only host (Claude Code, Codex CLI, Cursor): no iframe to render —
+      // but these are exactly the hosts that CAN reach a filesystem, so hand
+      // back the ticket already minted instead of dead-ending. Additive fields
+      // only; `status` is unchanged for any existing consumer.
       return {
         content: [{
           type: 'text',
           text: JSON.stringify({
             status: 'widget_unavailable',
-            hint: 'This host cannot render the upload widget. Use the upload_media tool with a URL or absolute local file path instead.'
+            hint: 'This host cannot render the upload card, but it can usually reach the filesystem. Upload the file yourself by POSTing it to upload_url with this ticket — the recipe is below. On a LOCAL stdio install you can also just call upload_media with the absolute path.',
+            ...uploadTicketPayload(ticket),
+          }, null, 2)
+        }]
+      };
+    }
+  );
+
+  // ─── create_upload_ticket ──────────────────────────────────
+  server.tool(
+    'create_upload_ticket',
+    'Get a short-lived ticket for uploading LOCAL files straight into the user\'s Kolbo media library, with NO upload card and no user interaction. ' + ticketRouting + ' Why it exists: when the server cannot read the caller\'s disk, the only other ways in are making the user click an upload card (`media_upload_widget`) or inlining the file as base64 via `upload_media` — base64 is slow and burns context in proportion to file size, so do not use it for anything but a tiny file. Returns `upload_url` + `token`; POST each file as multipart field `file` with header `Authorization: Bearer <token>` and read the CDN URL from `media.url` in the response. One POST per file; the ticket is reusable until it expires. Then pass those URLs to any generation tool (transcribe_audio, generate_image_edit, generate_video_from_image, generate_lipsync, visual DNA, …).',
+    {},
+    async () => {
+      const ticket = await mintUploadTicket(client);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            status: 'upload_ticket_created',
+            ...uploadTicketPayload(ticket),
           }, null, 2)
         }]
       };
@@ -128,7 +204,7 @@ function registerMediaTools(server, client, options = {}) {
     'list_media',
     'Browse the user\'s Kolbo media library — both uploaded files AND AI-generated outputs they have saved. Powerful filtering: scope to a single project (`project_id`), a user folder (`folder_id`), a "section" / category (`category`: ai / uploaded / edited / favorites / training-lab), a media type (`type`: image / video / audio), or generation provenance (`source_type`). Combine filters freely. Use this to discover what the user already has before generating something new, to retrieve a specific past creation, or to list everything in a project for downstream batch work.',
     {
-      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `list_projects` to discover IDs (NOT `app_builder_list_projects` — that is App Builder only). Omit to list across all the user\'s media.'),
+      project_id: z.string().optional().describe('Restrict to a single project (Mongo ObjectId). Use `list_projects` to discover IDs. Omit to list across all the user\'s media.'),
       folder_id: z.string().optional().describe('Restrict to a user folder (Mongo ObjectId). Discover folder IDs via `list_media_folders`. Takes precedence over project_id when both are set.'),
       type: z.enum(['image', 'video', 'audio', 'all']).optional().describe('Filter by media type. Default: all types.'),
       category: z.enum(['ai', 'uploaded', 'edited', 'favorites', 'training-lab', 'all']).optional().describe('Filter by "section" (matches the Kolbo desktop app sidebar): `ai` = AI-generated, `uploaded` = files the user uploaded, `edited` = AI-edited variants, `favorites` = items the user starred, `training-lab` = training-lab assets. Default: all sections.'),
@@ -155,10 +231,25 @@ function registerMediaTools(server, client, options = {}) {
 
       const media = result.media || [];
       const pagination = result.pagination || null;
-      const text = JSON.stringify({ media, pagination }, null, 2);
+      // A default page of 50 items measured 119,847 chars — every row carries a
+      // full metadata object and the original prompt. Keep what identifies and
+      // locates an item; get_media returns one in full.
+      const text = compactList(media, {
+        fields: ['id', 'filename', 'media_type', 'url', 'thumbnail_url', 'size', 'project_id', 'created_at'],
+        cap: 50,
+        total: pagination ? (pagination.total_items != null ? pagination.total_items : pagination.total) : media.length,
+        extra: pagination ? { pagination } : undefined,
+        note: 'Narrow with `type`, `category`, `project_id`, `folder_id`, or `search`; get_media returns one item in full.',
+      });
 
       if (ui()) {
-        const items = media.slice(0, 24).map((m) => ({
+        // The SDK envelope reports `total_items` (see sdk/controller.js listMedia);
+        // reading `total` always came back undefined, so the grid claimed the page
+        // size was the whole library. Accept either, then fall back.
+        const totalItems = pagination
+          ? (pagination.total_items != null ? pagination.total_items : pagination.total)
+          : null;
+        const items = media.slice(0, GRID_CAP).map((m) => ({
           id: m.id,
           title: m.filename,
           subtitle: m.media_type + (m.size ? ' · ' + Math.round(m.size / 1024) + 'KB' : ''),
@@ -171,7 +262,8 @@ function registerMediaTools(server, client, options = {}) {
           widget: 'media-grid',
           title: 'Media Library',
           items,
-          total: pagination && pagination.total != null ? pagination.total : media.length
+          total: totalItems != null ? totalItems : media.length,
+          shown: Math.min(media.length, GRID_CAP)
         });
       }
 
@@ -409,7 +501,7 @@ function registerMediaTools(server, client, options = {}) {
     'Move a media item to a different project. Caller must own the item AND have access to the target project. Items in shared projects from other members cannot be moved by you. Use this when the user says "move this to project X" or wants to reorganize.',
     {
       media_id: z.string().describe('MediaLibraryItem id to move.'),
-      project_id: z.string().describe('Target project id (use `list_projects` to discover ids — NOT `app_builder_list_projects`).')
+      project_id: z.string().describe('Target project id (use `list_projects` to discover ids).')
     },
     async ({ media_id, project_id }) => {
       const result = await client.patch(

package/src/tools/models.js

@@ -271,10 +271,46 @@ function registerModelTools(server, client, options = {}) {
         return parts.length ? `\n   ${parts.join(' | ')}` : '';
       };
 
+      // The FULL catalog with every spec line measured 140,590 chars — past what
+      // hosts accept, on the one discovery tool the skill tells the model to call
+      // when it is unsure. Unfiltered, emit the one-line form (enough to choose a
+      // model); once `type` narrows it, the set is small enough for full specs.
+      const detailed = !!type;
+      // Summaries run to a paragraph each; across the whole catalog that alone
+      // is most of the payload. Unfiltered, one clause is enough to choose by.
+      const brief = (s) => {
+        if (!s) return '';
+        const flat = String(s).replace(/\s+/g, ' ').trim();
+        return flat.length > 130 ? flat.slice(0, 127).trimEnd() + '…' : flat;
+      };
       const formatModel = m =>
-        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${m.summary}` : ''}${formatSpecs(m)}`;
+        `${m.identifier} (${m.name}) - ${m.credit} credits${m.recommended ? ' [RECOMMENDED]' : ''}${m.new_model ? ' [NEW]' : ''}${m.summary ? ` — ${detailed ? m.summary : brief(m.summary)}` : ''}${detailed ? formatSpecs(m) : ''}`;
 
       const sections = [];
+
+      if (!detailed) {
+        // The catalog is ~428 models. Listing all of them is both far past the
+        // text budget AND useless to choose from — so unfiltered, surface the
+        // curated picks and make the model narrow by `type` for the rest. This
+        // matches the connector rule of steering to a CONCRETE model.
+        const picks = result.models.filter(m => m.recommended || m.new_model);
+        if (picks.length) {
+          sections.push(`Recommended & new (${picks.length}):\n${picks.map(formatModel).join('\n')}`);
+        }
+        const text = `Kolbo model catalog — ${result.count} models total.\n\n`
+          + `${sections.join('\n\n')}\n\n`
+          + 'This is the curated shortlist, not the full catalog. To see everything in a '
+          + 'category (with per-model resolutions, durations, aspect ratios and reference-image '
+          + 'caps), re-call with `type`:\n'
+          + '  text_to_img · image_editing · text_to_video · img_to_video · video_to_video ·\n'
+          + '  first_last_frame · elements · lipsync · music_gen · text_to_speech ·\n'
+          + '  text_to_sound · stt · three_d · text\n\n'
+          + 'Use the "identifier" value as the "model" parameter in generate tools. '
+          + 'For raw documents (programmatic cap validation), re-call with format: "json".';
+        if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
+        return { content: [{ type: 'text', text }] };
+      }
+
       if (withSummary.length > 0) {
         sections.push(`Auto-selectable models (${withSummary.length}) — safe to pick based on quality + cost:\n${withSummary.map(formatModel).join('\n')}`);
       }
@@ -282,7 +318,7 @@ function registerModelTools(server, client, options = {}) {
         sections.push(`Named-only models (${withoutSummary.length}) — only use if the user explicitly requests by name:\n${withoutSummary.map(formatModel).join('\n')}`);
       }
 
-      const text = `Available models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`;
+      const text = `Available ${type} models (${result.count}):\n\n${sections.join('\n\n')}\n\nUse the "identifier" value as the "model" parameter in generate tools. For programmatic cap validation, re-call with format: "json".`;
       if (ui()) return uiResult(UI.catalog, text, buildCatalogStructured(result.models, type, !showCatalog));
       return { content: [{ type: 'text', text }] };
     }
@@ -312,9 +348,25 @@ function registerModelTools(server, client, options = {}) {
   // X credits in this app session" instead of estimating from base credits.
   server.tool(
     'get_session_usage',
-    'Fetch real, multiplier-adjusted credit spend for the current Kolbo Code app session. Use when the user asks "how much did I spend?" or before/after a large bulk job so you can quote actual cost (not an estimate from base credits). Returns total + per-tool breakdown + per-model breakdown + a recent list. The caller-session-id is forwarded automatically by the MCP HTTP client.',
+    'Fetch real, multiplier-adjusted credit spend for the current Kolbo Code app session. Use when the user asks "how much did I spend?" or before/after a large bulk job so you can quote actual cost (not an estimate from base credits). Returns total + per-tool breakdown + per-model breakdown + a recent list. The caller-session-id is forwarded automatically by the MCP HTTP client. ONLY works when running under Kolbo Code — on the claude.ai connector and other hosts there is no per-app session to scope to; use check_credits there instead.',
     {},
     async () => {
+      // Session scoping needs KOLBO_CALLER_SESSION_ID, which only the Kolbo Code
+      // parent process sets. The remote connector serves every user from one
+      // process, so it is never present there — calling anyway just returns a 400
+      // telling the user to reconfigure a process they do not control.
+      if (!process.env.KOLBO_CALLER_SESSION_ID) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              unavailable: 'Per-session usage is only tracked when running under Kolbo Code.',
+              reason: 'This host does not scope tool calls to an app session, so there is no session to total.',
+              use_instead: 'check_credits for the current balance, or the Usage page at https://app.kolbo.ai.'
+            })
+          }]
+        };
+      }
       try {
         const r = await client.get('/credit-usage/by-caller-session');
         // The endpoint returns { message, data: { total, count, by_tool, by_model, recent[] } }

package/src/tools/moodboards.js

@@ -75,7 +75,7 @@ function registerMoodboardTools(server, client, options = {}) {
     'Create a moodboard from 1–15 image URLs. The server analyzes the images and synthesizes a reusable master style prompt — then pass the returned moodboard id as `moodboard_id` on generation tools to apply the style. Use Kolbo URLs (generated images or `upload_media` output) or any public image URL. Typical flow: generate/upload reference images → create_moodboard → generate with moodboard_id.',
     {
       name: z.string().describe('Moodboard name (1–100 chars).'),
-      image_urls: z.array(z.string()).min(1).max(15).describe('1–15 public image URLs. For local files, call upload_media first and use the returned URLs.'),
+      image_urls: z.array(z.string()).min(1).max(15).describe('1–15 public image URLs. For local files, get URLs first via the LOCAL FILE route in this tool\'s description.'),
       style_guide: z.string().optional().describe('Optional style notes (max 500 chars) that steer the analysis, e.g. "focus on the color grading, not the subjects".')
     },
     async ({ name, image_urls, style_guide }) => {

package/src/tools/music_library.js

@@ -124,11 +124,38 @@ function registerMusicLibraryTools(server, client, options = {}) {
 
   server.tool(
     'get_music_library_facets',
-    'List SYNCI genres, moods, instruments, BPM, and duration filters.',
-    {},
-    async () => {
+    'List SYNCI genres, moods, instruments, BPM, and duration filters. Returns the most-used values ' +
+    'per facet (ranked by track count); raise `limit` if you need deeper coverage. Any value not ' +
+    'listed still works as a free-text `query` on search_music_library.',
+    {
+      limit: z.number().optional().describe(
+        'How many values to return per facet, ranked by track count. Default: 40. Max: 200.'
+      ),
+    },
+    async ({ limit }) => {
       const result = await client.get('/v1/music-library/facets');
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+
+      // The raw response carries 169 genres and 1000 each of moods/instruments — ~128K
+      // chars, which exceeds what hosts accept, so this tool used to fail outright. The
+      // tail is single-digit-count noise; the head is what anyone actually filters on.
+      const cap = Math.min(Math.max(Number(limit) || 40, 1), 200);
+      const trim = (arr) => (Array.isArray(arr) ? arr.slice(0, cap) : arr);
+      const omitted = (arr) => (Array.isArray(arr) ? Math.max(arr.length - cap, 0) : 0);
+
+      const payload = {
+        ...result,
+        genres: trim(result.genres),
+        moods: trim(result.moods),
+        instruments: trim(result.instruments),
+        _truncated: {
+          genres: omitted(result.genres),
+          moods: omitted(result.moods),
+          instruments: omitted(result.instruments),
+          hint: 'Values beyond these are long-tail. Pass a higher `limit`, or just use `query` on ' +
+            'search_music_library — free text matches values not listed here.',
+        },
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
     },
   );
 

package/src/tools/presets.js

@@ -5,6 +5,7 @@
 
 const { z } = require('zod');
 const { UI, uiResult, appsEnabled } = require('../apps');
+const { compactList } = require('./_shared');
 
 function registerPresetTools(server, client, options = {}) {
   const ui = () => appsEnabled(server, options);
@@ -22,11 +23,15 @@ function registerPresetTools(server, client, options = {}) {
       const result = await client.get(`/v1/presets${qs ? '?' + qs : ''}`);
 
       const presets = result.presets || [];
-      const text = JSON.stringify({
-        presets,
-        count: result.count || 0,
-        ...(result.warning ? { warning: result.warning } : {})
-      }, null, 2);
+      // Full catalog measured 632,919 chars — the single biggest payload in the
+      // tool surface. The model only needs enough to pick a preset_id.
+      const text = compactList(presets, {
+        fields: ['id', 'name', 'category', 'type', 'description'],
+        cap: 60,
+        total: result.count || presets.length,
+        extra: result.warning ? { warning: result.warning } : undefined,
+        note: 'Filter with `type` (image | video | music | text_to_video) to see a focused set.',
+      });
 
       if (ui()) {
         return uiResult(UI.mediaGrid, text, {
@@ -64,22 +69,56 @@ function registerPresetTools(server, client, options = {}) {
     'specific cinematic look; then pass the chosen ids via the `cinematic` arg of generate_image / ' +
     'generate_image_edit — at most one id per dimension. "Auto" is the absence of a selection: omit a ' +
     'dimension (or the whole `cinematic` object) to let the enhancer decide. For an ordinary generation ' +
-    'do not call this at all. Never hardcode ids — dimensions and presets change; always fetch here.',
-    {},
-    async () => {
+    'do not call this at all. Never hardcode ids — dimensions and presets change; always fetch here. ' +
+    'Call with no args for a compact id+name index of every dimension, then pass `dimension` to get the ' +
+    'full descriptions for just the one you are choosing from.',
+    {
+      dimension: z.string().optional().describe(
+        'Return full detail (incl. descriptions) for ONE dimension only — e.g. "lighting", "camera", ' +
+        '"looks". Omit for the compact index of all dimensions.'
+      ),
+    },
+    async ({ dimension }) => {
       const result = await client.get('/v1/cinematic-presets');
       // The public route serves the raw grouped map ({ camera:[...], lens:[...] });
       // the SDK envelope wraps it as { dimensions:{...} }. Accept either shape.
       const dimensions = (result && result.dimensions) || result || {};
-      const text = JSON.stringify({
-        dimensions,
-        available_dimensions: Object.keys(dimensions),
-        _usage_hint: 'Include ONLY the dimensions the user actually wants; pass their ids as the ' +
-          '`cinematic` arg on generate_image / generate_image_edit, e.g. {"camera":"<id>","lighting":"<id>"}. ' +
-          'Every omitted/null dimension is Auto — the enhancer completes the look in the spirit of the ones ' +
-          'you set. Omit the whole object for a non-cinematic generation. Ids are validated per-dimension server-side.'
-      }, null, 2);
-      return { content: [{ type: 'text', text }] };
+      const names = Object.keys(dimensions);
+
+      // The full catalog pretty-printed is ~63K chars — past what hosts accept, so the
+      // tool used to fail outright. thumbnail_url is dead weight on a text surface, and
+      // descriptions are only needed for the dimension actually being chosen from.
+      const slim = (p) => ({ id: p.id, name: p.name });
+      const full = (p) => ({
+        id: p.id,
+        name: p.name,
+        description: p.description,
+        ...(p.bundle ? { bundle: p.bundle } : {}),
+      });
+
+      let payload;
+      if (dimension && dimensions[dimension]) {
+        payload = {
+          dimension,
+          presets: (dimensions[dimension] || []).map(full),
+          available_dimensions: names,
+        };
+      } else {
+        if (dimension) payload = { _note: `Unknown dimension "${dimension}" — showing the index.` };
+        payload = {
+          ...payload,
+          dimensions: Object.fromEntries(names.map((k) => [k, (dimensions[k] || []).map(slim)])),
+          available_dimensions: names,
+          _detail_hint: 'Names only. Call again with `dimension: "<name>"` for descriptions.',
+        };
+      }
+
+      payload._usage_hint = 'Include ONLY the dimensions the user actually wants; pass their ids as the ' +
+        '`cinematic` arg on generate_image / generate_image_edit, e.g. {"camera":"<id>","lighting":"<id>"}. ' +
+        'Every omitted/null dimension is Auto — the enhancer completes the look in the spirit of the ones ' +
+        'you set. Omit the whole object for a non-cinematic generation. Ids are validated per-dimension server-side.';
+
+      return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
     }
   );
 }

package/src/tools/projects.js

@@ -12,7 +12,7 @@ function registerProjectTools(server, client, options = {}) {
   // ─── list_projects ─────────────────────────────────────────
   server.tool(
     'list_projects',
-    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted. NOT the same as `app_builder_list_projects`, which scopes App Builder coding sessions only.',
+    'List the user\'s platform projects (owned + shared with edit/full/owner permission). Use this to resolve a project NAME the user mentioned ("put this in my Acme Campaign project") into the project ObjectId you pass back as `project_id` on generation / chat / upload / move tools. Whenever the user mentions a project by name OR location, you MUST call this first — those tools accept only ObjectIds, not names — and then pass the resolved `project_id` on EVERY subsequent call in the conversation (it is per-call, not sticky; omitting it drops work into the default bucket). Returns id, name, role, and is_default. The project flagged `is_default: true` is the auto-created "API Generations" bucket every SDK generation lands in when project_id is omitted.',
     {},
     async () => {
       const result = await client.get('/v1/projects');

package/src/tools/stock_library.js

@@ -3,6 +3,7 @@
 
 const { z } = require('zod');
 const { UI, uiResult, appsEnabled } = require('../apps');
+const { compactList } = require('./_shared');
 
 // Compact one-line render of a normalized stock asset.
 function assetLine(a) {
@@ -62,7 +63,15 @@ function registerStockLibraryTools(server, client, options = {}) {
       const assets = result.assets || [];
       if (!assets.length) return { content: [{ type: 'text', text: 'No assets found. Try a broader query, a different source/mediaType, or call get_stock_sources.' }] };
       const head = `Found ${assets.length} asset${assets.length === 1 ? '' : 's'}${result.total ? ` (≈${result.total} total)` : ''}${result.hasMore ? ' — more available (increment page)' : ''}:`;
-      const text = `${head}\n\n${assets.map(assetLine).join('\n\n')}\n\nUse [source:sourceId] with get_stock_asset for full variants, or import_stock_asset to copy it into the media library.`;
+      // A wide `source=all` search interleaves providers and overran the text
+      // budget at ~27K. Cap the rendered rows; `page` still reaches the rest.
+      const ASSET_CAP = 30;
+      const shownAssets = assets.slice(0, ASSET_CAP);
+      const moreAssets = assets.length - shownAssets.length;
+      const moreHint = moreAssets > 0
+        ? `\n\n…and ${moreAssets} more on this page — narrow with \`source\` / \`mediaType\`, or use \`page\`.`
+        : '';
+      const text = `${head}\n\n${shownAssets.map(assetLine).join('\n\n')}${moreHint}\n\nUse [source:sourceId] with get_stock_asset for full variants, or import_stock_asset to copy it into the media library.`;
 
       if (ui()) {
         const items = assets.slice(0, 24).map((a) => {
@@ -113,7 +122,14 @@ function registerStockLibraryTools(server, client, options = {}) {
     async (args) => {
       const q = buildQuery(args);
       const result = await client.get(`/v1/stock/categories${q ? '?' + q : ''}`);
-      return { content: [{ type: 'text', text: JSON.stringify({ count: result.count, categories: result.categories }, null, 2) }] };
+      // Full category list measured 257,817 chars (Kolbo SFX alone has 77 groups
+      // + 623 sub-filters). The model needs the label and the param to pass back.
+      return { content: [{ type: 'text', text: compactList(result.categories, {
+        fields: ['key', 'label', 'mediaType', 'source', 'group', 'paramType', 'providerParam'],
+        cap: 120,
+        total: result.count,
+        note: 'Narrow with `source` and `mediaType` to see a focused set.',
+      }) }] };
     }
   );
 
@@ -128,7 +144,11 @@ function registerStockLibraryTools(server, client, options = {}) {
     async (args) => {
       const q = buildQuery(args);
       const result = await client.get(`/v1/stock/collections${q ? '?' + q : ''}`);
-      const text = JSON.stringify({ count: result.count, collections: result.collections }, null, 2);
+      const text = compactList(result.collections, {
+        fields: ['id', 'name', 'slug', 'mediaType', 'source', 'itemCount'],
+        cap: 60,
+        total: result.count,
+      });
 
       if (ui()) {
         const collections = result.collections || [];

package/src/tools/visual_dna.js

@@ -5,7 +5,7 @@
 
 const { z } = require('zod');
 const FormData = require('form-data');
-const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES, projectScopeReadField } = require('./_shared');
+const { resolveToBuffer: sharedResolveToBuffer, VISUAL_DNA_MAX_BYTES, projectScopeReadField, compactList } = require('./_shared');
 const { UI, uiResult, appsEnabled } = require('../apps');
 
 // Visual DNA caps reference media at 25MB per file (stricter than the
@@ -110,10 +110,14 @@ function registerVisualDnaTools(server, client, options = {}) {
       const qs = params.toString();
       const result = await client.get(`/v1/visual-dna${qs ? '?' + qs : ''}`);
       const dnas = result.visual_dnas || [];
-      const text = JSON.stringify({
-        visual_dnas: dnas,
-        count: result.count || 0
-      }, null, 2);
+      // Full profiles measured 74,310 chars — the embedded analysis/description
+      // blobs are large and the model only needs enough to pick an id.
+      const text = compactList(dnas, {
+        fields: ['id', 'name', 'type', 'folder_id', 'tags', 'thumbnail'],
+        cap: 60,
+        total: result.count || dnas.length,
+        note: 'Narrow with `search`, `tags`, or `collection`; get_visual_dna returns one in full.',
+      });
 
       if (ui()) {
         return uiResult(UI.mediaGrid, text, {

package/src/tools/voices.js

@@ -40,7 +40,16 @@ function registerVoiceTools(server, client, options = {}) {
         return `${v.voice_id} — ${v.name} (${v.provider})${v3}\n   ${tags}${styles}${v.description ? `\n   ${v.description}` : ''}`;
       });
 
-      const text = `Available voices (${voices.length}):\n\n${lines.join('\n\n')}\n\nUse the "voice_id" value in generate_speech calls.`;
+      // The unfiltered catalog measured 190,286 chars — past what hosts accept.
+      // Cap the listing and tell the model how to narrow, rather than handing
+      // back a blob the host truncates at an arbitrary byte.
+      const VOICE_CAP = 60;
+      const shown = lines.slice(0, VOICE_CAP);
+      const more = voices.length - shown.length;
+      const narrowHint = more > 0
+        ? `\n\n…and ${more} more. Filter by \`language\`, \`gender\`, or \`provider\` to narrow.`
+        : '';
+      const text = `Available voices (showing ${shown.length} of ${voices.length}):\n\n${shown.join('\n\n')}${narrowHint}\n\nUse the "voice_id" value in generate_speech calls.`;
 
       if (ui()) {
         return uiResult(UI.mediaGrid, text, {

package/skill/references/models/voice-tts.md

@@ -1,85 +0,0 @@
-# Voice / Text-to-Speech (`generate_speech`) — full style & option reference
-
-`generate_speech` turns text into spoken audio. Every voice belongs to a
-**provider** (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos). Each
-provider exposes its own expressive controls. You may pass any control on any
-call — **the engine silently ignores controls that don't apply to the chosen
-voice's provider**, so you never need to branch on provider yourself.
-
-## Pick the voice first
-Call `list_voices` (filter by `provider`, `language`, `gender`) and pass the
-returned `voice_id` — or a display name like `"Rachel"`. Cloned/custom voices
-resolve by name too. The voice determines the provider, which determines which
-controls below take effect.
-
-## Core params (all providers)
-| Param | Type | Notes |
-|---|---|---|
-| `text` | string (required) | The words to speak. |
-| `voice` | string | Voice id or display name. Default `"Rachel"`. |
-| `model` | string | From `list_models type="text_to_speech"`. Default `eleven_v3`. Usually inferred from the voice — only needed to force a specific engine. |
-| `language` | string | BCP-47 code, e.g. `"en-US"`, `"he-IL"`, `"es-ES"`. |
-| `speaking_speed` | number | `0.5` (slow) – `2.0` (fast). Default `1.0`. Applies to ElevenLabs / OpenAI / Google. |
-| `project_id` | string | Scope into a project (see Projects rules). |
-
-## Expressive style / emotion (provider-specific)
-| Param | Provider(s) | Values / notes |
-|---|---|---|
-| `style_instructions` | **Google / Gemini** | Free-form natural-language direction, e.g. `"whisper conspiratorially, slightly amused"`, `"excited sports announcer"`. Max 500 chars. |
-| `selected_style` | **DeepDub**, MiniMax | Preset style. DeepDub: `reading`, `conversational`, `angry`, `breathy`, `panic`, `amused`, `sad`, `whisper`, `singing`, `shout`, `scream`, `mumbling`, `excited`. |
-| `emotion` | **MiniMax** | `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `calm`, `fluent`, `whisper`. |
-
-## ElevenLabs voice settings
-| Param | Range | Default | Effect |
-|---|---|---|---|
-| `similarity_boost` | 0–1 | 0.75 | Higher hews closer to the source voice. |
-| `style` | 0–1 | 0.5 | Style exaggeration — higher is more expressive/dramatic. |
-| `use_speaker_boost` | bool | true | Speaker-clarity boost. |
-
-## DeepDub controls
-| Param | Range | Default | Effect |
-|---|---|---|---|
-| `variance` | 0–1 | 0.2 | More variation / takes. |
-| `tempo` | 0–2 | 1.0 | Pacing multiplier. |
-| `promptBoost` | bool | true | Higher fidelity to the text. |
-| `seed` | int | — | Reproducibility (same seed + inputs → same output). Also honored by Zonos. |
-| `accentControl` | object | — | `{ accentBaseLocale, accentLocale, accentRatio }` — blend an accent. Provide BOTH `accentBaseLocale` (e.g. `"en-US"`) and `accentLocale` (e.g. `"en-GB"`); `accentRatio` 0–1 (default 0.5). |
-| `voiceTitle` | string | — | Display title for a custom/cloned voice. |
-
-## MiniMax fine controls
-| Param | Range | Default | Effect |
-|---|---|---|---|
-| `minimax_pitch` | −12 … 12 | 0 | Pitch shift. |
-| `minimax_vol` | 0–10 | 1 | Volume. |
-| `minimax_intensity` | — | — | Voice intensity. |
-| `minimax_timbre` | — | — | Voice timbre. |
-
-## Examples
-Neutral ElevenLabs read:
-```
-generate_speech(text="Welcome to Kolbo.", voice="Rachel")
-```
-Whispered, conspiratorial Gemini delivery:
-```
-generate_speech(text="Meet me at midnight.", voice="Kore",
-                style_instructions="whisper conspiratorially, slow and breathy")
-```
-Angry DeepDub take, faster:
-```
-generate_speech(text="Get out of my house!", voice="<deepdub voice>",
-                selected_style="angry", tempo=1.2)
-```
-Excited MiniMax with pitch/volume tweaks:
-```
-generate_speech(text="We won the championship!", voice="<minimax voice>",
-                emotion="happy", minimax_pitch=3, minimax_vol=6)
-```
-British-accented DeepDub blend:
-```
-generate_speech(text="Good evening.", voice="<deepdub voice>",
-                accentControl={ accentBaseLocale: "en-US", accentLocale: "en-GB", accentRatio: 0.7 })
-```
-
-## Credits
-~5 credits per 100 characters for most TTS models (Zonos ~3; voice design/clone
-~30 flat). Charged only on success. Use `check_credits` once per conversation.