figmanage 1.3.0 → 1.3.1

package/dist/tools/files.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 { createFile, renameFile, moveFiles, duplicateFile, trashFiles, restoreFiles, favoriteFile, setLinkAccess, } from '../operations/files.js';
 // -- create_file --
 defineTool({
@@ -17,10 +18,10 @@ defineTool({
         }, async ({ project_id, editor_type, org_id }) => {
             try {
                 const result = await createFile(config, { project_id, editor_type, org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created ${result.editor_type || 'design'} file.`, result);
             }
             catch (e) {
-                return toolError(`Failed to create file: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create file: ${formatApiError(e)}`);
             }
         });
     },
@@ -43,7 +44,7 @@ defineTool({
                 return toolResult(`Renamed to "${name}"`);
             }
             catch (e) {
-                return toolError(`Failed to rename file: ${e.response?.status || e.message}`);
+                return toolError(`Failed to rename file: ${formatApiError(e)}`);
             }
         });
     },
@@ -69,7 +70,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to move files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to move files: ${formatApiError(e)}`);
             }
         });
     },
@@ -89,10 +90,10 @@ defineTool({
         }, async ({ file_key, project_id }) => {
             try {
                 const result = await duplicateFile(config, { file_key, project_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Duplicated file.`, result);
             }
             catch (e) {
-                return toolError(`Failed to duplicate file: ${e.response?.status || e.message}`);
+                return toolError(`Failed to duplicate file: ${formatApiError(e)}`);
             }
         });
     },
@@ -105,7 +106,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('trash_files', {
-            description: 'Move files to trash. Supports batch operations.',
+            description: 'Move files to trash (recoverable via restore_files). Supports batch operations.',
             inputSchema: {
                 file_keys: z.array(figmaId).min(1).describe('Array of file keys to trash'),
             },
@@ -115,7 +116,7 @@ defineTool({
                 return toolResult(`Trashed ${result.succeeded} file(s)`);
             }
             catch (e) {
-                return toolError(`Failed to trash files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to trash files: ${formatApiError(e)}`);
             }
         });
     },
@@ -140,7 +141,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to restore files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to restore files: ${formatApiError(e)}`);
             }
         });
     },
@@ -163,7 +164,7 @@ defineTool({
                 return toolResult(`${result.favorited ? 'Favorited' : 'Unfavorited'} file ${file_key}`);
             }
             catch (e) {
-                return toolError(`Failed to toggle favorite: ${e.response?.status || e.message}`);
+                return toolError(`Failed to toggle favorite: ${formatApiError(e)}`);
             }
         });
     },
@@ -186,7 +187,7 @@ defineTool({
                 return toolResult(`Set link access to "${result.link_access}" on file ${file_key}`);
             }
             catch (e) {
-                return toolError(`Failed to set link access: ${e.response?.status || e.message}`);
+                return toolError(`Failed to set link access: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/libraries.js

@@ -1,4 +1,5 @@
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listOrgLibraries } from '../operations/libraries.js';
 // -- list_org_libraries --
 defineTool({
@@ -13,10 +14,12 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await listOrgLibraries(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                if (result.length === 0)
+                    return toolResult('No libraries found.');
+                return toolSummary(`${result.length} library/libraries.`, result, 'Use library_usage to see adoption metrics.');
             }
             catch (e) {
-                return toolError(`Failed to list org libraries: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list org libraries: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/navigate.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 { checkAuthStatus, listOrgs, switchOrg, listTeams, listProjects, listFiles, listRecentFiles, search, getFileInfo, listFavorites, } from '../operations/navigate.js';
 // -- check_auth --
 defineTool({
@@ -34,10 +35,10 @@ defineTool({
                 if (orgs.length === 0) {
                     return toolResult('No workspaces found. You may be on a free/starter plan.');
                 }
-                return toolResult(JSON.stringify(orgs, null, 2));
+                return toolSummary(`Found ${orgs.length} workspace(s).`, orgs, 'Use switch_org to change workspace, or list_teams to browse.');
             }
             catch (e) {
-                return toolError(`Failed to list orgs: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list orgs: ${formatApiError(e)}`);
             }
         });
     },
@@ -60,7 +61,7 @@ defineTool({
                 return toolResult(`Switched workspace: ${result.previous} -> ${result.current.name} (${result.current.id})`);
             }
             catch (e) {
-                return toolError(`Failed to switch org: ${e.response?.status || e.message}`);
+                return toolError(`Failed to switch org: ${formatApiError(e)}`);
             }
         });
     },
@@ -75,10 +76,12 @@ defineTool({
         }, async () => {
             try {
                 const teams = await listTeams(config);
-                return toolResult(JSON.stringify(teams, null, 2));
+                if (teams.length === 0)
+                    return toolResult('No teams found.');
+                return toolSummary(`Found ${teams.length} team(s).`, teams, 'Use list_projects with a team_id to browse projects.');
             }
             catch (e) {
-                return toolError(`Failed to list teams: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list teams: ${formatApiError(e)}`);
             }
         });
     },
@@ -96,10 +99,12 @@ defineTool({
         }, async ({ team_id }) => {
             try {
                 const projects = await listProjects(config, { team_id });
-                return toolResult(JSON.stringify(projects, null, 2));
+                if (projects.length === 0)
+                    return toolResult('No projects found.');
+                return toolSummary(`Found ${projects.length} project(s).`, projects, 'Use list_files with a project_id to see files.');
             }
             catch (e) {
-                return toolError(`Failed to list projects: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list projects: ${formatApiError(e)}`);
             }
         });
     },
