Two tools with strong descriptions and complete schemas. Both tools have well-articulated use cases, clear parameter documentation, and proper input validation. However, output schemas are not formally documented in the code, and error handling guidance could be more specific. Tool naming follows action-verb convention. Parameter descriptions are detailed and context-aware.

• Add explicit outputSchema to both tool definitions documenting the structure of ScreenData and ComponentData (name, variants, designTokens, layers, annotations, etc.). Use JSON Schema with $ref to TypeScript type definitions if available.
• Enhance error messages with recovery guidance. Instead of 'Failed to fetch screen data: {error}', return categorized errors: 'Screen not found (retryable: no). The screen URL may be invalid. Check: app.zeplin.io/project/{projectId}/screen/{screenId}' or 'API rate limit exceeded (retryable: yes, after 60s).'
• Add readOnlyHint annotation to both tools since they perform GET operations without side effects. This signals to MCP clients that responses can be safely cached.
• For get_screen.targetLayerName, add validation: return 'Layer not found: {targetLayerName}. Available layers on this screen: {list}' to guide the LLM toward correct layer names instead of blind retry.
• Consider offering a batch_get_screens(urls: string[], includeVariants?: boolean) tool to reduce multi-screen workflows from N calls to 1. Return array of ScreenData objects with per-item success/failure metadata.
• Document the expected return schema in INSTRUCTIONS or as a JSON Schema example. E.g., 'get_screen returns {type: "Screen", name: string, variants: [{name, annotations, layers}], designTokens: [...]}'.
• Add 'includeVariants' to parameter descriptions an example of when to use it: 'Set to false if you only need the specific linked screen, or if variants are not relevant to conserve tokens. Omit or set true for a complete design picture.' This is already done, good pattern to replicate elsewhere.