What can you do with this server?

The Optics MCP Server enables AI agents to interact comprehensively with the Optics Design System through 14 specialized tools and 13 resources. Core Capabilities: * Token Management: Access detailed information about specific design tokens, search by category (color, spacing, typography, border, shadow) or pattern, and view usage statistics across 83 tokens in an HSL-based color system with calc-based spacing (2px-80px) * Component Information: Get detailed specs for any of the 24 available components, list all components, and identify token dependencies * Documentation Access: Search Optics documentation for guidelines and best practices via keyword search or optics:// URI schemes Advanced Features: * Theme Generation: Create custom branded themes with CSS variable overrides and Figma Variables JSON, including installation instructions for @rolemodel/optics via npm or CDN * Code Validation & Migration: Detect hard-coded values (colors, spacing, fonts, borders, shadows) that should use design tokens, automatically replace them, and get intelligent suggestions for legacy code migration with semantic token recommendations * Accessibility Checking: Verify WCAG AA/AAA color contrast ratios between tokens with compliance recommendations * Component Scaffolding: Generate component boilerplate with proper token usage for React, Vue, Svelte, or HTML with TypeScript support * Visual Style Guides: Create production-ready sticker sheets with color swatches, typography specimens, spacing visualizations, and component examples The server includes 5 pre-configured workflow prompts for common design system tasks and provides access to all resources via the optics:// URI scheme.

Which integrations are available for this server?

Provides access to the Optics Design System's HSL-based color tokens, spacing, typography, borders, and shadows, enabling generation of CSS variables and themed styles for web applications. Generates Figma Variables JSON format from custom themes, allowing design tokens to be exported and used in Figma design files. Integrates with GitHub Copilot in Agent Mode to provide Optics design system tools, tokens, and component information directly in VS Code. Generates React component scaffolds pre-configured with Optics design tokens, including TypeScript types and proper token dependencies. Generates Svelte component scaffolds with integrated Optics design tokens and proper styling implementations.

How do I use Optics MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Optics MCP Server show me the color tokens for the primary button component" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Optics MCP Server

by RoleModel

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Optics MCP Server

A Model Context Protocol (MCP) server for the Optics Design System, enabling LLMs to understand and work with design tokens, components, and documentation from https://docs.optics.rolemodel.design.

⚠️ IMPORTANT: Understanding Optics

If you're an AI agent, read SYSTEM_OVERVIEW.md FIRST!

Optics uses a sophisticated HSL-based color system that's different from typical design systems. The system overview explains:

Why there's no --color-primary token (use --op-color-primary-base instead)
The three-layer token architecture (HSL base → Scale → On tokens)
How to find and use the correct tokens
Common mistakes and how to avoid them

Key insight: Optics has 500+ color tokens organized as a predictable scale system, not simple name-value pairs.

Related MCP server: AI-Canvas MCP Server

Overview

This MCP server provides 14 tools and resources for working with the Optics design system:

83 Design Tokens: Real HSL-based colors, calc-based spacing, typography, borders, and shadows
24 Components: All Optics components with accurate token dependencies extracted from SCSS
7 Core Tools: Query tokens, components, and documentation
7 Advanced Tools: Theme generation, validation, accessibility checking, code scaffolding, and style guide generation
5 MCP Prompts: Pre-configured workflows for common design system tasks
Documentation: Design system guidelines and best practices

Architecture

