figmanage 1.3.0 → 1.3.2

package/dist/operations/files.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { resolveOrgId } from '../tools/register.js';
+import { resolveOrgId } from '../helpers.js';
 export async function createFile(config, params) {
     const res = await internalClient(config).post('/api/files/create', {
         folder_id: params.project_id,

package/dist/operations/libraries.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function listOrgLibraries(config, params) {
     const orgId = requireOrgId(config, params.org_id);
     const res = await internalClient(config).get('/api/design_systems/libraries', {

package/dist/operations/org.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 // -- Seat constants --
 export const SEAT_HIERARCHY = {
     view: 0,

package/dist/operations/reading.js

@@ -1,4 +1,6 @@
 import { publicClient } from '../clients/public-api.js';
+// WARNING: Response can be very large for complex files. Callers should
+// encourage use of depth and node_id params to limit payload size.
 export async function getFile(config, params) {
     const queryParams = {};
     if (params.depth !== undefined)

package/dist/operations/teams.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function createTeam(config, params) {
     const orgId = requireOrgId(config, params.org_id);
     const res = await internalClient(config).post('/api/teams/create', { team_name: params.name, org_id: orgId, sharing_audience_control: 'org_view' });

package/dist/operations/variables.js

@@ -24,6 +24,17 @@ export async function updateVariables(config, params) {
         !params.variable_mode_values?.length) {
         throw new Error('At least one operation array is required.');
     }
+    const allOps = [
+        ...(params.variable_collections || []),
+        ...(params.variable_modes || []),
+        ...(params.variables || []),
+        ...(params.variable_mode_values || []),
+    ];
+    for (const op of allOps) {
+        if (!op.action || !['CREATE', 'UPDATE', 'DELETE'].includes(op.action)) {
+            throw new Error(`Each operation must have an action field (CREATE, UPDATE, or DELETE). Got: ${JSON.stringify(op.action)}`);
+        }
+    }
     const body = {};
     if (params.variable_collections)
         body.variableCollections = params.variable_collections;

package/dist/operations/webhooks.d.ts

@@ -3,7 +3,10 @@ export type WebhookEventType = 'FILE_UPDATE' | 'FILE_DELETE' | 'FILE_VERSION_UPD
 export type WebhookStatus = 'ACTIVE' | 'PAUSED';
 export declare function listWebhooks(config: AuthConfig, params: {
     team_id: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    webhooks: any[];
+}>;
 export declare function createWebhook(config: AuthConfig, params: {
     team_id: string;
     event_type: WebhookEventType;

package/dist/operations/webhooks.js

@@ -1,7 +1,8 @@
 import { publicClient } from '../clients/public-api.js';
 export async function listWebhooks(config, params) {
     const res = await publicClient(config).get(`/v2/teams/${params.team_id}/webhooks`);
-    return res.data?.webhooks || [];
+    const webhooks = res.data?.webhooks || [];
+    return { count: webhooks.length, webhooks };
 }
 export async function createWebhook(config, params) {
     const body = {

package/dist/tools/analytics.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { libraryUsage, componentUsage } from '../operations/analytics.js';
 // -- library_usage --
 defineTool({
@@ -15,10 +16,10 @@ defineTool({
         }, async ({ library_file_key, days }) => {
             try {
                 const result = await libraryUsage(config, { library_file_key, days });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Library usage:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch library usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch library usage: ${formatApiError(e)}`);
             }
         });
     },
@@ -37,10 +38,10 @@ defineTool({
         }, async ({ component_key, org_id }) => {
             try {
                 const result = await componentUsage(config, { component_key, org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Component usage:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch component usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch component usage: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/branching.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listBranches, createBranch, deleteBranch } from '../operations/branching.js';
 // -- list_branches --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
                 const result = await listBranches(config, { file_key });
                 if (result.length === 0)
                     return toolResult('No branches found.');
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} branch(es).`, result, 'Use create_branch to add a branch, or delete_branch to archive one.');
             }
             catch (e) {
-                return toolError(`Failed to list branches: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list branches: ${formatApiError(e)}`);
             }
         });
     },
@@ -39,10 +40,10 @@ defineTool({
         }, async ({ file_key, name }) => {
             try {
                 const result = await createBranch(config, { file_key, name });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Created branch.', result, 'Use get_file with the branch file key to read the branch.');
             }
             catch (e) {
-                return toolError(`Failed to create branch: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create branch: ${formatApiError(e)}`);
             }
         });
     },
@@ -66,7 +67,7 @@ defineTool({
                 return toolResult(`Archived branch ${branch_key}`);
             }
             catch (e) {
-                return toolError(`Failed to delete branch: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete branch: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/comments.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, listCommentReactions, } from '../operations/comments.js';
 // -- list_comments --
 defineTool({
@@ -18,10 +19,12 @@ defineTool({
                 if (as_md) {
                     return toolResult(formatCommentsAsMarkdown(comments));
                 }
-                return toolResult(JSON.stringify(comments, null, 2));
+                if (comments.length === 0)
+                    return toolResult('No comments on this file.');
+                return toolSummary(`${comments.length} comment(s).`, comments, 'Use post_comment to reply, or delete_comment to remove.');
             }
             catch (e) {
-                return toolError(`Failed to list comments: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list comments: ${formatApiError(e)}`);
             }
         });
     },
@@ -43,10 +46,10 @@ defineTool({
         }, async ({ file_key, message, comment_id, node_id }) => {
             try {
                 const result = await postComment(config, { file_key, message, comment_id, node_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Posted comment.', result);
             }
             catch (e) {
-                return toolError(`Failed to post comment: ${e.response?.status || e.message}`);
+                return toolError(`Failed to post comment: ${formatApiError(e)}`);
             }
         });
     },
@@ -59,7 +62,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('delete_comment', {
-            description: 'Permanently delete a comment. For top-level comments, the entire thread is removed.',
+            description: 'Permanently delete a comment. For top-level comments, the entire thread is removed. Cannot be undone.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
                 comment_id: figmaId.describe('Comment ID to delete'),
@@ -70,7 +73,7 @@ defineTool({
                 return toolResult(`Deleted comment ${comment_id}`);
             }
             catch (e) {
-                return toolError(`Failed to delete comment: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete comment: ${formatApiError(e)}`);
             }
         });
     },
@@ -89,10 +92,12 @@ defineTool({
         }, async ({ file_key, comment_id }) => {
             try {
                 const reactions = await listCommentReactions(config, { file_key, comment_id });
-                return toolResult(JSON.stringify(reactions, null, 2));
+                if (reactions.length === 0)
+                    return toolResult('No reactions on this comment.');
+                return toolSummary(`${reactions.length} reaction(s).`, reactions);
             }
             catch (e) {
-                return toolError(`Failed to list reactions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list reactions: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/components.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listFileComponents, listFileStyles, listTeamComponents, listTeamStyles, } from '../operations/components.js';
 // -- list_file_components --
 defineTool({
@@ -7,17 +8,19 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_file_components', {
-            description: 'List components published from a specific file.',
+            description: 'List components published from a file. Only published library components appear -- local unpublished components are not included.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
             },
         }, async ({ file_key }) => {
             try {
-                const components = await listFileComponents(config, { file_key });
-                return toolResult(JSON.stringify(components, null, 2));
+                const result = await listFileComponents(config, { file_key });
+                if (result.count === 0)
+                    return toolResult('No published components in this file. Components must be published to appear.');
+                return toolSummary(`${result.count} published component(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list file components: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list file components: ${formatApiError(e)}`);
             }
         });
     },
@@ -28,17 +31,19 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_file_styles', {
-            description: 'List styles in a specific file.',
+            description: 'List styles published from a file. Only published library styles appear.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
             },
         }, async ({ file_key }) => {
             try {
-                const styles = await listFileStyles(config, { file_key });
-                return toolResult(JSON.stringify(styles, null, 2));
+                const result = await listFileStyles(config, { file_key });
+                if (result.count === 0)
+                    return toolResult('No published styles in this file.');
+                return toolSummary(`${result.count} published style(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list file styles: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list file styles: ${formatApiError(e)}`);
             }
         });
     },
@@ -49,7 +54,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_team_components', {
-            description: 'List published components across a team. Supports pagination.',
+            description: 'List published components across a team. Pass the cursor from the response\'s pagination object to fetch the next page.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
                 page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
@@ -58,10 +63,12 @@ defineTool({
         }, async ({ team_id, page_size, cursor }) => {
             try {
                 const result = await listTeamComponents(config, { team_id, page_size, cursor });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.components?.length || 0;
+                const hasMore = !!result.pagination?.cursor;
+                return toolSummary(`${count} component(s)${hasMore ? ' (more pages available)' : ''}.`, result, hasMore ? 'Pass the cursor from pagination to fetch the next page.' : undefined);
             }
             catch (e) {
-                return toolError(`Failed to list team components: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list team components: ${formatApiError(e)}`);
             }
         });
     },
@@ -72,7 +79,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_team_styles', {
-            description: 'List published styles across a team. Supports pagination.',
+            description: 'List published styles across a team. Pass the cursor from the response\'s pagination object to fetch the next page.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
                 page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
@@ -81,10 +88,12 @@ defineTool({
         }, async ({ team_id, page_size, cursor }) => {
             try {
                 const result = await listTeamStyles(config, { team_id, page_size, cursor });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.styles?.length || 0;
+                const hasMore = !!result.pagination?.cursor;
+                return toolSummary(`${count} style(s)${hasMore ? ' (more pages available)' : ''}.`, result, hasMore ? 'Pass the cursor from pagination to fetch the next page.' : undefined);
             }
             catch (e) {
-                return toolError(`Failed to list team styles: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list team styles: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/compound-manager.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { offboardUser, onboardUser, quarterlyDesignOpsReport, } from '../operations/compound-manager.js';
 // -- offboard_user --
 defineTool({
@@ -24,10 +25,11 @@ defineTool({
                     transfer_to,
                     org_id,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const mode = (execute ?? false) ? 'Offboarding complete.' : 'Offboarding audit (read-only). Set execute=true to proceed.';
+                return toolSummary(mode, result);
             }
             catch (e) {
-                return toolError(`Failed to audit user for offboarding: ${e.response?.status || e.message}`);
+                return toolError(`Failed to audit user for offboarding: ${formatApiError(e)}`);
             }
         });
     },
@@ -60,10 +62,10 @@ defineTool({
                     confirm,
                     org_id,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Onboarding complete for ${email}.`, result);
             }
             catch (e) {
-                return toolError(`Failed to onboard user: ${e.response?.status || e.message}`);
+                return toolError(`Failed to onboard user: ${formatApiError(e)}`);
             }
         });
     },
@@ -85,10 +87,11 @@ defineTool({
                     org_id,
                     days: days ?? 90,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const highlightText = result.highlights?.join(' ') || 'Report generated.';
+                return toolSummary(highlightText, result);
             }
             catch (e) {
-                return toolError(`Failed to generate design ops report: ${e.response?.status || e.message}`);
+                return toolError(`Failed to generate design ops report: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/compound.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { fileSummary, workspaceOverview, openComments, cleanupStaleFiles, organizeProject, setupProjectStructure, seatOptimization, permissionAudit, branchCleanup, } from '../operations/compound.js';
 // -- file_summary --
 defineTool({
@@ -14,10 +15,10 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const result = await fileSummary(config, { file_key });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.name}: ${result.pages?.length || 0} pages, ${result.component_count} components, ${result.unresolved_comment_count} unresolved comments.`, result);
             }
             catch (e) {
-                return toolError(`Failed to summarize file: ${e.response?.status || e.message}`);
+                return toolError(`Failed to summarize file: ${formatApiError(e)}`);
             }
         });
     },
@@ -35,10 +36,11 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await workspaceOverview(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                const teamCount = result.teams?.length || 0;
+                return toolSummary(`${teamCount} team(s). Seats and billing included.`, result);
             }
             catch (e) {
-                return toolError(`Failed to fetch workspace overview: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch workspace overview: ${formatApiError(e)}`);
             }
         });
     },
@@ -56,10 +58,12 @@ defineTool({
         }, async ({ project_id }) => {
             try {
                 const result = await openComments(config, { project_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                const total = result.total_unresolved || 0;
+                const fileCount = result.files?.length || 0;
+                return toolSummary(`${total} unresolved comment(s) across ${fileCount} file(s).`, result, 'Use post_comment with file_key and parent_id to reply.');
             }
             catch (e) {
-                return toolError(`Failed to fetch open comments: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch open comments: ${formatApiError(e)}`);
             }
         });
     },
@@ -72,7 +76,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('cleanup_stale_files', {
-            description: 'Find files not modified in N days and optionally trash them. Defaults to dry run.',
+            description: 'Find files not modified in N days and optionally trash them. dry_run=true (default) previews which files would be trashed without trashing them. Set dry_run=false to execute.',
             inputSchema: {
                 project_id: figmaId.describe('Project ID'),
                 days_stale: z.number().optional().default(90).describe('Days since last modification (default: 90)'),
@@ -85,10 +89,12 @@ defineTool({
                     days_stale: days_stale ?? 90,
                     dry_run: rawDryRun ?? true,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.stale_files?.length || 0;
+                const action = result.dry_run ? `${count} stale file(s) found. Set dry_run=false to trash them.` : `Trashed ${result.trashed_count || 0} file(s).`;
+                return toolSummary(action, result);
             }
             catch (e) {
-                return toolError(`Failed to cleanup stale files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to cleanup stale files: ${formatApiError(e)}`);
             }
         });
     },
@@ -100,7 +106,7 @@ defineTool({
     mutates: true,
     register(server, config) {
         server.registerTool('organize_project', {
-            description: 'Move multiple files into a target project in a single batch.',
+            description: 'Move files into a target project in a single batch. Files are moved (not copied) from their current project.',
             inputSchema: {
                 file_keys: z.array(figmaId).min(1).describe('File keys to move'),
                 target_project_id: figmaId.describe('Destination project ID'),
@@ -108,10 +114,10 @@ defineTool({
         }, async ({ file_keys, target_project_id }) => {
             try {
                 const result = await organizeProject(config, { file_keys, target_project_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Moved ${result.moved} file(s) to project ${result.target_project_id}.`, result);
             }
             catch (e) {
-                return toolError(`Failed to organize project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to organize project: ${formatApiError(e)}`);
             }
         });
     },
@@ -134,10 +140,10 @@ defineTool({
         }, async ({ team_id, projects }) => {
             try {
                 const result = await setupProjectStructure(config, { team_id, projects });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created ${result.created?.length || 0} project(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to setup project structure: ${e.response?.status || e.message}`);
+                return toolError(`Failed to setup project structure: ${formatApiError(e)}`);
             }
         });
     },
@@ -161,10 +167,13 @@ defineTool({
                     days_inactive: days_inactive ?? 90,
                     include_cost: include_cost ?? true,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const inactive = result.summary?.inactive_paid || 0;
+                const savingsCents = result.summary?.monthly_waste_cents || 0;
+                const savingsStr = savingsCents > 0 ? ` Potential savings: $${(savingsCents / 100).toFixed(2)}/mo.` : '';
+                return toolSummary(`${inactive} inactive paid seat(s).${savingsStr}`, result, 'Use change_seat to downgrade inactive users, or offboard_user for full removal.');
             }
             catch (e) {
-                return toolError(`Failed to analyze seat optimization: ${e.response?.status || e.message}`);
+                return toolError(`Failed to analyze seat optimization: ${formatApiError(e)}`);
             }
         });
     },
@@ -190,10 +199,11 @@ defineTool({
                     flag_external: flag_external ?? true,
                     org_id,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const flagCount = result.flags?.length || 0;
+                return toolSummary(`${flagCount} issue(s) flagged.`, result, flagCount > 0 ? 'Use revoke_access or set_permissions to address flagged issues.' : undefined);
             }
             catch (e) {
-                return toolError(`Failed to audit permissions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to audit permissions: ${formatApiError(e)}`);
             }
         });
     },
@@ -206,7 +216,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('branch_cleanup', {
-            description: 'Find stale branches across a project and optionally archive them. Defaults to dry run.',
+            description: 'Find stale branches across a project and optionally archive them. dry_run=true (default) previews which branches would be archived. Archives move branch files to trash (recoverable).',
             inputSchema: {
                 project_id: figmaId.describe('Project ID'),
                 days_stale: z.number().min(1).max(365).optional().default(60).describe('Days since last modification to flag as stale (default: 60)'),
@@ -219,10 +229,12 @@ defineTool({
                     days_stale: days_stale ?? 60,
                     dry_run: rawDryRun ?? true,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const stale = result.stale_branches?.length || 0;
+                const action = result.dry_run ? `${stale} stale branch(es) found. Set dry_run=false to archive.` : `Archived ${result.archived_count || 0} branch(es).`;
+                return toolSummary(action, result);
             }
             catch (e) {
-                return toolError(`Failed to cleanup branches: ${e.response?.status || e.message}`);
+                return toolError(`Failed to cleanup branches: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/export.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { exportNodes, getImageFills } from '../operations/export.js';
 // -- export_nodes --
 defineTool({
@@ -17,10 +18,10 @@ defineTool({
         }, async ({ file_key, node_ids, format, scale }) => {
             try {
                 const result = await exportNodes(config, { file_key, node_ids, format, scale });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Exported ${result.length} node(s). URLs valid ~14 days.`, result);
             }
             catch (e) {
-                return toolError(`Failed to export nodes: ${e.response?.status || e.message}`);
+                return toolError(`Failed to export nodes: ${formatApiError(e)}`);
             }
         });
     },
@@ -40,10 +41,10 @@ defineTool({
                 const results = await getImageFills(config, { file_key });
                 if (results.length === 0)
                     return toolResult('No image fills in this file.');
-                return toolResult(JSON.stringify(results, null, 2));
+                return toolSummary(`${results.length} image fill(s).`, results);
             }
             catch (e) {
-                return toolError(`Failed to get image fills: ${e.response?.status || e.message}`);
+                return toolError(`Failed to get image fills: ${formatApiError(e)}`);
             }
         });
     },