Allows comparison of Figma design frames against rendered UI components, using the Figma API to export design images and fetch metadata.
A developer-first MCP server (also runnable as a CLI) that compares Figma designs against rendered UI components and surfaces an AI-powered semantic diff. Plugs into Claude Code, Cursor, Codex CLI, and any other MCP-compatible client.
Unlike pixel-diff tools, kiyas uses vision AI to understand what is different and why it matters — outputting actionable, human-readable feedback like:
"border-radius is 8px in implementation but 12px in design"
"spacing between title and subtitle is 16px tighter than the design"
Just describe the component by name. kiyas finds it in your codebase, screenshots it, and compares it against the Figma design.
Prefer an app over a terminal? There's also a desktop app.
A native macOS app for running the same comparisons point-and-click — built for designers and anyone who'd rather not touch a terminal. Pick a project, paste a Figma link (or drop in a screenshot), describe the component, and get the full report in-app. It uses the same engine and the same subscription-based auth: AI calls go through the Claude Code or Codex CLI on your machine, never an API key.
⬇ Download the latest release (Apple Silicon)
Download the .dmg, drag Kiyas to Applications.
Preview builds aren't notarized yet — on first launch, right-click → Open (or run xattr -dr com.apple.quarantine /Applications/Kiyas.app).
Sign in to Claude Code or Codex in any terminal once; the app picks it up from there.
Highlights: project sidebar with dev-server detection, capture preview + crop before comparing, built-in terminal, full dark mode, and a Liquid Glass icon on macOS 26.
To build from source instead:
git clone https://github.com/saiffmirza/kiyas && cd kiyas
npm install
npm run desktop # dev mode
# or package a .app/.dmg:
cd apps/desktop && npx electron-builder --macRelated MCP server: UI Expert MCP Server
┌─────────────────────┐
│ kiyas │
│ (MCP server / CLI) │
│ │
│ figma / design img │
│ + target/component │
└──────────┬───────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌───────────┐ ┌─────────────┐
│ 1. Auth │ │ 2. Design │ │ 3. Resolve │
│ │ │ Capture │ │ Component │
│ Verify │ │ │ │ │
│ Claude Code │ │ Figma API │ │ AI agent │
│ or Codex CLI │ │ PNG export│ │ searches │
│ is installed │ │ — or your │ │ codebase, │
│ & signed in │ │ own image │ │ finds URL + │
│ │ │ (--design)│ │ CSS selector│
└──────┬───────┘ └─────┬─────┘ └──────┬──────┘
│ │ │
│ ▼ ▼
│ ┌────────────┐ ┌────────────┐
│ │ Figma │ │ Playwright │
│ │ design │ │ screenshot │
│ │ (PNG) │ │ (PNG) │
│ └─────┬──────┘ └─────┬──────┘
│ │ │
│ └───────┬───────┘
│ ▼
│ ┌──────────────────────┐
└─────────►│ 4. Vision AI Compare │
│ │
│ Both images sent to │
│ Claude Code CLI with │
│ a structured prompt │
│ │
│ Returns JSON array │
│ of discrepancies │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 5. HTML Report │
│ │
│ Side-by-side images │
│ Severity badges │
│ Interactive filters │
│ HIGH / MEDIUM / LOW │
│ │
│ file:// link in │
│ terminal output │
└──────────────────────┘Step-by-step:
Authenticate — kiyas delegates AI calls to the Claude Code or Codex CLI. Your existing subscription handles everything — no API keys needed.
Get the design image — Parses the Figma URL, calls the Figma REST API to export the frame as a PNG (at the same scale as the screenshot — adaptive, see --scale), and fetches node metadata (colors, fonts, spacing). Or skip Figma entirely: pass --design <path-or-url> with your own design image and no Figma token is needed.
Resolve component — An AI agent scans your codebase (file tree, routes, components) and maps your natural-language description to a URL on your dev server + a CSS selector.
Screenshot implementation — Playwright launches headless Chromium, navigates to the resolved URL, and captures the component.
AI comparison — Both PNGs are passed to the Claude Code CLI with a structured prompt. The AI identifies every discrepancy with specific CSS properties and values.
Report — Results are formatted into an HTML report with side-by-side image comparison, severity badges, and interactive filters. A file link is printed to the terminal for easy access.
kiyas exposes its comparison engine as an MCP server over stdio. Three tools, all with Zod-typed input schemas:
Tool | Description | Required input |
| Run a fresh design-vs-implementation comparison; returns | ( |
| Fetch a stored report's HTML or JSON content |
|
| List discrepancies from a stored report, optionally filtered by severity |
|
Reports are persisted under .kiyas/reports/<reportId>/ in your project directory, so the same reportId stays valid across calls and across CLI/MCP usage.
npm install -g kiyas-cli
npx playwright install chromiumClaude Code
claude mcp add kiyas -- npx -y kiyas-cli@latest mcp
# with a Figma token (only needed for Figma-URL comparisons):
claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx -y kiyas-cli@latest mcpkiyas is also listed in the official MCP Registry as io.github.saiffmirza/kiyas, so registry-aware clients can install it directly from their MCP catalog.
Cursor — edit ~/.cursor/mcp.json:
{
"mcpServers": {
"kiyas": {
"command": "npx",
"args": ["kiyas-cli@latest", "mcp"]
}
}
}Codex CLI — edit ~/.codex/config.toml:
[mcp_servers.kiyas]
command = "npx"
args = ["kiyas-cli@latest", "mcp"]The configs above use kiyas-cli@latest so npx picks up new releases on every launch — the tradeoff is a registry check per start, and launches can fail offline. If you'd rather pin a version (kiyas-cli@1.3.1) or use a global install, that's safe too: kiyas checks npm once at startup (non-blocking) and logs a notice to stderr when a newer version is available.
The compare tool needs Figma access only when you pass a figma URL. Three ways to provide it:
1. Pass your token via the server config (recommended):
claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=<your-token> -- npx -y kiyas-cli@latest mcpor in .mcp.json / mcp.json / config.toml, add an env block:
{
"mcpServers": {
"kiyas": {
"command": "npx",
"args": ["kiyas-cli@latest", "mcp"],
"env": { "FIGMA_ACCESS_TOKEN": "your-token" }
}
}
}2. A .kiyasrc file in the project root or home directory: { "figmaAccessToken": "..." }
3. No token at all — pair with the Figma MCP server. If the agent already has Figma's own MCP server connected, it can export the frame as an image itself and pass the file path (or image URL) as designImage instead of a figma URL. kiyas never touches the Figma API in this mode:
Export node 1:234 from the Figma file as a PNG, then use kiyas to compare it against the primary button on the login page.
If a figma URL is used with no token configured, the tool fails fast with these instructions rather than hanging.
Once connected, you can ask the agent things like:
Compare the Figma frame at
<url>against the primary button on the login page, then list only the high-severity issues.
The agent will call compare to produce a reportId, then list_issues with severity: "high" against that ID.
Node.js 20+
Claude Code installed and signed in (Pro, Max, or Team subscription), or Codex for OpenAI
A Figma personal access token (generate one here) — only needed for --figma; comparing against a local screenshot with --design requires no token
npm install -g kiyas-cli
npx playwright install chromiumkiyas setupThis walks you through:
Figma token — creates a read-only personal access token and saves it to .env
AI provider — checks for Claude Code or Codex and sets the default
# Describe the component by name — kiyas finds it automatically
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
--component "eventHeader on the redemption screen"
# Or provide a direct URL if you already know it
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
--target "http://localhost:3000/redemption" \
--selector ".event-header"
# Save the report to a specific path
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
--component "primary button" \
--output report.html
# Output as JSON (for CI pipelines)
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
--component "primary button" \
--format json
# Compare against a design screenshot instead of Figma (no Figma token needed)
kiyas --design ./design.png \
--component "primary button" \
--output report.html
# Use OpenAI instead of Claude
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
--component "nav bar" \
--model openaiFlag | Description | Required |
| Figma frame/component URL | Yes** |
| Design image (local path or URL) instead of Figma | Yes** |
| Natural-language description of the component to find | Yes* |
| Direct URL of the rendered component (skips AI lookup) | Yes* |
| Dev server base URL (default: auto-detect 3000/5173/8080/4200) | No |
| AI provider: | No |
| Path to save the report (default: | No |
| Output format: | No |
| Viewport size for screenshot (default: | No |
| Render scale for both Figma export and screenshot. Default adaptive: | No |
| Capture only the viewport instead of the full scrollable page | No |
| CSS selector to screenshot a specific element | No |
| Time in ms to wait before screenshot (for animations/loading) | No |
| Playwright | No |
| Path to a JSON config file for batch comparisons | No |
| Severity filter: | No |
*Provide either --component or --target. When using --component, kiyas uses AI to find the component in your codebase and resolve it to a URL.
**Provide either --figma or --design. With --design, the Figma export is skipped entirely and no Figma token is required.
Most real designs live behind a login. kiyas accepts a Playwright storageState JSON file (cookies + localStorage) and reuses it for the screenshot session — the same format Playwright tests use, so any auth-state file your tests already produce works as-is.
# 1. Record a session — log in, then close the browser. Playwright writes auth.json.
npx playwright codegen --save-storage=auth.json https://app.example.com
# 2. Use it for kiyas screenshots
kiyas \
--figma "https://www.figma.com/design/.../?node-id=1:234" \
--target "https://app.example.com/dashboard" \
--auth-state ./auth.jsonThe MCP compare tool exposes the same option as authState — pass the path and the agent screenshots authenticated views with no further setup.
kiyas leverages your existing AI subscriptions — no separate API keys needed. It delegates all AI calls to the Claude Code or Codex CLI, which handle their own authentication.
Claude (default): Requires Claude Code installed and signed in with a Pro, Max, or Team subscription. kiyas spawns the claude CLI for AI calls, so usage counts against your existing subscription quota.
# Install Claude Code if you haven't already
npm install -g @anthropic-ai/claude-code
# Sign in
claude auth loginOpenAI (alternative): Requires Codex installed and signed in. Use --model openai to select it.
codex auth loginIf no CLI is found, kiyas prompts you to install and sign in:
Claude Code is not installed or not signed in.
kiyas uses your existing Claude Code subscription — no API keys needed.
To fix this, either:
1. Install and sign into Claude Code:
npm install -g @anthropic-ai/claude-code
claude auth login
2. Or switch kiyas to use OpenAI instead:
kiyas set model openai
(requires signing into Codex: codex auth login)Figma: Requires a personal access token with File content → Read only scope. Run kiyas setup to configure it, or set FIGMA_ACCESS_TOKEN in .env manually.
kiyas is a harness around vision AI, and a harness is only useful if its results are consistent. What it controls:
Pinned models — the comparison and resolver models are pinned (claude --model / codex -m) instead of drifting with CLI defaults. Configure with kiyas set claudeModel <id> / kiyas set codexModel <id>.
Isolated AI context — comparisons run in an empty working directory so your project's CLAUDE.md/AGENTS.md, hooks, and MCP servers can't influence the output.
Frozen capture environment — animations and transitions disabled, fonts awaited, UTC timezone, fixed locale, full-page screenshots, and the Figma export scale always matches the screenshot's device scale factor. Component-sized captures default to 2x — measured on the eval set, that raised subtle-mutation recall from 75% to 90%.
Validated output — model responses are schema-validated (malformed findings are dropped with a warning; a majority-invalid response fails the run instead of producing a quietly wrong report).
Run manifest — every report's JSON records the viewport, scale, threshold, pinned model, CLI version, prompt version hash, and how a --component description was resolved, so any two reports can be meaningfully compared.
Multi-run voting — --runs 3 runs the comparison three times concurrently and keeps only majority-vote findings, each tagged with a confidence score. Higher consistency at N× cost; off by default.
Measured, not vibed — npm run eval (repo only, not shipped) runs a golden eval set: fixture pages with known injected CSS mutations plus zero-mutation pairs, scored deterministically for recall, precision, severity agreement, false-positive floor, and run-to-run stability. Prompt and pipeline changes are validated against it.
For teams running repeated comparisons, create a kiyas.config.json:
{
"figmaAccessToken": "env:FIGMA_ACCESS_TOKEN",
"model": "claude",
"viewport": "1280x720",
"comparisons": [
{
"name": "Primary Button",
"figma": "https://www.figma.com/design/abc123/Design?node-id=1:234",
"target": "primary button on the login page"
},
{
"name": "Event Card",
"figma": "https://www.figma.com/design/abc123/Design?node-id=5:678",
"target": "http://localhost:6006/iframe.html?id=card--event",
"selector": ".event-card"
}
]
}The target field accepts both component descriptions (resolved by AI) and direct URLs. Each comparison takes either figma (a URL) or design (a local image path) as its design source. Run with:
kiyas --config ./kiyas.config.jsonkiyas/ (npm workspaces monorepo)
├── packages/
│ ├── core/ # @kiyas/core — the engine (private, bundled into the CLI)
│ │ └── src/
│ │ ├── index.ts # Public API barrel (runComparison, resolveComponent, …)
│ │ ├── config.ts # Config file loading + Figma token resolution
│ │ ├── settings.ts # Persisted user settings
│ │ ├── auth/
│ │ │ ├── index.ts # Auth resolver (picks best available auth)
│ │ │ ├── claude-oauth.ts # Verify Claude Code CLI is available
│ │ │ └── openai-auth.ts # Verify Codex CLI is available
│ │ ├── resolve/
│ │ │ └── component.ts # AI agent: finds component in codebase → URL + selector
│ │ ├── capture/
│ │ │ ├── figma.ts # Figma REST API: export frame as PNG + metadata
│ │ │ └── playwright.ts # Playwright: headless screenshot of rendered component
│ │ ├── compare/
│ │ │ ├── index.ts # Orchestrator: sends images to vision AI
│ │ │ ├── pipeline.ts # Pure runComparison() + report persistence (shared by CLI + MCP)
│ │ │ ├── claude.ts # Claude comparison via Claude Code CLI
│ │ │ ├── openai.ts # OpenAI comparison via Codex CLI
│ │ │ └── prompt.ts # The comparison prompt (shared across providers)
│ │ ├── report/
│ │ │ └── html.ts # Generate self-contained HTML report with embedded images
│ │ └── utils/
│ │ ├── parse-figma-url.ts # Extract file key + node ID from Figma URL
│ │ └── logger.ts # Minimal logging utility
│ └── cli/ # kiyas-cli — the published npm package
│ ├── src/
│ │ ├── index.ts # CLI entry point (argument parsing, orchestration)
│ │ ├── setup.ts # Interactive first-time setup
│ │ └── mcp/
│ │ ├── server.ts # MCP server bootstrap (stdio transport)
│ │ └── tools.ts # Zod schemas + handlers (compare, get_diff_report, list_issues)
│ ├── package.json
│ └── tsup.config.ts
├── apps/
│ └── desktop/ # @kiyas/desktop — Electron app (macOS)
│ ├── src/
│ │ ├── main/ # Main process: IPC, capture flow, pty terminal
│ │ ├── preload/ # Typed context bridge (window.kiyas)
│ │ └── renderer/ # React UI (cream/navy/gold theme, dark mode)
│ ├── build/kiyas.icon # Icon Composer bundle (Liquid Glass icon source)
│ ├── scripts/gen-icon.mjs # Renders all icon variants from the Farisi kāf
│ └── electron-builder.yml
├── eval/ # Golden eval set + scoring harness
├── .env.example
├── .kiyasrc.example
├── package.json # Workspace root
└── tsconfig.jsonLayer | Tool |
Runtime | Node.js (TypeScript) |
MCP |
|
Screenshot capture | Playwright (headless Chromium) |
Figma export | Figma REST API |
AI comparison | Claude Code CLI or Codex CLI (vision) |
Component resolution | Claude Code CLI / Codex CLI (agent) |
Output | HTML (default), JSON |
Desktop app | Electron, electron-vite, React, node-pty + xterm |
Build | tsup, electron-builder |
Package manager | npm |
MIT
Compare a design against a rendered implementation and return discrepancies (measured on kiyas's golden eval set: 90% mutation recall, zero false positives on identical pairs). Provide figma (frame URL) or designImage (local path or URL of a design screenshot), plus either target (a URL) or component (natural-language description; kiyas finds it in the codebase). No Figma token needed for designImage — if a Figma MCP server is connected, export the frame as an image with its screenshot tool and pass that here. Returns a reportId you can pass to get_diff_report or list_issues.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Friendly name for the comparison, used in the report header | |
| runs | No | Run the comparison N times and keep majority-vote findings — higher consistency at N× cost (default: 1) | |
| wait | No | Time in ms to wait after page load before screenshotting | |
| figma | No | Figma frame/component URL. Provide either `figma` OR `designImage`. | |
| model | No | AI provider (default: claude) | |
| scale | No | Render scale applied to both the Figma export and the screenshot (default: adaptive — 2 for component-sized captures, 1 for large ones) | |
| target | No | Direct URL of the rendered component. Provide either `target` OR `component`. | |
| fullPage | No | Capture the full scrollable page when no selector is given (default: true) | |
| selector | No | CSS selector to screenshot a specific element | |
| viewport | No | Viewport for the screenshot, format WIDTHxHEIGHT (default: 1280x720) | |
| authState | No | Path to a Playwright storageState JSON file (cookies + localStorage). Lets kiyas screenshot authenticated views the same way your tests do. Generate with `npx playwright codegen --save-storage=auth.json`. | |
| component | No | Natural-language description of the component to find in the codebase, e.g. "primary button on the login page". | |
| devServer | No | Dev server base URL (default: auto-detect a listening server on ports 3000/5173/8080/4200, else http://localhost:3000) | |
| threshold | No | Severity threshold for the rendered HTML report (default: all) | |
| colorScheme | No | Force prefers-color-scheme for the capture. Default: auto — kiyas detects the design's brightness and retries in the matching scheme. | |
| designImage | No | Local path, http(s) URL, or base64 data: URI of a design image (e.g. a screenshot) to compare against, instead of a Figma URL. Useful when no Figma token is configured — e.g. export the frame with a connected Figma MCP server's screenshot tool and pass the resulting file path or image URL here. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it notes the evaluation metrics (90% mutation recall, zero false positives), default behaviors (adaptive scale, auto-detected dev server, color scheme detection), resource costs (multiple runs increase cost), and the nature of the output (reportId). No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but front-loaded with the core purpose and key options. Every sentence adds value, though a more structured (e.g., bulleted) format could improve readability. It avoids redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters, no output schema, and no annotations, the description is remarkably complete. It covers input alternatives, output (reportId), dependencies (Figma MCP server), default behaviors, and performance guarantees. The only minor gap is the omission of the exact report schema, but that is delegated to sibling tools appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning by grouping mutually exclusive parameters (figma vs designImage, target vs component), explaining defaults, and providing contextual notes (e.g., 'no Figma token needed for designImage'). This goes beyond the schema's field definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: comparing a design against a rendered implementation and returning discrepancies. It specifies two alternative input methods (figma or designImage, target or component) and mentions the output (reportId), distinguishing it from sibling tools like get_diff_report and list_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each parameter combination, including alternatives (e.g., 'Provide figma OR designImage', 'either target OR component'), prerequisites (no Figma token for designImage), and links to sibling tools for further processing. It also explains how to handle authentication via authState.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a stored kiyas report by reportId. Defaults to JSON; pass format=html to fetch the rendered report. Returns the artifact path and (by default for JSON) inline content.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Which artifact to return (default: json) | |
| reportId | Yes | Report ID returned from a prior compare call | |
| includeContent | No | When true, return the raw file content inline. When false, return only the path. Default: true for json, false for html (HTML is large). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It states the default behavior, what is returned (artifact path and inline content), and includes a note about HTML size. This provides adequate transparency for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The main action is front-loaded, followed by specifics. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description partially explains return values (artifact path and inline content) but lacks detail on the structure of the response. For a simple tool with 3 parameters, this is acceptable but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining defaults (format defaults to json) and the conditional behavior of includeContent based on format, which is not in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a stored kiyas report by reportId, with options for format and content inclusion. This distinguishes it from siblings 'compare' (which likely creates reports) and 'list_issues' (which lists issues).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use each format ('Defaults to JSON; pass format=html to fetch the rendered report') and notes that includeContent defaults differ by format. It does not explicitly exclude alternatives but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List discrepancies from a stored kiyas report by reportId, optionally filtered by severity (all | high | medium | low).
| Name | Required | Description | Default |
|---|---|---|---|
| reportId | Yes | Report ID returned from a prior compare call | |
| severity | No | Filter to a single severity level (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes a read operation ('List discrepancies'), but does not disclose side effects, return format, pagination, or limits. For a tool with no output schema, the description should provide more context about what data is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that communicates the tool's purpose, resource, and optional filter without any wasted words. It is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two parameters and no output schema, the description covers most essential information. However, it omits what the returned discrepancies look like (e.g., fields, format) and any pagination or ordering details, leaving some ambiguity. A more complete description would describe the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds minimal extra meaning beyond the schema, such as clarifying that the output is 'discrepancies' and that severity defaults to 'all'. It largely repeats the parameter information, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists discrepancies from a stored kiyas report by reportId, with optional severity filtering. It uses a specific verb ('List') and resource ('discrepancies from a stored kiyas report'), and implies the tool is used after a prior compare call, effectively distinguishing it from siblings like 'compare' and 'get_diff_report'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by mentioning 'stored kiyas report by reportId', indicating a prerequisite. However, it does not explicitly state when to use this tool vs. siblings (e.g., compare, get_diff_report) or provide any exclusion criteria. The usage is implied but not fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0compareget_diff_reportlist_issuesScored across 3 tools
The three tools are clearly distinct: 'compare' creates a new comparison and returns a reportId, 'get_diff_report' retrieves a stored report, and 'list_issues' lists discrepancies from a report. No functional overlap exists.
All tool names follow the verb_noun pattern: 'compare', 'get_diff_report', 'list_issues'. The pattern is consistent across the server.
With 3 tools, the server is well-scoped for its purpose of comparing designs and implementations. Each tool serves a necessary step in the workflow without redundancy.
The tool set covers the complete lifecycle: creating a comparison, retrieving the full report, and listing filtered issues. No obvious gaps for the domain.
On-demand drift checks: declared CSS color, radius, spacing & type vs your own tokens or a pack
Capture screenshots, detect visual regressions between page versions, and analyze with AI.
AI QA tester — real browsers scan sites for bugs, SEO, perf, and accessibility issues via chat.
Score any URL against a real design contract — 42 checks, A-F grade, token + motion validation.
