figmanage 1.2.9 → 1.3.1

package/dist/tools/permissions.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 { getPermissions, setPermissions, share, revokeAccess, listRoleRequests, approveRoleRequest, denyRoleRequest, } from '../operations/permissions.js';
 // -- get_permissions --
 defineTool({
@@ -15,10 +16,10 @@ defineTool({
         }, async ({ resource_type, resource_id }) => {
             try {
                 const result = await getPermissions(config, { resource_type, resource_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} user(s) with access.`, result, 'Use set_permissions or revoke_access to modify.');
             }
             catch (e) {
-                return toolError(`Failed to get permissions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to get permissions: ${formatApiError(e)}`);
             }
         });
     },
@@ -43,7 +44,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(e.response?.status ? `Failed to set permissions: ${e.response.status}` : e.message);
+                return toolError(`Failed to set permissions: ${formatApiError(e)}`);
             }
         });
     },
@@ -71,7 +72,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to share: ${e.response?.status || e.message}`);
+                return toolError(`Failed to share: ${formatApiError(e)}`);
             }
         });
     },
@@ -84,7 +85,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('revoke_access', {
-            description: "Remove someone's access to a file, project, or team. Looks up the role by user_id.",
+            description: "Remove a user's access to a file, project, or team. The user loses access immediately.",
             inputSchema: {
                 resource_type: z.enum(['file', 'folder', 'team']).describe('Type of resource'),
                 resource_id: figmaId.describe('Resource ID'),
@@ -96,7 +97,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(e.response?.status ? `Failed to revoke access: ${e.response.status}` : e.message);
+                return toolError(`Failed to revoke access: ${formatApiError(e)}`);
             }
         });
     },
@@ -112,10 +113,12 @@ defineTool({
         }, async () => {
             try {
                 const result = await listRoleRequests(config);
-                return toolResult(JSON.stringify(result, null, 2));
+                if (result.length === 0)
+                    return toolResult('No pending access requests.');
+                return toolSummary(`${result.length} pending request(s).`, result, 'Use approve_role_request or deny_role_request.');
             }
             catch (e) {
-                return toolError(`Failed to list role requests: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list role requests: ${formatApiError(e)}`);
             }
         });
     },
@@ -137,7 +140,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to approve request: ${e.response?.status || e.message}`);
+                return toolError(`Failed to approve request: ${formatApiError(e)}`);
             }
         });
     },
@@ -159,7 +162,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to deny request: ${e.response?.status || e.message}`);
+                return toolError(`Failed to deny request: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/projects.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 { createProject, renameProject, moveProject, trashProject, restoreProject, setProjectDescription, } from '../operations/projects.js';
 // -- create_project --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
         }, async ({ team_id, name }) => {
             try {
                 const result = await createProject(config, { team_id, name });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created project "${result.name}".`, result, 'Use list_files to see files, or create_file to add one.');
             }
             catch (e) {
-                return toolError(`Failed to create project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create project: ${formatApiError(e)}`);
             }
         });
     },
@@ -42,7 +43,7 @@ defineTool({
                 return toolResult(`Renamed project ${project_id} to "${name}"`);
             }
             catch (e) {
-                return toolError(`Failed to rename project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to rename project: ${formatApiError(e)}`);
             }
         });
     },
@@ -65,7 +66,7 @@ defineTool({
                 return toolResult(`Moved project ${project_id} to team ${destination_team_id}`);
             }
             catch (e) {
-                return toolError(`Failed to move project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to move project: ${formatApiError(e)}`);
             }
         });
     },
@@ -78,7 +79,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('trash_project', {
-            description: 'Move a project to trash.',
+            description: 'Move a project and all its files to trash. Recoverable via restore_project.',
             inputSchema: {
                 project_id: figmaId.describe('Project ID to trash'),
             },
@@ -88,7 +89,7 @@ defineTool({
                 return toolResult(`Trashed project ${project_id}`);
             }
             catch (e) {
-                return toolError(`Failed to trash project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to trash project: ${formatApiError(e)}`);
             }
         });
     },
