This Figma MCP server provides 15 read-only tools with basic schema definitions but suffers from significant quality gaps. All tools have descriptions and input schemas present, which is a positive baseline. However, descriptions are generic and brief (most under 50 chars), parameter descriptions lack context about formats and constraints, and output schemas are entirely undocumented. Tools follow a consistent naming pattern (verb_noun: get_*, search_*) which is excellent, but lack the depth of documentation needed for reliable LLM selection and error recovery. No tool uses structured output schemas, error handling provides minimal guidance, and there are no security considerations documented despite accepting Figma API keys. The server is functional for basic read operations but falls short of production-grade quality expected for agent integration.
Output schemas entirely undocumented, LLMs cannot predict what fields are returned or plan downstream tool calls. No documentation of pagination, filtering, or structured response formats.
Tool descriptions are too brief (10-40 chars) and lack context. 'Get comments from a file' does not explain when to use this tool, what format comments are in, or whether they include resolved/unresolved status. Descriptions should be 50-200 chars and answer: what, when, prerequisites.
Add structured output schema documentation to every tool. Specify: field names, types (string, number, array, object), required vs optional fields. Example for get_widgets: 'Returns {"widgets": [{"id": string, "name": string, "type": string, "syncData": object | null}], "total": number, "nextCursor": string | null}'
Expand tool descriptions to 50-200 chars and include: (1) what the tool retrieves, (2) when to use it vs similar tools, (3) prerequisites. Example: 'Retrieve all widget nodes in a Figma file. Use this first to discover available widgets before inspecting individual widgets with get_widget. Requires valid file_key.'
Document parameter formats in descriptions. Example: 'file_key (UUID format, e.g. abc123def456; obtain from Figma URL or get_file call)' and 'node_id (alphanumeric string, e.g. 12:34)'
Implement pagination for list tools. Add optional parameters: limit (1 - 50, default 20), offset (0+). Return {"items": [...], "total": number, "hasMore": boolean, "nextOffset": number | null}. Mention in description: 'Large files may have many results. Use limit/offset to paginate.'
Replace generic error messages with actionable guidance. Example: catch(error) { if (error.status === 404) return 'File not found. Check the file_key is correct. Use search() to find files by name.'; if (error.status === 401) return 'Authentication failed. Verify FIGMA_PERSONAL_ACCESS_TOKEN is set.'; }
Rename 'search' tool to 'search_global' or 'search_files' to clarify what entity is being searched. Alternatively, add a required 'entity_type' enum parameter (file|widget|component|frame) to disambiguate.
Parameter descriptions lack format and constraint information. 'The Figma file key' does not explain: expected format (UUID? alphanumeric?), min/max length, or valid examples. LLMs cannot validate inputs without this context.
Error handling provides generic messages with no recovery guidance. Code returns '(error as Error).message' which may be raw API errors like 'Unauthorized' or 'Rate limited'. LLMs need explicit: 'User not found. Try search() first.' or 'Rate limit hit. Retry in 60 seconds.'
No pagination or result-limiting strategy documented. Tools like get_widgets, get_comments, get_versions may return unbounded result sets that overflow context windows. LLMs need limit/offset and total_count fields.
Tool 'search' has ambiguous name. It does not specify what entity is being searched (widgets? files? components? teams?). LLMs cannot distinguish this from search_widgets without reading implementation.
No tool annotations (readOnlyHint, idempotentHint) to signal tool properties to LLMs. While all tools are read-only (low risk), adding annotations would help agents classify them and optimize caching strategies.
Add readOnlyHint annotation to all tools since they are read-only and cacheable. This allows agents to optimize for repeated calls.
Document which tools depend on others. Example: 'To inspect a widget, first call get_widgets to discover IDs, then pass them to get_widget. If you only have a widget name, call search_widgets first.'
Add error categorization in responses. Return {"success": boolean, "error": {"code": string, "message": string, "retryable": boolean, "suggestion": string} | null}. Example: {"success": false, "error": {"code": "NOT_FOUND", "message": "File abc123 not found", "retryable": false, "suggestion": "Verify the file key matches the Figma file URL. Use search() to find files by name."}}
Document widget-specific tools as a cohesive group. Add overview: 'Widgets are reusable components in Figma. These tools let you discover, inspect, and analyze widget properties and sync data. Start with get_widgets to list all, then drill down with get_widget or get_widget_sync_data.'
Add security note: 'FIGMA_PERSONAL_ACCESS_TOKEN is injected at runtime from environment. Never include tokens in tool parameters. All tool calls are logged for audit, avoid passing sensitive user data via parameters.'