@@ -119,10 +124,12 @@ defineTool({
         }, async ({ project_id, page_size, page_token }) => {
             try {
                 const result = await listFiles(config, { project_id, page_size, page_token });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.files.length;
+                const summary = `${count} file(s).` + (result.pagination?.has_more ? ' More pages available.' : '');
+                return toolSummary(summary, result, 'Use get_file_info or get_file for details.');
             }
             catch (e) {
-                return toolError(`Failed to list files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list files: ${formatApiError(e)}`);
             }
         });
     },
@@ -137,10 +144,12 @@ defineTool({
         }, async () => {
             try {
                 const files = await listRecentFiles(config);
-                return toolResult(JSON.stringify(files, null, 2));
+                if (files.length === 0)
+                    return toolResult('No recent files.');
+                return toolSummary(`${files.length} recently accessed file(s).`, files, 'Use get_file_info for details.');
             }
             catch (e) {
-                return toolError(`Failed to list recent files: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list recent files: ${formatApiError(e)}`);
             }
         });
     },
@@ -163,10 +172,10 @@ defineTool({
                 if (results.length === 0) {
                     return toolResult('No results. Try list_recent_files or browse via list_projects + list_files.');
                 }
-                return toolResult(JSON.stringify(results, null, 2));
+                return toolSummary(`Found ${results.length} result(s).`, results, 'Use get_file_info for file details.');
             }
             catch (e) {
-                return toolError(`Search failed: ${e.response?.status || e.message}`);
+                return toolError(`Search failed: ${formatApiError(e)}`);
             }
         });
     },
@@ -184,10 +193,10 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const info = await getFileInfo(config, { file_key });
-                return toolResult(JSON.stringify(info, null, 2));
+                return toolSummary(`${info.name} (${info.editor_type || 'design'})`, info);
             }
             catch (e) {
-                return toolError(`Failed to get file info: ${e.response?.status || e.message}`);
+                return toolError(`Failed to get file info: ${formatApiError(e)}`);
             }
         });
     },
@@ -202,10 +211,12 @@ defineTool({
         }, async () => {
             try {
                 const favorites = await listFavorites(config);
-                return toolResult(JSON.stringify(favorites, null, 2));
+                if (favorites.length === 0)
+                    return toolResult('No favorites found.');
+                return toolSummary(`${favorites.length} favorited file(s).`, favorites, 'Use get_file_info for details.');
             }
             catch (e) {
-                return toolError(`Failed to list favorites: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list favorites: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/org.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 { listAdmins, listOrgTeams, seatUsage, listTeamMembers, billingOverview, listInvoices, orgDomains, aiCreditUsage, exportMembers, listOrgMembers, contractRates, changeSeat, } from '../operations/org.js';
 // -- list_admins --
 defineTool({
@@ -15,10 +16,10 @@ defineTool({
         }, async ({ org_id, include_license_admins }) => {
             try {
                 const result = await listAdmins(config, { org_id, include_license_admins });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} admin(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list admins: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list admins: ${formatApiError(e)}`);
             }
         });
     },
@@ -37,10 +38,10 @@ defineTool({
         }, async ({ org_id, include_secret_teams }) => {
             try {
                 const result = await listOrgTeams(config, { org_id, include_secret_teams });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} team(s) in the org.`, result, 'Use list_team_members for member details.');
             }
             catch (e) {
-                return toolError(`Failed to list org teams: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list org teams: ${formatApiError(e)}`);
             }
         });
     },
@@ -59,10 +60,10 @@ defineTool({
         }, async ({ org_id, search_query }) => {
             try {
                 const result = await seatUsage(config, { org_id, search_query });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Seat usage breakdown:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch seat usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch seat usage: ${formatApiError(e)}`);
             }
         });
     },
@@ -80,10 +81,10 @@ defineTool({
         }, async ({ team_id }) => {
             try {
                 const result = await listTeamMembers(config, { team_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} member(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list team members: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list team members: ${formatApiError(e)}`);
             }
         });
     },
@@ -101,10 +102,10 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await billingOverview(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Billing overview:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch billing overview: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch billing overview: ${formatApiError(e)}`);
             }
         });
     },
@@ -122,10 +123,10 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await listInvoices(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} invoice(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list invoices: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list invoices: ${formatApiError(e)}`);
             }
         });
     },
@@ -143,10 +144,10 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await orgDomains(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Domain configuration:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch org domains: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch org domains: ${formatApiError(e)}`);
             }
         });
     },
@@ -164,10 +165,10 @@ defineTool({
         }, async ({ plan_id }) => {
             try {
                 const result = await aiCreditUsage(config, { plan_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('AI credit usage:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch AI credit usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch AI credit usage: ${formatApiError(e)}`);
             }
         });
     },
@@ -189,7 +190,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to export members: ${e.response?.status || e.message}`);
+                return toolError(`Failed to export members: ${formatApiError(e)}`);
             }
         });
     },
@@ -208,10 +209,10 @@ defineTool({
         }, async ({ org_id, search_query }) => {
             try {
                 const result = await listOrgMembers(config, { org_id, search_query });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} member(s).`, result, 'Use change_seat to modify seat types.');
             }
             catch (e) {
-                return toolError(`Failed to list org members: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list org members: ${formatApiError(e)}`);
             }
         });
     },
@@ -229,10 +230,10 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await contractRates(config, { org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Seat pricing:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch contract rates: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch contract rates: ${formatApiError(e)}`);
             }
         });
     },
@@ -257,10 +258,10 @@ defineTool({
                 const result = await changeSeat(config, { user_id, seat_type, org_id, confirm });
                 if (typeof result === 'string')
                     return toolResult(result);
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Seat change requires confirmation.', result);
             }
             catch (e) {
-                return toolError(e.response?.status ? `Failed to change seat: ${e.response.status}` : e.message);
+                return toolError(`Failed to change seat: ${formatApiError(e)}`);
             }
         });
     },

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