@@ -110,7 +111,7 @@ defineTool({
                 return toolResult(`Restored project ${project_id}`);
             }
             catch (e) {
-                return toolError(`Failed to restore project: ${e.response?.status || e.message}`);
+                return toolError(`Failed to restore project: ${formatApiError(e)}`);
             }
         });
     },
@@ -133,7 +134,7 @@ defineTool({
                 return toolResult(`Updated description for project ${project_id}`);
             }
             catch (e) {
-                return toolError(`Failed to set description: ${e.response?.status || e.message}`);
+                return toolError(`Failed to set description: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/reading.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 { getFile, getNodes } from '../operations/reading.js';
 // -- get_file --
 defineTool({
@@ -7,7 +8,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('get_file', {
-            description: 'Read file contents as a node tree. To read a branch, use the branch file key from list_branches.',
+            description: 'Read file contents as a node tree. Use depth to limit response size (full trees can be very large). depth=1 returns pages only. To read a branch, use the branch file key from list_branches.',
             inputSchema: {
                 file_key: figmaId.describe('File key (or branch file key from list_branches)'),
                 depth: z.number().int().optional().describe('Tree depth limit. 0=root, 1=pages, 2=top-level frames. Omit for full tree.'),
@@ -16,10 +17,12 @@ defineTool({
         }, async ({ file_key, depth, node_id }) => {
             try {
                 const result = await getFile(config, { file_key, depth, node_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                const name = result.name || 'Untitled';
+                const pages = result.document?.children?.length || 0;
+                return toolSummary(`${name}: ${pages} page(s). Use depth parameter to limit response size.`, result);
             }
             catch (e) {
-                return toolError(`Failed to get file: ${e.response?.status || e.message}`);
+                return toolError(`Failed to get file: ${formatApiError(e)}`);
             }
         });
     },
@@ -30,7 +33,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('get_nodes', {
-            description: 'Read specific nodes from a file. Returns node data for each requested node ID.',
+            description: 'Read specific nodes from a file. Returns the full node tree for each ID including type, name, layout properties, fills, strokes, and children.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
                 node_ids: z.array(figmaId).min(1).describe('Node IDs to fetch'),
@@ -39,10 +42,11 @@ defineTool({
         }, async ({ file_key, node_ids, depth }) => {
             try {
                 const result = await getNodes(config, { file_key, node_ids, depth });
-                return toolResult(JSON.stringify(result, null, 2));
+                const nodeCount = result.nodes ? Object.keys(result.nodes).length : 0;
+                return toolSummary(`${nodeCount} node(s) returned.`, result);
             }
             catch (e) {
-                return toolError(`Failed to get nodes: ${e.response?.status || e.message}`);
+                return toolError(`Failed to get nodes: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/register.d.ts

@@ -20,6 +20,13 @@ export declare function toolResult(text: string): {
         text: string;
     }>;
 };
+/** Format a tool response with a summary line, JSON data, and optional next-step guidance. */
+export declare function toolSummary(summary: string, data: unknown, nextStep?: string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
 export declare function toolError(message: string): {
     isError: true;
     content: Array<{
@@ -27,6 +34,5 @@ export declare function toolError(message: string): {
         text: string;
     }>;
 };
-export declare function resolveOrgId(config: AuthConfig, explicit?: string): string | undefined;
-export declare function requireOrgId(config: AuthConfig, explicit?: string): string;
+export { resolveOrgId, requireOrgId } from '../helpers.js';
 //# sourceMappingURL=register.d.ts.map

package/dist/tools/register.js

@@ -56,21 +56,16 @@ export function registerTools(server, config, enabledToolsets, readOnly) {
 export function toolResult(text) {
     return { content: [{ type: 'text', text }] };
 }
+/** Format a tool response with a summary line, JSON data, and optional next-step guidance. */
+export function toolSummary(summary, data, nextStep) {
+    const parts = [summary, '', JSON.stringify(data, null, 2)];
+    if (nextStep)
+        parts.push('', nextStep);
+    return { content: [{ type: 'text', text: parts.join('\n') }] };
+}
 export function toolError(message) {
     return { isError: true, content: [{ type: 'text', text: message }] };
 }
-export function resolveOrgId(config, explicit) {
-    const id = explicit || config.orgId;
-    if (id && !/^[\w.:-]+$/.test(id))
-        throw new Error('Invalid org ID format');
-    return id;
-}
-export function requireOrgId(config, explicit) {
-    const id = explicit || config.orgId;
-    if (!id)
-        throw new Error('Org context required. Run list_orgs to see available workspaces, or set FIGMA_ORG_ID.');
-    if (!/^[\w.:-]+$/.test(id))
-        throw new Error('Invalid org ID format');
-    return id;
-}
+// Re-export from helpers so existing tool imports still work
+export { resolveOrgId, requireOrgId } from '../helpers.js';
 //# sourceMappingURL=register.js.map

package/dist/tools/setup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Interactive setup tools for first-run MCP configuration.
+ *
+ * Guides the user through cookie extraction and PAT creation
+ * via conversational tool calls. Registered when auth is missing;
+ * replaced by the full toolset once setup completes.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSetupTools(server: McpServer, onSetupComplete: () => void): void;
+//# sourceMappingURL=setup.d.ts.map

package/dist/tools/setup.js

@@ -0,0 +1,181 @@
+/**
+ * Interactive setup tools for first-run MCP configuration.
+ *
+ * Guides the user through cookie extraction and PAT creation
+ * via conversational tool calls. Registered when auth is missing;
+ * replaced by the full toolset once setup completes.
+ */
+import { platform } from 'node:os';
+import { z } from 'zod';
+import { extractCookies, validateSession, validatePat, resolveAccountInfo, } from '../auth/cookie.js';
+import { setActiveWorkspace, getActiveWorkspace } from '../config.js';
+import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
+// State shared across setup steps within a single session
+let pendingAccounts = [];
+export function registerSetupTools(server, onSetupComplete) {
+    server.tool('setup_status', 'Check figmanage authentication status and get setup instructions. Always call this before using any other tool.', {}, async () => {
+        const config = loadAuthConfig();
+        if (hasPat(config) && hasCookie(config)) {
+            return { content: [{ type: 'text', text: 'figmanage is fully configured. All tools are available.' }] };
+        }
+        const os = platform();
+        const lines = [
+            'figmanage needs two credentials to give you full access to all 85 Figma workspace tools:',
+            '',
+            '1. Browser cookie -- extracted automatically from Chrome',
+            '2. Personal Access Token (PAT) -- created in Figma settings',
+            '',
+        ];
+        if (!hasCookie(config)) {
+            lines.push('NEXT: Cookie extraction');
+            lines.push('The user must be logged into figma.com in Chrome before proceeding.');
+            if (os === 'darwin') {
+                lines.push('');
+                lines.push('When they proceed, a macOS Keychain prompt will appear asking to access');
+                lines.push('"Chrome Safe Storage". They need to click Allow.');
+            }
+            else if (os === 'linux') {
+                lines.push('');
+                lines.push('On Linux, Chrome cookies are decrypted using the system keyring or a default key.');
+            }
+            lines.push('');
+            lines.push('Ask the user to confirm they are logged into figma.com in Chrome, then call setup_extract_cookies.');
+        }
+        else {
+            lines.push('Cookie auth is configured.');
+            lines.push('');
+            lines.push('NEXT: Personal Access Token');
+            lines.push('Ask the user to create a PAT at: https://www.figma.com/settings');
+            lines.push('(Security > Personal access tokens)');
+            lines.push('Then call setup_save_pat with the token value.');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    server.tool('setup_extract_cookies', 'Extract Figma session cookies from Chrome. On macOS this triggers a Keychain prompt. IMPORTANT: Before calling, confirm the user is logged into figma.com in Chrome and knows a system prompt may appear.', {}, async () => {
+        try {
+            const accounts = extractCookies();
+            if (accounts.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: 'No Figma cookies found in Chrome. The user needs to log into figma.com in Chrome first, then try again.',
+                        }],
+                };
+            }
+            pendingAccounts = accounts;
+            const infos = await Promise.all(accounts.map(a => resolveAccountInfo(a)));
+            const lines = [
+                `Found ${accounts.length} Figma account${accounts.length > 1 ? 's' : ''}:`,
+                '',
+            ];
+            for (let i = 0; i < accounts.length; i++) {
+                const info = infos[i];
+                const label = info.figmaEmail || `User ${accounts[i].userId}`;
+                lines.push(`  ${i + 1}. ${label} (Chrome profile: ${info.profileName})`);
+            }
+            lines.push('');
+            lines.push('Ask the user which account to use, then call setup_select_account with the chosen number.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (e) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Cookie extraction failed: ${e.message}` }],
+            };
+        }
+    });
+    server.tool('setup_select_account', 'Select a Figma account and validate the session. Call after setup_extract_cookies.', {
+        account_index: z.number().int().min(1).describe('Account number from the list returned by setup_extract_cookies'),
+    }, async ({ account_index }) => {
+        if (pendingAccounts.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'No accounts available. Call setup_extract_cookies first.' }],
+            };
+        }
+        const idx = account_index - 1;
+        if (idx < 0 || idx >= pendingAccounts.length) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Invalid selection. Choose 1-${pendingAccounts.length}.` }],
+            };
+        }
+        const account = pendingAccounts[idx];
+        try {
+            const session = await validateSession(account.cookieValue, account.userId);
+            let orgId = session.orgId;
+            if (!orgId && session.orgs.length > 0) {
+                orgId = session.orgs[0].id;
+            }
+            const workspaceName = orgId || account.userId || 'default';
+            setActiveWorkspace(workspaceName, {
+                cookie: account.cookieValue,
+                user_id: account.userId,
+                org_id: orgId || undefined,
+                cookie_extracted_at: new Date().toISOString(),
+            });
+            const lines = [`Session valid (user ${account.userId}).`];
+            if (session.orgs.length > 0) {
+                const orgName = session.orgs.find(o => o.id === orgId)?.name;
+                lines.push(`Workspace: ${orgName ? `${orgName} (${orgId})` : orgId}`);
+            }
+            if (session.teams.length > 0) {
+                lines.push(`Teams: ${session.teams.map(t => t.name).join(', ')}`);
+            }
+            lines.push('');
+            lines.push('Cookie saved. Now need a Personal Access Token for full access.');
+            lines.push('Ask the user to create one at: https://www.figma.com/settings');
+            lines.push('(Security > Personal access tokens)');
+            lines.push('Then call setup_save_pat with the token.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (e) {
+            const status = e.response?.status;
+            if (status === 401 || status === 403) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Cookie expired or invalid. Log into figma.com in Chrome and run setup_extract_cookies again.' }],
+                };
+            }
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Session validation failed: ${e.message}` }],
+            };
+        }
+    });
+    server.tool('setup_save_pat', 'Validate and save a Figma Personal Access Token. Completes setup and activates all tools.', {
+        pat: z.string().min(1).describe('Figma Personal Access Token (starts with figd_)'),
+    }, async ({ pat }) => {
+        try {
+            const patUser = await validatePat(pat);
+            // Update the active workspace with the PAT
+            const workspace = getActiveWorkspace();
+            if (!workspace) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'No workspace configured. Run setup_extract_cookies and setup_select_account first.' }],
+                };
+            }
+            workspace.pat = pat;
+            const workspaceName = workspace.org_id || workspace.user_id || 'default';
+            setActiveWorkspace(workspaceName, workspace);
+            // Clear setup state
+            pendingAccounts = [];
+            // Trigger full tool registration
+            onSetupComplete();
+            return {
+                content: [{
+                        type: 'text',
+                        text: `PAT valid (${patUser}). Setup complete -- all 85 figmanage tools are now available.`,
+                    }],
+            };
+        }
+        catch {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'PAT invalid or expired. Check the token and try again.' }],
+            };
+        }
+    });
+}
+//# sourceMappingURL=setup.js.map