graph TB
    subgraph "MCP Client (AI/LLM)"
        CLIENT[AI Agent/LLM]
    end

    subgraph "Optics MCP Server"
        SERVER[MCP Server<br/>stdio transport]

        subgraph "Resources (13)"
            SYSTEM[optics://system-overview]
            DOC_INTRO[optics://documentation/introduction]
            DOC_START[optics://documentation/getting-started]
            DOC_TOKENS[optics://documentation/design-tokens]
            DOC_COLOR[optics://documentation/color-system]
            DOC_SPACING[optics://documentation/spacing]
            DOC_TYPO[optics://documentation/typography]
            DOC_COMP[optics://documentation/components]
            DOC_A11Y[optics://documentation/accessibility]
            TOK_ALL[optics://tokens/all]
            TOK_COLOR[optics://tokens/color]
            TOK_SPACING[optics://tokens/spacing]
            TOK_TYPO[optics://tokens/typography]
            COMP_ALL[optics://components/all]
        end

        subgraph "Core Tools (7)"
            T1[get_token]
            T2[search_tokens]
            T3[get_token_usage_stats]
            T4[get_component_info]
            T5[list_components]
            T6[get_component_tokens]
            T7[search_documentation]
        end

        subgraph "Advanced Tools (7)"
            T8[generate_theme]
            T9[validate_token_usage]
            T10[replace_hard_coded_values]
            T11[check_contrast]
            T12[suggest_token_migration]
            T13[generate_component_scaffold]
            T14[generate_sticker_sheet]
        end

        subgraph "Prompts (5)"
            P1[start-here]
            P2[get-token-reference]
            P3[component-guide]
            P4[theme-customization]
            P5[migration-guide]
        end

        subgraph "Data Layer"
            TOKENS[83 Design Tokens<br/>HSL colors, spacing,<br/>typography, borders, shadows]
            COMPONENTS[24 Components<br/>with token dependencies]
            DOCS[Documentation<br/>Guidelines & best practices]
        end
    end

    CLIENT -->|JSON-RPC| SERVER
    SERVER --> SYSTEM
    SERVER --> DOC_INTRO
    SERVER --> DOC_START
    SERVER --> DOC_TOKENS
    SERVER --> DOC_COLOR
    SERVER --> DOC_SPACING
    SERVER --> DOC_TYPO
    SERVER --> DOC_COMP
    SERVER --> DOC_A11Y
    SERVER --> TOK_ALL
    SERVER --> TOK_COLOR
    SERVER --> TOK_SPACING
    SERVER --> TOK_TYPO
    SERVER --> COMP_ALL
    SERVER --> T1
    SERVER --> T2
    SERVER --> T3
    SERVER --> T4
    SERVER --> T5
    SERVER --> T6
    SERVER --> T7
    SERVER --> T8
    SERVER --> T9
    SERVER --> T10
    SERVER --> T11
    SERVER --> T12
    SERVER --> T13
    SERVER --> T14
    SERVER --> P1
    SERVER --> P2
    SERVER --> P3
    SERVER --> P4
    SERVER --> P5
    T1 --> TOKENS
    T2 --> TOKENS
    T3 --> TOKENS
    T4 --> COMPONENTS
    T5 --> COMPONENTS
    T6 --> COMPONENTS
    T7 --> DOCS
    T8 --> TOKENS
    T9 --> TOKENS
    T10 --> TOKENS
    T11 --> TOKENS
    T12 --> TOKENS
    T13 --> COMPONENTS
    T14 --> TOKENS
    T14 --> COMPONENTS
    P1 --> SYSTEM
    P2 --> TOKENS
    P3 --> COMPONENTS
    P4 --> T8
    P5 --> T12

Installation

VS Code 🎨

Quick Setup:

Command Palette → MCP: Open User Configuration
Add this configuration:

{
  "servers": {
    "optics": {
      "command": "npx",
      "args": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

Open GitHub Copilot in Agent Mode
Click the tools icon to see Optics tools available

Or create .vscode/mcp.json in your workspace with the same config.

Official MCP Registry: Listed at registry.modelcontextprotocol.io ✅

Cursor 🎯

One-Click Install (click to open Cursor):

cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==

Or Manual Setup:

Open Cursor Settings → MCP
Add this configuration:

{
  "servers": {
    "optics": {
      "command": "npx",
      "args": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

Chat with Cursor AI to access Optics tools

Quick Start (Zero-Install) ⚡

The easiest way to use Optics MCP - no installation required!

Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "optics": {
      "command": "npx",
      "args": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

Claude Code CLI

Add with a single command:

claude mcp add optics -- npx -y optics-mcp

Other useful commands:

# List all MCP servers
claude mcp list

# Remove the Optics server
claude mcp remove optics

# View server details
claude mcp get optics

# Test the connection
claude mcp test optics

That's it! The server runs automatically whenever your MCP client needs it.

Local Installation (For Development)

If you want to modify the server or contribute:

git clone https://github.com/RoleModel/optics-mcp.git
cd optics-mcp
npm install
npm run build

Then configure with the local path:

{
  "mcpServers": {
    "optics": {
      "command": "node",
      "args": ["/absolute/path/to/optics-mcp/dist/index.js"]
    }
  }
}

Usage

Running Directly

npm start

Available Tools (14 Total)

For detailed documentation of all tools, see TOOLS.md.

Core Tools

`get_token`

Get detailed information about a specific design token.

`search_tokens`

Search for design tokens by category or name pattern.

`get_token_usage_stats`

Get statistics about design token usage across the system.

`get_component_info`

Get detailed information about a component including its design token dependencies.

`list_components`

List all available components in the design system.

`get_component_tokens`

Get all design tokens used by a specific component.

`search_documentation`

Search through Optics documentation.

Advanced Tools

`generate_theme`

Create a custom branded theme with CSS variables and Figma Variables JSON.

Outputs HSL-based theme overrides
Generates Figma Variables format
Creates theme preview

`validate_token_usage`

Find hard-coded values in code that should use design tokens.

Detects colors, spacing, fonts, borders, shadows
Suggests token replacements
Validates token usage

`replace_hard_coded_values`

Automatically replace hard-coded values with design tokens.

Manual mode: suggestions only
Autofix mode: applies replacements
Preserves code structure

`check_contrast`

Check WCAG color contrast ratios between tokens.

Supports AA and AAA levels
Works with token names or hex colors
Provides accessibility recommendations

`suggest_token_migration`

Suggest tokens for legacy code migration.

Maps old values to new tokens
Prioritizes semantic tokens
Provides rationale

`generate_component_scaffold`

Generate component code with Optics tokens.

React, Vue, Svelte, HTML support
Pre-configured with design tokens
TypeScript types included

`generate_sticker_sheet`

Generate a visual style guide showing all design tokens and components.

Complete color palettes with swatches
Typography scale examples
Spacing visualizations
Component examples
Multi-framework support (React, Vue, Svelte, HTML)
Production-ready code output

Available Resources

The server exposes the following resources via the optics:// URI scheme:

Documentation

optics://documentation/introduction - Overview of Optics
optics://documentation/getting-started - Getting started guide
optics://documentation/design-tokens - Design token documentation
optics://documentation/color-system - Color system guide
optics://documentation/spacing - Spacing system guide
optics://documentation/typography - Typography guide
optics://documentation/components - Component library overview
optics://documentation/accessibility - Accessibility guidelines

Tokens

optics://tokens/all - All design tokens
optics://tokens/color - Color tokens only
optics://tokens/spacing - Spacing tokens only
optics://tokens/typography - Typography tokens only

Components

optics://components/all - All components

Design System Overview

Design Token Categories

Colors (25 tokens): HSL-based color system with primary, neutral, and alert colors
Spacing (11 tokens): calc-based rem units with base-10 scale (2px to 80px)
Typography (32 tokens): Noto Sans/Serif fonts with sizes, weights, and line heights
Borders (10 tokens): Border radius (small to pill) and widths
Shadows (5 tokens): Elevation system (x-small to x-large)

Components (24 Total)

All components extracted from real Optics SCSS with accurate token dependencies:

Accordion: Collapsible content panel
Alert: Notification messages (warning, danger, info, notice)
Avatar: User profile pictures
Badge: Status indicators and labels
Breadcrumbs: Navigation hierarchy
Button: Interactive buttons with variants
ButtonGroup: Grouped button container
Card: Content containers with elevation
ConfirmDialog: Action confirmation modals
Divider: Content separators
Form: Input fields, textareas, selects
Icon: Material Symbols icons
Modal: Overlay dialogs
Navbar: Top navigation
Pagination: Page navigation
SidePanel: Sliding side panels
Sidebar: Side navigation
Spinner: Loading indicators
Switch: Toggle switches
Tab: Tabbed interfaces
Table: Data tables
Tag: Categorization labels
TextPair: Label-value pairs
Tooltip: Contextual information

Each component specifies which Optics design tokens it uses, making it easy to understand dependencies and maintain consistency.

Development

Build

npm run build

Watch Mode

npm run watch

Project Structure

optics-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   └── optics-data.ts    # Design tokens and component data
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Token Usage Tracking

The server tracks which design tokens are used by each component, enabling:

Dependency Analysis: Understand which tokens a component relies on
Impact Analysis: See which components are affected by token changes
Usage Statistics: Get insights into token usage patterns

Contributing

To add new design tokens or components:

Edit src/optics-data.ts
Add tokens to the designTokens array
Add components to the components array, specifying their token dependencies
Rebuild the project: npm run build

License

MIT

Available Tools

15 tools

check_contrastCheck ContrastC

Check WCAG contrast ratio between two color tokens

ParametersJSON Schema

Name	Required	Description	Default
`foregroundToken`	Yes	Foreground color token name
`backgroundToken`	Yes	Background color token name

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavioral traits. It only states 'check', implying a read operation, but does not clarify whether it modifies state, requires authentication, or has rate limits. A simple verification tool likely has no side effects, but the description fails to confirm this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the purpose with no extraneous information. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain the return value (e.g., ratio number, pass/fail boolean). It does not mention what the output looks like, leaving the agent uncertain about how to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional meaning beyond what the schema provides, aligning with the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and resource ('WCAG contrast ratio between two color tokens'), clearly indicating the tool's function. However, it does not explicitly differentiate from the sibling tool 'validate_color_pair', which could have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description merely states what it does without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_component_scaffoldGenerate Component ScaffoldB

Generate a React component scaffold with proper token usage

ParametersJSON Schema

Name	Required	Description
`componentName`	Yes	Name of the component (e.g., "Alert", "Card")
`description`	Yes	Brief description of the component
`tokens`	Yes	List of token names the component should use

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions 'with proper token usage' but does not explain what that entails—e.g., whether tokens are validated, if existing files are overwritten, or any side effects. This is insufficient for a generation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is front-loaded and free of fluff. Every word contributes to the purpose, with no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool generates a scaffold—an involved operation—yet the description lacks details on output structure, error behavior, or how token usage is enforced. Without an output schema, more explanation is needed for an agent to expect the result correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all three parameters, so the schema already documents their meaning. The description adds no additional parameter-specific context beyond 'with proper token usage,' which is vague. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a React component scaffold, with a specific verb and resource. It distinguishes itself from sibling tools like get_component_info or list_components, which are read-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as list_components or get_component_info. There is no mention of prerequisites, scenarios where it should be avoided, or comparison to related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_sticker_sheetGenerate Sticker SheetC

Generate a visual style guide with color swatches and component examples

ParametersJSON Schema

Name	Required	Description
`framework`	No	Target framework (default: react)
`includeColors`	No	Include color swatches (default: true)
`includeTypography`	No	Include typography specimens (default: true)
`includeComponents`	No	Include component examples (default: true)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must fully disclose behavioral traits. It only states the tool generates output, but does not mention any side effects, authentication needs, or output format. This is insufficient for an agent to fully understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It is efficiently written, though it could benefit from slightly more structure (e.g., listing output items) without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters and no output schema, the description is too brief. It does not explain the output format, behavior when all booleans are false, or any prerequisites. The complexity is not fully addressed, leaving gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all 4 parameters with descriptions. The tool description adds semantic value by linking 'color swatches' and 'component examples' to two of the boolean parameters, but it does not mention includeTypography or the framework parameter. Thus, it provides moderate added meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a visual style guide with specific items (color swatches and component examples). It distinguishes from siblings like generate_theme or generate_component_scaffold, which are more focused. However, the term 'sticker sheet' in the name might cause slight confusion, but overall purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs. alternatives such as generate_theme or generate_component_scaffold. The description does not include any when-to-use, prerequisites, or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_themeGenerate ThemeB

Generate a complete theme with CSS variables and Figma Variables JSON using Optics design tokens

ParametersJSON Schema

Name	Required	Description
`brandName`	Yes	The name of the brand/theme (e.g., "Acme Corp")
`primary`	Yes	Primary brand color (hex, e.g., "#FF5733")
`neutral`	No	Neutral color (hex, optional)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool generates a theme but does not disclose side effects, permission requirements, rate limits, or whether the operation is idempotent. The description lacks behavioral details beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 15 words, efficiently conveying the tool's purpose, output formats, and underlying design system. It is front-loaded and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no output schema, and no annotations, the description is somewhat brief. It specifies output formats but omits information about error handling, constraints on the 'neutral' parameter, and what 'complete theme' entails. The description is adequate but leaves gaps for a comprehensive understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so each parameter is documented. However, the tool description does not add any extra meaning beyond what the schema already provides. It neither clarifies parameter constraints nor explains how they affect the output. The baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Generate' and the resource 'a complete theme', specifying the output formats (CSS variables and Figma Variables JSON) and the design system used (Optics design tokens). This distinguishes it from sibling tools like 'generate_component_scaffold' which focus on components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, use cases, or when not to use it. With several sibling tools, explicit usage context would be helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_component_infoGet Component InfoB

Get detailed information about a component including its design token dependencies

ParametersJSON Schema

Name	Required	Description	Default
`componentName`	Yes	The name of the component (e.g., "Button", "Card", "Input")

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states the purpose without mentioning any side effects, failure modes, or authorization requirements. For a read operation, it minimally implies non-destructive behavior but provides no explicit details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the tool's primary function without unnecessary words. It is highly concise and structurally sound.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, the description should elaborate more on what 'detailed information' includes beyond token dependencies. The presence of a similar sibling (get_component_tokens) further suggests a need for clarity, but the description is adequate for a simple one-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a description for the componentName parameter. The tool description does not add any additional semantic context beyond what the schema already provides, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves detailed component info including design token dependencies, which distinguishes it from siblings like list_components and get_component_tokens. However, it doesn't specify what other details are included, leaving some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like get_component_tokens or list_components. The description lacks context for appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_component_tokensGet Component TokensB

Get all design tokens used by a specific component

ParametersJSON Schema

Name	Required	Description	Default
`componentName`	Yes	The name of the component (e.g., "Button", "Card", "Input")

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It does not disclose what tokens are returned (names, values), any permissions needed, or whether the operation is read-only. The minimal description omits important behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, clear and front-loaded. Efficient but could include more detail without being verbose. Not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter, no output schema, and no annotations, the description should explain what the response contains (e.g., token names and values) and any scope. It is incomplete for a meaningful tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (componentName described). The description adds 'design tokens' context but does not elaborate on parameter format or constraints beyond the schema. Baseline 3 is appropriate as schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and resource 'design tokens used by a specific component'. It distinguishes from siblings like 'get_token' (single token) and 'get_component_info' (component metadata).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as 'get_token' or 'search_tokens'. No when-not-to-use or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tokenGet TokenA

Get detailed information about a specific design token by name

ParametersJSON Schema

Name	Required	Description	Default
`tokenName`	Yes	The name of the design token (e.g., "color-primary", "spacing-md")

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It states 'get detailed information' but does not specify what fields or structure the response contains, leaving the agent uninformed about return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no redundant information, earning its place by being concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should provide more detail about what 'detailed information' entails. It is minimally adequate but leaves room for ambiguity about the response content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the tokenName parameter with examples (100% coverage). The description adds no additional semantic meaning beyond restating 'by name', so it meets the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and resource 'design token', and specifies it is for a specific token by name, distinguishing it from list/search tools like search_tokens.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving details of a single token by name, but provides no explicit guidance on when to use this tool versus alternative tools like search_tokens or get_component_tokens.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_token_usage_statsGet Token Usage StatsB

Get statistics about design token usage across the system

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the purpose, with no mention of side effects, data source, or whether it's read-only. For a tool with no annotations, more transparency is expected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is maximally concise and front-loaded, with no unnecessary words. Every part of the description conveys essential meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is adequate but lacks detail about the return format or what 'statistics' entails (e.g., counts, usage frequencies). Without output schema, the description should clarify expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is effectively 100%. Baseline for zero parameters is 4, and the description adds no param-specific information since none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it gets statistics about design token usage, distinguishing it from other token tools like get_token or search_tokens that serve different purposes. However, it could be slightly more specific about what kind of statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like search_tokens or get_component_tokens. The description simply states the action without providing context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_componentsList ComponentsA

List all available components in the design system

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for behavioral disclosure. It only states the action and resource, but fails to mention potential traits such as pagination, performance considerations, or whether the list is cached. The agent has no information on what the response looks like or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that directly states the tool's purpose with no extraneous words. It is efficiently front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (zero parameters, no output schema), the description minimally covers the tool's purpose. However, it omits any indication of the return format (e.g., list of IDs, names, or full objects). With siblings that provide more detailed information, the agent may need to guess what this tool returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the description does not need to add parameter context. Per the scaling rule, baseline is 4 for zero parameters. The description is adequate for this parameter count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('list') and the resource ('all available components in the design system'), distinguishing it from siblings like get_component_info (which retrieves details of a specific component) and generate_component_scaffold (which creates a new component).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool vs alternatives (e.g., get_component_info). While the purpose is straightforward, an agent might benefit from knowing that this tool returns a full list, whereas other tools serve specific needs like getting details or generating components.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

replace_hard_coded_valuesReplace Hard-Coded ValuesB

Replace hard-coded values with design tokens

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes	Code containing hard-coded values
`autofix`	No	Whether to automatically fix the code (default: false)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, placing full burden on description. It does not disclose whether the tool modifies code in place or returns new code, any side effects, or required permissions. A mutation tool with zero behavioral context is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no waste. Efficient, but slightly too terse given the lack of additional context from annotations or output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations. The description does not explain what the tool returns, how errors are handled, or whether 'autofix' modifies the input code. Incomplete for a mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 no extra meaning beyond the schema fields, which is the baseline for this dimension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Replace') and the target resource ('hard-coded values with design tokens'). It is specific and distinguishes from siblings, which focus on contrast, components, or token search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'suggest_token_migration'. Suggests a replacement operation, but does not specify prerequisites or scenarios where it is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_documentationSearch DocumentationC

Search through Optics documentation

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query for documentation content

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It only states 'Search through Optics documentation' with no disclosure of behavioral traits like being read-only, result format, pagination, or any side effects. The minimal description provides insufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence), which is concise but under-specified. It could include more useful details without increasing length significantly, so it scores as adequate but not exemplary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a simple input schema and no output schema, the description should provide more context about what is searched, how results are presented, and any limitations. The current description is incomplete for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single required parameter 'query' described in the schema as 'Search query for documentation content'. The tool description does not add further meaning beyond the schema, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search through Optics documentation', specifying the action (search) and resource (documentation). It distinguishes from siblings like search_tokens which search for tokens, so the purpose is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as search_tokens or other sibling tools. The description lacks context about scenarios or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tokensSearch TokensA

Search for design tokens by category or name pattern

ParametersJSON Schema

Name	Required	Description	Default
`category`	No	Filter by category (color, spacing, typography, border, shadow)
`namePattern`	No	Search pattern for token names (case-insensitive)

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It does not disclose behavioral traits like whether results are paginated, ordered, or limited. The read-only nature is implied by the word 'search' but not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence containing only essential information. No extraneous words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema or annotations, the description is minimal. It lacks details on return format, result limits, or pagination. For a search tool, this leaves ambiguity about what the agent should expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters (e.g., 'category' lists possible values, 'namePattern' notes case-insensitivity). The tool description merely paraphrases the schema fields without adding new nuance, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Search for design tokens by category or name pattern', specifying the verb and resource. It distinguishes from siblings like 'get_token' (single token) and 'get_component_tokens' (tokens by component).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied via the verb 'search', but no explicit guidance on when to use this tool vs alternatives like 'get_token' or 'get_component_tokens'. No exclusions or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

suggest_token_migrationSuggest Token MigrationA

Suggest design tokens for a hard-coded value

ParametersJSON Schema

Name	Required	Description	Default
`value`	Yes	Hard-coded value to find tokens for (e.g., "#0066CC", "16px")
`category`	No	Optional category filter (color, spacing, typography)

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as whether it reads or mutates data, how it handles unrecognized values, or if it returns a single suggestion or multiple. The read-only nature is implied but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple suggestion tool, but it lacks information about the output format or behavior (e.g., returns a list of suggestions, how suggestions are ranked). No output schema is provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage for both parameters ('value' and 'category'), so the description adds minimal value beyond what the schema already provides. No additional parameter context is given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Suggest design tokens for a hard-coded value' clearly states the action (suggest) and the resource (design tokens) with context (hard-coded value). It distinguishes from siblings like 'search_tokens' and 'get_token'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when a hard-coded value needs a token replacement, but does not specify when not to use it or mention alternatives. No explicit guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_color_pairValidate Color PairC

Check if the pair is meant to be used together

ParametersJSON Schema

Name	Required	Description	Default
`backgroundToken`	Yes	Background color token name
`foregroundToken`	Yes	Foreground color token name

TDQS

C2.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description fails to disclose behavioral traits such as whether the tool performs a read-only check, has side effects, or requires permissions; the minimal wording adds no transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short but at the expense of clarity; it is under-specified and does not effectively communicate the tool's purpose, making it inefficient rather than concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (2 string params, no output schema), the description lacks essential details such as what the return value indicates (e.g., boolean, error) or any behavioral constraints, leaving the agent ill-informed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with clear parameter descriptions ('Background color token name', 'Foreground color token name'), so the description adds no additional meaning beyond what the schema provides; baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Check if the pair is meant to be used together' is vague; it does not specify what constitutes 'meant to be used together' (e.g., contrast ratio, design guidelines) and does not differentiate from the sibling tool 'check_contrast'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'check_contrast'; the description leaves the agent without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_token_usageValidate Token UsageB

Validate code for hard-coded values that should use design tokens

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes	CSS or component code to validate

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must disclose behavioral traits but only says 'Validate', implying read-only analysis. It does not state whether the tool modifies code, returns warnings/errors, or requires any permissions. The agent has no information on side effects or operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core purpose without any wasteful wording. It is front-loaded and immediately understandable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks critical information about the output (e.g., whether it returns a list of issues, warnings, or passes silently). Given the sibling tool set and absence of an output schema, the agent needs to infer behavior, which may lead to incorrect usage or misinterpretation of results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the 'code' parameter with a clear description. The tool description adds the purpose of validating token usage, which provides context beyond the schema. Baseline is 3 due to 100% schema coverage, and the description adds moderate value but does not elaborate on expected input format or validation criteria.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('validate') and resource ('code for hard-coded values that should use design tokens'). It distinguishes from sibling tools like 'validate_color_pair' and 'check_contrast' by focusing on token usage validation vs. color or contrast concerns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., 'replace_hard_coded_values' or 'suggest_token_migration'). The agent is not informed about prerequisites, limitations, or cases where this tool is inappropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

15 tool updatesv0.2.7May 2, 2026
- Changedcheck_contrast2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedgenerate_component_scaffold2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedgenerate_sticker_sheet3 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
  - changedInput schema / properties / framework / description
```
Previous value: -"Target framework: react, vue, svelte, or html (default: react)"New value: +"Target framework (default: react)"
```
- Changedgenerate_theme6 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
  - changedInput schema / properties / brandName / description
```
Previous value: -"Name of the brand/theme (e.g., \"Acme Corp\")"New value: +"The name of the brand/theme (e.g., \"Acme Corp\")"
```
  - addedInput schema / properties / neutral
```
Added value: +{
+  "description": "Neutral color (hex, optional)",
+  "type": "string"
+}
```
  - changedInput schema / properties / primary / description
```
Previous value: -"Primary brand color (hex, e.g., \"#0066CC\")"New value: +"Primary brand color (hex, e.g., \"#FF5733\")"
```
  - removedInput schema / properties / secondary
```
Removed value: -{
-  "description": "Secondary color (hex, optional)",
-  "type": "string"
-}
```
- Changedget_component_info2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedget_component_tokens3 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
  - changedInput schema / properties / componentName / description
```
Previous value: -"The name of the component"New value: +"The name of the component (e.g., \"Button\", \"Card\", \"Input\")"
```
- Changedget_token2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedget_token_usage_stats1 field changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
- Changedlist_components1 field changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
- Changedreplace_hard_coded_values2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedsearch_documentation2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedsearch_tokens2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Changedsuggest_token_migration2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
- Addedvalidate_color_pair
- Changedvalidate_token_usage2 fields changed
  - addedInput schema / $schema
```
Added value: +"http://json-schema.org/draft-07/schema#"
```
  - addedInput schema / additionalProperties
```
Added value: +false
```
14 tool updatesv0.2.6Jan 28, 2026
- First observedcheck_contrast
- First observedgenerate_component_scaffold
- First observedgenerate_sticker_sheet
- First observedgenerate_theme
- First observedget_component_info
- First observedget_component_tokens
- First observedget_token
- First observedget_token_usage_stats
- First observedlist_components
- First observedreplace_hard_coded_values
- First observedsearch_documentation
- First observedsearch_tokens
- First observedsuggest_token_migration
- First observedvalidate_token_usage

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Disambiguation4/5

Most tools have distinct purposes (tokens, components, generation, validation). However, some pairs like check_contrast/validate_color_pair and validate_token_usage/replace_hard_coded_values/suggest_token_migration could cause confusion, though their descriptions clarify differences.

Naming Consistency5/5

All tools use a consistent snake_case verb_noun pattern (e.g., get_token, generate_theme, validate_token_usage). No mixing of styles or irregular names.

Tool Count5/5

With 15 tools, the server covers a broad range of design system tasks without being excessive. Each tool serves a clear purpose, fitting well within the ideal 3-15 range.

Completeness4/5

The surface covers token management (get, search, usage, migration), components (info, list, scaffolding), theme/sticker generation, and validation. Minor gaps exist (no token creation/update, no component deletion) but core workflows are supported.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Reddit Discussion

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Supernova
io.supernova
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Design Tools Documentation Access Developer Tools
1
design-system
app.zaklad
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Design Tools Developer Tools
2
marmo-ui A
io.github.mahmoudilyan
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Design Tools Developer Tools
142
Tseha AFeatured
io.tseha
Serves your design system and coding standards to coding agents, so they stop guessing.
Developer Tools Documentation Access
93

Related MCP Servers

mcpsystem.design MCP Server
Developer Tools Software Architecture Content Management Systems
heyadam
A
license
Not graded
quality
D
maintenance
Provides AI assistants with access to a production-ready design system including Tailwind CSS component patterns, style guides (colors, typography, spacing), and Web Components specifications for consistent UI development.
Updated 3 months ago (2026-06-04 11:52 UTC)
19
MIT
AI-Canvas MCP Server
Design Tools Developer Tools
laoluojuhai
A
license
Not graded
quality
C
maintenance
Enables AI assistants to inspect, modify, export, and validate design documents with 47 tools covering design, code generation, branding, and print/mockup workflows.
Updated 6 months ago (2026-03-18 14:42 UTC)
6
1
MIT
Material 3 MCP Server
Design Tools Documentation Access
weppa-cloud
A
license
A
quality
C
maintenance
Provides AI agents with tools to access Material 3 design components, design tokens, icons, and accessibility guidelines across multiple frameworks.
Updated a year ago (2025-09-30 01:52 UTC)
8
37
6
MIT
web-stylebook-mcp
Design Tools Developer Tools
seungdori
A
license
A
quality
B
maintenance
Provides deterministic, read-only design knowledge for AI coding agents to help them choose visual directions, plan UI states, and compose design tokens, all without network access.
Updated 6 days ago (2026-08-31 02:48 UTC)
6
29
4
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/RoleModel/optics-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Optics MCP Server

⚠️ IMPORTANT: Understanding Optics

Overview

Architecture

Installation

VS Code 🎨

Cursor 🎯

Quick Start (Zero-Install) ⚡

Claude Desktop

Claude Code CLI

Local Installation (For Development)

Usage

Running Directly

Available Tools (14 Total)

Core Tools

get_token

search_tokens

get_token_usage_stats

get_component_info

list_components

get_component_tokens

search_documentation

Advanced Tools

generate_theme

validate_token_usage

replace_hard_coded_values

check_contrast

suggest_token_migration

generate_component_scaffold

generate_sticker_sheet

Available Resources

Documentation

Tokens

Components

Design System Overview

Design Token Categories

Components (24 Total)

Development

Build

Watch Mode

Project Structure

Token Usage Tracking

Contributing

License

Links

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`get_token`

`search_tokens`

`get_token_usage_stats`

`get_component_info`

`list_components`

`get_component_tokens`

`search_documentation`

`generate_theme`

`validate_token_usage`

`replace_hard_coded_values`

`check_contrast`

`suggest_token_migration`

`generate_component_scaffold`

`generate_sticker_sheet`