The server defines 4 tools with basic schemas and descriptions, but suffers from significant quality gaps across naming, parameter documentation, and output schema clarity. Tool names use verb_noun convention (acceptable), but descriptions are minimal (9-50 chars, well below the 194-char baseline). Most critically, parameter descriptions are absent or minimal, and output schemas are entirely undocumented. The server returns raw JSON text wrapped in a 'text' content type rather than structured responses, forcing LLMs to parse unstructured output. No error handling guidance, no output field documentation, and no parameter validation constraints beyond basic enums on 2 tools.
Parameter descriptions missing or minimal, fileId appears 4 times with identical generic 'Figma file ID' but no guidance on format, validation, or prerequisites.
Expand each tool description to 150-250 chars, answering: What is the primary use case? What structure does it return? When should I call this vs. a similar tool? Example: 'Extract design tokens (colors, spacing, typography, shadows) from a Figma file. Returns a JSON object with categories: {colors: {...}, spacing: {...}, fonts: {...}}. Use this to bootstrap a design system before calling generate_design_system for full component definitions.'
Add descriptions to ALL parameters. For fileId, specify: 'The Figma file ID (format: 24-char alphanumeric string, e.g. abc123def456ghi789jkl012). Find it in your Figma URL: figma.com/file/[FILE_ID]/...' For nodeId, add: 'The unique Figma node ID of the component (string). Copy from the component's URL or right-click → Copy link.'
Document output schemas explicitly. Add to each tool's handler a docstring like: '@returns {object} {tokens: {colors: {name: string, value: string, category: string}[], spacing: {...}, fonts: {...}}, version: string, lastUpdated: ISO8601 date}' Then return STRUCTURED objects instead of JSON text strings.
Distinguish generate_design_system vs. generate_organized_design_system in descriptions: e.g., 'generate_design_system: Fast export of all tokens and component metadata. Use when you need raw data. Returns up to 1000 items.' vs. 'generate_organized_design_system: Formatted design system (JSON/TypeScript/CSS/SCSS) with hierarchy, grouped by category, optimized for use in codebases. Use when you need production-ready output.'
Add error handling with recovery guidance. Wrap FigmaClient calls in try/catch. Return: '{content: [{type: "text", text: "Figma file abc123 not found. Verify the file ID is correct and you have access. Try calling list_figma_files() to find available files."}]}' instead of letting exceptions propagate.
Duplicate or confusingly-named tools (generate_design_system vs. generate_organized_design_system), LLM cannot distinguish when to call which, leading to redundant or incorrect selection.
Unstructured output (raw JSON text), LLM must parse unstructured strings rather than receiving typed fields. Wastes tokens, increases hallucination risk, and breaks downstream field extraction.
FIGMA_TOKEN exposed via process.env without validation or secret injection pattern, if token is missing, server crashes with unclear error. No permission scoping.
No input validation, framework enum only enforced by JSON Schema; no runtime check prevents invalid 'framework' values. No parameter sanitization for nodeId or fileId.
No pagination support despite potential for large results (design tokens, component lists), LLM could receive thousands of tokens and exhaust context window.
Add pagination parameters to extract_design_tokens and generate_design_system: 'limit' (1-1000, default 100) and 'offset' (0-based). Return {tokens: [...], total: int, hasMore: bool, nextOffset: int|null} so LLM can iterate if needed.
Validate framework input at runtime: 'if (!['react','vue','html'].includes(framework)) return {content: [{type: "text", text: "Invalid framework: '" + framework + "'. Must be one of: react, vue, html"}]}'.
Add a FIGMA_TOKEN validation check on server startup: 'if (!FIGMA_TOKEN) throw new Error("FIGMA_ACCESS_TOKEN env var not set. See README.md for setup instructions.");'
Return structured objects instead of JSON text. Change: 'return {content: [{type: "text", text: JSON.stringify(tokens, null, 2)}]}' to: 'return {content: [{type: "text", text: JSON.stringify(tokens, null, 2)}, {type: "object", data: tokens}]}' (if MCP supports object type) or include a summary field: '{content: [{type: "text", text: `Extracted ${tokens.colors.length} colors, ${tokens.spacing.length} spacing values, ${tokens.fonts.length} font families.`}], data: tokens}' (if custom extension).
Add tool annotations for read-only operations: Update tool definitions to include 'readOnlyHint: true' for extract_design_tokens, analyze_component, generate_design_system, generate_organized_design_system (if MCP SDK supports tool annotations).
Document when each tool requires authentication (all of them) and what Figma permissions are needed (e.g., 'read:files'). Add to descriptions: 'Requires: Figma API token with read:files scope.'
Add a discovery tool or resource to list available Figma files, enabling the LLM to self-serve file lookups without trial-and-error guessing of file IDs.