package/dist/tools/teams.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 { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
 // -- create_team --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
         }, async ({ name, org_id }) => {
             try {
                 const result = await createTeam(config, { name, org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created team.`, result, 'Use create_project to add projects to this team.');
             }
             catch (e) {
-                return toolError(`Failed to create team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create team: ${formatApiError(e)}`);
             }
         });
     },
@@ -42,7 +43,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to rename team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to rename team: ${formatApiError(e)}`);
             }
         });
     },
@@ -55,7 +56,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('delete_team', {
-            description: 'Delete a team. This is destructive and cannot be undone.',
+            description: 'Permanently delete a team and all its projects/files. This cannot be undone. All team members lose access.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
             },
@@ -65,7 +66,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to delete team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete team: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/variables.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 { listLocalVariables, listPublishedVariables, updateVariables, isEnterpriseScopeError, ENTERPRISE_ERROR, } from '../operations/variables.js';
 // -- list_local_variables --
 defineTool({
@@ -14,12 +15,14 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const result = await listLocalVariables(config, { file_key });
-                return toolResult(JSON.stringify(result, null, 2));
+                const vars = result.variables ? Object.keys(result.variables).length : 0;
+                const collections = result.variableCollections ? Object.keys(result.variableCollections).length : 0;
+                return toolSummary(`${vars} variable(s) in ${collections} collection(s).`, result);
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to list local variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list local variables: ${formatApiError(e)}`);
             }
         });
     },
@@ -37,12 +40,13 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const result = await listPublishedVariables(config, { file_key });
-                return toolResult(JSON.stringify(result, null, 2));
+                const vars = result.variables ? Object.keys(result.variables).length : 0;
+                return toolSummary(`${vars} published variable(s).`, result);
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to list published variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list published variables: ${formatApiError(e)}`);
             }
         });
     },
