Kiyas implements 3 well-defined tools with strong descriptions and comprehensive schemas. All tools have clear verb-based names (compare, get_diff_report, list_issues), detailed parameter documentation, and structured output. The compare tool is particularly strong with 16 parameters, each with descriptions and type constraints. Schemas use Zod validation with proper type definitions. Main gap: no output schema documentation in the visible code, tool annotations (readOnlyHint) are missing but appropriate for this read-focused server, and error handling guidance could be more explicit.

• Add explicit TypeScript interface or JSDoc output schema for each tool. Example: compare returns { reportId: string; reportPath: string }, document this in the tool or server.ts
• Declare readOnlyHint: true in all 3 tool definitions (all operations are read-only). This improves agent planning.
• Add error handling layer that returns structured errors with actionable guidance. For get_diff_report/list_issues: if reportId not found, return 'Report not found. Call compare() to generate a new report, or check available reports in the reports directory.'
• Document validate that exactly one of (figma, designImage) and exactly one of (target, component) are provided. Add early validation with clear error message.
• For list_issues, document pagination: 'Returns a list of issues (capped at 100 per call; pass next_cursor for additional results)' and add offset/limit or cursor parameters if needed.
• Add example flow to README: compare → get_diff_report → list_issues, with sample reportId values and expected return shapes.
• Consider splitting compare into compare (initiates check, returns reportId immediately) and optionally a wait_for_comparison (polls reportId until ready) if comparisons are async. Current blocking behavior should be explicit.