The server defines 2 tools with reasonable structure and Zod-based schema validation. Both tools have clear verb-noun naming (get_, download_) and substantive descriptions (150+ chars each). However, the definitions have notable gaps: output schemas are not explicitly documented in code, parameter descriptions lack format constraints and validation guidance, and error handling is generic. The tools follow single-responsibility principles but lack idempotency hints and composition details. Per-tool analysis: get_figma_data (65/100) has solid naming and description but schema lacks explicit output type documentation; download_figma_images (59/100) similarly structured but the nested 'nodes' array schema lacks detailed validation constraints. Token efficiency is reasonable (descriptions avoid examples), but actionable error recovery is absent.

• Add explicit output schema documentation. For get_figma_data: describe return type as 'SimplifiedDesign object with fields: name (string), nodes (array of design nodes), styles (array of CSS styles), exports (array of export metadata)'. For download_figma_images: describe return as 'object with fields: downloaded (array of filenames), failed (array of {nodeId, error}), localPath (string)'.
• Enhance parameter descriptions with format constraints. For depth: 'Integer 1 - 100, default all levels. Higher depths may exhaust token budgets for large files.' For localPath: 'Absolute filesystem path (Unix: /tmp/figma, Windows: C:\\temp\\figma). Must be writable. Directories created if missing.'
• Implement actionable error recovery. Catch and format common failures: 'Figma API returned 401: Invalid API key. Regenerate your token at https://figma.com/account/api-tokens and update FIGMA_API_KEY env var.' Or: 'File key "abc123" not found. Call list_figma_files() first to discover valid file keys.'
• Add idempotency guarantees and dry-run support. For download_figma_images, add optional 'dry_run' boolean param (default false). When true, return success/failure predictions without writing. Document: 'Idempotent, safe to retry. Existing files overwritten silently unless dry_run=true.'
• Document caching and rate limits. Add to tool descriptions: 'Results cached 24 hours to reduce API calls. Figma API rate limit: 120 req/min per token. If limit hit, server returns 429 with Retry-After header.'
• Add permission scope declarations. Register tools with scope hints: get_figma_data (scope: 'read:figma_files'), download_figma_images (scope: 'read:figma_files, write:local_filesystem'). Enable least-privilege agent configuration.