@@ -55,7 +59,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('update_variables', {
-            description: 'Bulk create, update, or delete variables, collections, modes, and mode values. Requires Enterprise plan.',
+            description: 'Bulk create, update, or delete variables, collections, modes, and mode values. Requires Enterprise plan. Each operation object needs an action field (CREATE, UPDATE, or DELETE). Deletions are immediate and cannot be undone -- list variables first to verify IDs.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
                 variable_collections: z.array(z.record(z.any())).optional().describe('Collection operations (action: CREATE, UPDATE, or DELETE)'),
@@ -72,12 +76,12 @@ defineTool({
                     variables,
                     variable_mode_values,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Variables updated.', result, 'Use list_local_variables to verify changes.');
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to update variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to update variables: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/versions.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 { listVersions, createVersion } from '../operations/versions.js';
 // -- list_versions --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
                 const result = await listVersions(config, { file_key });
                 if (result.length === 0)
                     return toolResult('No versions found.');
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} version(s).`, result, 'Use create_version to add a named checkpoint.');
             }
             catch (e) {
-                return toolError(`Failed to list versions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list versions: ${formatApiError(e)}`);
             }
         });
     },
@@ -40,10 +41,10 @@ defineTool({
         }, async ({ file_key, title, description }) => {
             try {
                 const result = await createVersion(config, { file_key, title, description });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created version "${result.label}".`, result);
             }
             catch (e) {
-                return toolError(`Failed to create version: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create version: ${formatApiError(e)}`);
             }
         });
     },