All 4 tools have basic verb-noun naming (get_*) and visible input schemas with type definitions. However, descriptions are extremely terse (10-27 chars, well below the 50-200 char baseline for LLM-optimized tools). Parameter descriptions exist but are minimal. No output schemas are documented. Error handling is absent, no guidance on retryability, user-fixable errors, or recovery paths. Tools lack idempotency hints, permission declarations, and composition metadata. The server exposes Figma API tokens via environment injection (correct), but tools do not validate inputs or sanitize against injection attacks.

• Expand all tool descriptions to 80-150 chars. Example: 'get_page_structure' → 'Fetch all pages and top-level frames from a Figma file. Returns page names and frame lists. Call this first to discover available design sections.'
• Document output schemas for each tool. Example for get_page_structure: returns array of {page: string, frames: string[]}. For get_hero_section: returns {texts: {title?, subtitle?, description?}, background: {r, g, b, a}?, layout: {direction, spacing, padding}}.
• Add input validation: validate file_key matches Figma key format (alphanumeric + hyphen, 20-30 chars); validate node_id is non-empty. Return 'Invalid file_key format' errors with examples.
• Wrap API calls in try-except with specific error messages. Example: 'Figma API returned 401, check FIGMA_API_KEY is valid and has read:files scope. Retry after 60 seconds.' Distinguish retryable (timeout, 429) from fatal (401, 404) errors.
• Add tool annotations via FastMCP: @mcp.tool(readOnlyHint=True, idempotentHint=True) to signal safety properties to LLMs.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry