Which integrations are available for this server?

Integrates with Lit-based web component libraries, allowing AI agents to access component metadata, attributes, events, slots, and CSS parts from the Custom Elements Manifest. Integrates with Stencil-based web component libraries, enabling AI agents to retrieve component APIs and generate accurate code suggestions from the Custom Elements Manifest. Generates Storybook stories for web components based on the Custom Elements Manifest, enabling automated story creation and documentation within Storybook. Integrates with Vaadin web component libraries, providing AI agents with component discovery, metadata, and usage guidance from the Custom Elements Manifest.

How do I use HELiXiR?

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., "@HELiXiR show me the attributes of sl-button" 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.

HELiXiR

by bookedsolidtech

Overview Schema Related Servers Score Discussions

TypeScript

Local

HELiXiR

Give AI agents full situational awareness of any web component library.

Stop AI hallucinations. Ground every component suggestion in your actual Custom Elements Manifest.

npm version npm downloads License: MIT Node 22+ Build Tests MCP Protocol TypeScript Tools

Quick Start · Why HELiXiR · Tools Reference · Configuration · AI Tool Configs

Why HELiXiR

No more hallucinations — AI reads your real component API from the Custom Elements Manifest, not from training data. Every attribute, event, slot, and CSS part is sourced directly from your library.
87+ MCP tools out of the box — Component discovery, health scoring, design token lookup, TypeScript diagnostics, breaking-change detection, Storybook story generation, Shadow DOM styling validators, theme scaffolding, and scaffold/extend tools — all callable by any MCP-compatible AI agent.
Works with any web component framework — Shoelace, Lit, Stencil, FAST, Spectrum, Vaadin, and any library that produces a custom-elements.json CEM file.
Any AI editor, zero lock-in — Claude Code, Claude Desktop, Cursor, VS Code (Cline/Continue), Zed — one config, any tool.

Related MCP server: ds-pilot

Quick Start

Under 60 seconds from zero to a component-aware AI agent.

npm install helixir

Then generate a starter config in your component library:

npx helixir init
# → writes mcpwc.config.json to the current directory

Edit mcpwc.config.json to point at your library:

{
  "cemPath": "custom-elements.json",
  "projectRoot": "/absolute/path/to/your/component-library",
  "componentPrefix": "sl-",
  "tokensPath": "dist/tokens/tokens.json"
}

Add HELiXiR to your Claude Desktop config (see AI Tool Configs for other editors):

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  }
}

Restart Claude Desktop. Done — your AI agent now knows every property, event, slot, CSS part, and design token in your library.

What You Get

Without HELiXiR

You: How do I use sl-button?
Claude: You can use <sl-button> like this:
<sl-button type="primary" color="blue" rounded>Click me</sl-button>
It supports type, color, rounded, icon, and label attributes.

All of that is hallucinated. type, color, rounded, icon, and label are not real attributes on sl-button. The correct attribute for the visual style is variant, and rounded doesn't exist at all.

With HELiXiR

You: How do I use sl-button?
Claude: (calls get_component → sl-button) Here's the accurate API for <sl-button>:
Attributes:
variant — 'default' | 'primary' | 'success' | 'neutral' | 'warning' | 'danger' | 'text' (default: 'default')
size — 'small' | 'medium' | 'large' (default: 'medium')
disabled — boolean (default: false)
loading — boolean — Draws the button in a loading state
outline — boolean — Draws an outlined button
pill — boolean — Draws a pill-style button with rounded edges
href — string | undefined — Renders as <a> when set
Slots: default (button label), prefix (before label), suffix (after label)
Events: sl-blur, sl-focus, sl-invalid
Example:
<sl-button variant="primary" size="medium">Save changes</sl-button>

Every property, event, slot, CSS part, and design token — sourced directly from your Custom Elements Manifest. No hallucinations.

Framework Setup

HELiXiR works with any toolchain that produces a custom-elements.json (CEM). Below are quick-start setups for the most common frameworks.

Shoelace

Shoelace ships custom-elements.json inside its npm package. No build step needed.

npm install @shoelace-style/shoelace

{
  "cemPath": "node_modules/@shoelace-style/shoelace/dist/custom-elements.json",
  "componentPrefix": "sl-"
}

Lit

Use the official CEM analyzer with the Lit plugin:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --litelement --globs 'src/**/*.ts'"

{
  "cemPath": "custom-elements.json",
  "componentPrefix": "my-"
}

Run npm run analyze after each build to keep the CEM current.

Stencil

Enable CEM output in stencil.config.ts:

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [{ type: 'docs-custom' }, { type: 'dist-custom-elements' }],
};

Stencil emits custom-elements.json to your dist/ folder:

{
  "cemPath": "dist/custom-elements/custom-elements.json",
  "componentPrefix": "my-"
}

FAST

FAST components ship with CEM support via the @custom-elements-manifest/analyzer:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --globs 'src/**/*.ts'"

{
  "cemPath": "custom-elements.json",
  "componentPrefix": "fluent-"
}

Adobe Spectrum Web Components

Spectrum Web Components use Stencil under the hood and ship their CEM in the package:

npm install @spectrum-web-components/bundle

{
  "cemPath": "node_modules/@spectrum-web-components/bundle/custom-elements.json",
  "componentPrefix": "sp-"
}

Polymer / Generic Web Components

Any project can add CEM generation with the analyzer:

npm install -D @custom-elements-manifest/analyzer

// package.json scripts
"analyze": "cem analyze --globs 'src/**/*.js'"

{
  "cemPath": "custom-elements.json"
}

Tools Reference

All tools are exposed over the Model Context Protocol. Your AI agent can call any of these tools by name.

Discovery

Tool	Description	Required Args
`list_components`	List all custom elements registered in the CEM	—
`find_component`	Semantic search for components by name, description, or member names (top 3 matches)	`query`
`get_library_summary`	Overview of the library: component count, average health score, grade distribution	—
`list_events`	List all events across the library, optionally filtered by component	`tagName` (optional)
`list_slots`	List all slots across the library, optionally filtered by component	`tagName` (optional)
`list_css_parts`	List all CSS `::part()` targets across the library, optionally filtered by component	`tagName` (optional)
`list_components_by_category`	Group components by functional category (form, navigation, feedback, layout, etc.)	—

Component

Tool	Description	Required Args
`get_component`	Full metadata for a component: members, events, slots, CSS parts, CSS properties	`tagName`
`validate_cem`	Validate CEM documentation completeness; returns score (0–100) and issues list	`tagName`
`suggest_usage`	Generate an HTML snippet showing key attributes with their defaults and variant options	`tagName`
`generate_import`	Generate side-effect and named import statements from CEM exports	`tagName`
`get_component_narrative`	3–5 paragraph markdown prose description of a component optimized for LLM comprehension	`tagName`
`get_prop_constraints`	Structured constraint table for an attribute: union values with descriptions, or simple type info	`tagName`, `attributeName`
`find_components_by_token`	Find all components that expose a given CSS custom property token	`tokenName`
`find_components_using_token`	Find all components referencing a token in their `cssProperties` (works without `tokensPath`)	`tokenName`
`get_component_dependencies`	Dependency graph for a component: direct and transitive dependencies from CEM reference data	`tagName`
`validate_usage`	Validate a proposed HTML snippet against the CEM spec: unknown attrs, bad slot names, enum mismatches	`tagName`, `html`

Composition

Tool	Description	Required Args
`get_composition_example`	Realistic HTML snippet showing how to compose 1–4 components together using their slot structure	`tagNames`

Health

Tool	Description	Required Args
`score_component`	Latest health score for a component: grade (A–F), dimension scores, and issues	`tagName`
`score_all_components`	Health scores for every component in the library	—
`get_health_trend`	Health trend for a component over the last N days with trend direction	`tagName`
`get_health_diff`	Before/after health comparison between current branch and a base branch	`tagName`
`get_health_summary`	Aggregate health stats for all components: average score, grade distribution	—
`analyze_accessibility`	Accessibility profile: ARIA roles, keyboard events, focus management, label support	`tagName` (optional)
`audit_library`	Generates a JSONL audit report scoring every component across 11 dimensions; returns file path (if outputPath given) and summary stats	—

Library

Tool	Description	Required Args
`load_library`	Load an additional web component library by npm package name or CEM path	`libraryId`
`list_libraries`	List all currently loaded web component libraries	—
`unload_library`	Remove a loaded library from memory	`libraryId`

Safety

Tool	Description	Required Args
`diff_cem`	Per-component CEM diff between branches; highlights breaking changes and additions	`tagName`, `baseBranch`
`check_breaking_changes`	Breaking-change scan across all components vs. a base branch with summary report	`baseBranch`

Framework

Tool	Description	Required Args
`detect_framework`	Identifies the web component framework in use from package.json, CEM metadata, and config	—

TypeScript

Tool	Description	Required Args
`get_file_diagnostics`	TypeScript diagnostics for a single file	`filePath`
`get_project_diagnostics`	Full TypeScript diagnostic pass across the entire project	—

Story

Tool	Description	Required Args
`generate_story`	Generates a Storybook CSF3 story file for a component based on its CEM declaration	`tagName`

Bundle

Tool	Description	Required Args
`estimate_bundle_size`	Estimates minified + gzipped bundle size for a component's npm package via bundlephobia/npm	`tagName`

package parameter derivation:

The estimate_bundle_size tool accepts an optional package argument — the npm package name to look up (e.g. "@shoelace-style/shoelace"). When omitted, the tool derives the package name from your componentPrefix config value using a built-in prefix-to-package map:

Prefix	npm Package
`sl`	`@shoelace-style/shoelace`
`fluent-`	`@fluentui/web-components`
`mwc-`	`@material/web`
`ion-`	`@ionic/core`
`vaadin-`	`@vaadin/components`
`lion-`	`@lion/ui`
`pf-`	`@patternfly/elements`
`carbon-`	`@carbon/web-components`

If your prefix is not in the list above and you omit package, the tool returns a VALIDATION error. In that case, pass the package argument explicitly.

Benchmark

Tool	Description	Required Args
`benchmark_libraries`	Compare 2–10 web component libraries by health score, documentation quality, and API surface; returns a weighted score table	`libraries`

CDN

Tool	Description	Required Args
`resolve_cdn_cem`	Fetch and cache a library's CEM from jsDelivr or UNPKG by npm package name (for CDN-loaded libraries)	`package`

Tokens

(Requires tokensPath to be configured)

Tool	Description	Required Args
`get_design_tokens`	List all design tokens, optionally filtered by category (e.g. `"color"`, `"spacing"`)	—
`find_token`	Search for a design token by name or value (case-insensitive substring match)	`query`

TypeGenerate

Tool	Description	Required Args
`generate_types`	Generates TypeScript type definitions (.d.ts content) for all custom elements in the CEM	—

Theme

Tool	Description	Required Args
`create_theme`	Scaffold a complete enterprise CSS theme from the component library's design tokens with light/dark mode variables and color-scheme support	—
`apply_theme_tokens`	Map a theme token definition to specific components, generating per-component CSS blocks and a global `:root` block	`themeTokens`

Scaffold

Tool	Description	Required Args
`scaffold_component`	Scaffold a new web component with boilerplate code based on an existing component's CEM structure	`tagName`

Extend

Tool	Description	Required Args
`extend_component`	Generate extension boilerplate for a web component, providing a subclass with overridable methods and properties	`tagName`

Styling

29 anti-hallucination validators that ground every component styling decision in real CEM data. Run validate_component_code as the all-in-one final check, or use individual tools for targeted validation.

Tool	Description	Required Args
`diagnose_styling`	Generates a Shadow DOM styling guide for a component — token prefix, theming approach, dark mode support, anti-pattern warnings, and correct CSS usage snippets	`tagName`
`get_component_quick_ref`	Complete quick reference for a component — attributes, methods, events, slots, CSS custom properties, CSS parts, Shadow DOM warnings, and anti-patterns. Use as the FIRST call when working with any component	`tagName`
`validate_component_code`	ALL-IN-ONE validator — runs 19 anti-hallucination sub-validators (HTML, CSS, JS, a11y, events, methods, composition) in a single call. Use as the FINAL check before submitting any code	`html`, `tagName`
`styling_preflight`	Single-call styling validation combining API discovery, CSS reference resolution, and anti-pattern detection with inline fix suggestions. Call ONCE before finalizing component CSS	`cssText`, `tagName`
`validate_css_file`	Validates an entire CSS file targeting multiple components — auto-detects component tags, runs per-component and global validation with inline fixes	`cssText`
`check_shadow_dom_usage`	Scans CSS for Shadow DOM anti-patterns: descendant selectors piercing shadow boundaries, `::slotted()` misuse, invalid `::part()` chaining, `!important` on tokens, unknown part names	`cssText`
`check_html_usage`	Validates consumer HTML against a component CEM — catches invalid slot names, wrong enum values, boolean attribute misuse, and unknown attributes with typo suggestions	`htmlText`, `tagName`
`check_event_usage`	Validates event listener patterns against a component CEM — catches React `onXxx` props for custom events, unknown event names, and framework-specific binding mistakes	`codeText`, `tagName`
`check_component_imports`	Scans HTML/JSX/template code for all custom element tags and verifies they exist in the loaded CEM; catches non-existent components with fuzzy suggestions	`codeText`
`check_slot_children`	Validates that children placed inside slots match expected element types from the CEM — catches wrong child elements in constrained slots (e.g. `<div>` inside `<sl-select>`)	`htmlText`, `tagName`
`check_attribute_conflicts`	Detects conditional attributes used without their guard conditions — catches `target` without `href`, `min`/`max` on non-number inputs, and other attribute interaction mistakes	`htmlText`, `tagName`
`check_a11y_usage`	Validates consumer HTML for accessibility mistakes — catches missing accessible labels on icon buttons/dialogs/selects, and manual role overrides on components that self-assign ARIA roles	`htmlText`, `tagName`
`check_css_vars`	Validates CSS for custom property usage against a component CEM — catches unknown CSS custom properties with typo suggestions and `!important` on design tokens	`cssText`, `tagName`
`check_token_fallbacks`	Validates CSS for proper `var()` fallback chains and detects hardcoded colors that break theme switching	`cssText`, `tagName`
`check_composition`	Validates cross-component composition patterns — catches tab/panel count mismatches, unlinked cross-references, and empty containers	`htmlText`
`check_method_calls`	Validates JS/TS code for correct method and property usage — catches hallucinated API calls, properties called as methods, and methods assigned as properties	`codeText`, `tagName`
`check_theme_compatibility`	Validates CSS for dark mode and theme compatibility — catches hardcoded colors on background/color/border properties and potential contrast issues	`cssText`
`check_css_specificity`	Detects CSS specificity anti-patterns — catches `!important` usage, ID selectors, deeply nested selectors (4+ levels), and inline style attributes	`code`
`check_layout_patterns`	Detects layout anti-patterns when styling web component host elements — catches display overrides, fixed dimensions, absolute/fixed positioning, and `overflow: hidden`	`cssText`
`check_css_scope`	Detects component-scoped CSS custom properties set at the wrong scope (e.g. on `:root` instead of the component host)	`cssText`, `tagName`
`check_css_shorthand`	Detects risky CSS shorthand + `var()` combinations that can fail silently when any token is undefined	`cssText`
`check_color_contrast`	Detects color contrast issues: low-contrast hardcoded color pairs, mixed color sources (token + hardcoded), and low opacity on text	`cssText`
`check_transition_animation`	Detects CSS transitions and animations on component hosts targeting properties that cannot cross Shadow DOM boundaries	`cssText`, `tagName`
`check_shadow_dom_js`	Detects JavaScript anti-patterns that violate Shadow DOM encapsulation — catches `.shadowRoot.querySelector()`, `attachShadow()` on existing components, and `innerHTML` overwriting slot content	`codeText`
`check_dark_mode_patterns`	Detects dark mode styling anti-patterns — catches theme-scoped selectors setting standard CSS properties that won't reach shadow DOM internals	`cssText`
`resolve_css_api`	Resolves every `::part()`, CSS custom property, and slot reference in agent-generated code against actual CEM data — reports valid/hallucinated references with closest valid alternatives	`cssText`, `tagName`
`detect_theme_support`	Analyzes a component library for theming capabilities — token categories, semantic naming patterns, dark mode readiness, and coverage score	—
`recommend_checks`	Analyzes code to determine which validation tools are most relevant — returns a prioritized list of tool names without running them all	`codeText`
`suggest_fix`	Generates concrete, copy-pasteable code fixes for validation issues by type (shadow-dom, token-fallback, theme-compat, method-call, event-usage, specificity, layout)	`type`, `issue`, `original`

Configuration

Configuration is resolved in priority order: environment variables > mcpwc.config.json > defaults.

`mcpwc.config.json`

Place this file at the root of your component library project (or wherever MCP_WC_PROJECT_ROOT points).

Key	Type	Default	Description
`cemPath`	`string`	`"custom-elements.json"`	Path to the Custom Elements Manifest, relative to `projectRoot`. Auto-discovered if omitted.
`projectRoot`	`string`	`process.cwd()`	Absolute path to the component library project root.
`componentPrefix`	`string`	`""`	Optional tag-name prefix (e.g. `"sl-"`) to scope component discovery.
`healthHistoryDir`	`string`	`".mcp-wc/health"`	Directory where health snapshots are stored, relative to `projectRoot`.
`tsconfigPath`	`string`	`"tsconfig.json"`	Path to the project's `tsconfig.json`, relative to `projectRoot`.
`tokensPath`	`string \| null`	`null`	Path to a design tokens JSON file. Set to `null` to disable token tools.
`cdnBase`	`string \| null`	`null`	Base URL prepended to component paths when generating CDN `<script>` and `<link>` tags in `suggest_usage` output (e.g. `"https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2/cdn"`). Does not affect `resolve_cdn_cem`. Set to `null` to disable CDN suggestions.
`watch`	`boolean`	`false`	When `true`, HELiXiR automatically reloads the CEM on file changes.
`scoring`	`object`	`undefined`	Optional scoring configuration for customizing health dimension weights. See Configurable Health Scoring Weights.

Full example:

{
  "cemPath": "dist/custom-elements.json",
  "projectRoot": "/home/user/my-design-system",
  "componentPrefix": "ds-",
  "healthHistoryDir": ".mcp-wc/health",
  "tsconfigPath": "tsconfig.build.json",
  "tokensPath": "dist/tokens/tokens.json",
  "cdnBase": "https://cdn.jsdelivr.net/npm"
}

Configurable Health Scoring Weights

Enterprise teams have different priorities. A design system team may weight accessibility at 3× while a rapid-prototyping team may treat it as lower priority. The scoring.weights config section lets you adjust per-dimension weight multipliers:

{
  "scoring": {
    "weights": {
      "documentation": 1.0,
      "accessibility": 1.5,
      "naming": 1.0,
      "apiConsistency": 1.0,
      "cssArchitecture": 1.0,
      "cemSourceFidelity": 0.5
    }
  }
}

Each value is a positive multiplier applied to that dimension's base weight (e.g. 1.5 = 50% more influence; 0.5 = half influence). Omitted keys default to 1.0 (unchanged). Setting a key to 0 or a negative number is rejected with a warning.

Supported keys and their dimensions:

Config Key	Health Dimension	Default Weight
`documentation`	CEM Completeness	15
`accessibility`	Accessibility	10
`typeCoverage`	Type Coverage	10
`apiConsistency`	API Surface Quality	10
`cemSourceFidelity`	CEM-Source Fidelity	10
`testCoverage`	Test Coverage	10
`cssArchitecture`	CSS Architecture	5
`eventArchitecture`	Event Architecture	5
`slotArchitecture`	Slot Architecture	5
`bundleSize`	Bundle Size	5
`storyCoverage`	Story Coverage	5
`naming`	Naming Consistency	5
`performance`	Performance	5
`drupalReadiness`	Drupal Readiness	5

Accessibility-first team example:

{
  "scoring": {
    "weights": {
      "accessibility": 3.0,
      "testCoverage": 2.0,
      "cemSourceFidelity": 0.5
    }
  }
}

Rapid-prototyping team example:

{
  "scoring": {
    "weights": {
      "documentation": 0.5,
      "testCoverage": 0.5,
      "accessibility": 0.5
    }
  }
}

Environment Variables

Environment variables override all config file values. Useful for CI or when pointing the same server at different libraries.

Variable	Overrides
`MCP_WC_PROJECT_ROOT`	`projectRoot`
`MCP_WC_CEM_PATH`	`cemPath`
`MCP_WC_COMPONENT_PREFIX`	`componentPrefix`
`MCP_WC_HEALTH_HISTORY_DIR`	`healthHistoryDir`
`MCP_WC_TSCONFIG_PATH`	`tsconfigPath`
`MCP_WC_TOKENS_PATH`	`tokensPath`
`MCP_WC_CDN_BASE`	`cdnBase`

Set MCP_WC_TOKENS_PATH=null (the string "null") to explicitly disable token tools via env var.

See mcpwc.config.json.example for a ready-to-copy template.

AI Tool Configs

Claude Code (CLI)

Add to .mcp.json in your project root (project-scoped) or ~/.claude.json (global):

Option 1 — Install from npm (recommended)

npx helixir init  # generates mcpwc.config.json in your project root

Then add to .mcp.json:

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  }
}

Option 2 — Install from local clone (development)

git clone https://github.com/bookedsolidtech/helixir.git
cd helixir
pnpm install
pnpm build

Then add to .mcp.json:

{
  "mcpServers": {
    "helixir": {
      "command": "node",
      "args": ["/absolute/path/to/helixir/build/index.js"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  }
}

Reload Claude Code after saving (:mcp to verify the server appears).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

VS Code (Cline / Continue)

Cline — add to .vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "helixir": {
      "command": "npx",
      "args": ["helixir"],
      "env": {
        "MCP_WC_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Continue — add to ~/.continue/config.json under mcpServers:

{
  "mcpServers": [
    {
      "name": "helixir",
      "command": "npx helixir",
      "env": {
        "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
      }
    }
  ]
}

Zed

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "helixir": {
      "command": {
        "path": "npx",
        "args": ["helixir"],
        "env": {
          "MCP_WC_PROJECT_ROOT": "/absolute/path/to/your/component-library"
        }
      }
    }
  }
}

Security

HELiXiR applies defense-in-depth on all inputs that touch the file system or network:

Path containment — all file paths are resolved and verified to stay within projectRoot; .. traversals and absolute paths outside the root are rejected.
Input validation — every tool argument is validated with Zod schemas before reaching handler code; unknown properties are rejected via additionalProperties: false.
CDN safety — resolve_cdn_cem only fetches from allowlisted CDN origins (jsDelivr, UNPKG); arbitrary URLs are not accepted.
No shell execution — the server never spawns subprocesses based on user input; TypeScript diagnostics use the TS compiler API in-process.

See SECURITY.md for the vulnerability disclosure policy.

Quality Gates

Every pull request must pass all five CI checks before merge:

Workflow	What it checks
build	TypeScript type-check + `tsc` compile on Node 22/24
test	Full vitest suite with coverage on Node 22/24
lint	ESLint (TypeScript + Prettier compatibility rules)
format	Prettier formatting check
security	`pnpm audit --audit-level=high`

Pre-commit hooks (via husky + lint-staged):

TypeScript/JavaScript files: ESLint auto-fix → Prettier format
JSON/CSS/Markdown/YAML files: Prettier format
Commit messages: validated by commitlint against conventional-commits format

Allowed commit types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, audit

See CONTRIBUTING.md and LOCAL.md for full setup details.

Compliance

HELiXiR generates a CycloneDX Software Bill of Materials (SBOM) as part of every release. The sbom.json artifact is attached to each GitHub Release and lists all runtime and development dependencies with their versions, licenses, and package identifiers — suitable for enterprise security audits and supply-chain compliance reviews.

Contributing

See CONTRIBUTING.md for guidelines.

Quick steps:

Fork the repo and create a feature branch.
Run pnpm install to install dependencies.
Make your changes in src/.
Run pnpm test to ensure all tests pass.
Run pnpm run lint && pnpm run format:check before submitting.
Open a pull request with a clear description of the change.

Issues and feature requests are welcome on GitHub.

License

Available Tools

79 tools

analyze_accessibilityB

Analyzes the accessibility profile of one or all web components from CEM data. Checks for ARIA roles, aria-* attributes, form association, keyboard events, focus management, disabled state, label support, and accessibility documentation. When libraryRoot is provided alongside tagName, the report is enriched with helix-native AAA evidence (helixMeta, AAA verdict snapshot, source-level signals).

ParametersJSON Schema

Name	Required	Description	Default
`tagName`	No	The tag name of the component to analyze (e.g. "my-button"). Omit to analyze all components.
`libraryRoot`	No	Optional absolute path to the consuming library root. When provided alongside tagName, the response is a HelixAccessibilityReport with the helix-native AAA evidence summary attached. Ignored when tagName is omitted (back-compat).

TDQS

B3.3/5.0

Behavior3/5

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

The description explains the behavioral traits: it checks multiple aspects and enriches output when libraryRoot is provided. However, it does not explicitly state that it is read-only (implied by 'analyzes'), and no annotations are present. Some behavioral aspects like performance or auth requirements are omitted, but the core behavior is sufficiently covered.

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 concise with three sentences. The first sentence establishes the purpose, the second lists specific checks, and the third explains enrichment. It is front-loaded and contains no redundant information.

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 no output schema, the description should explain the return value format. It mentions a 'report' and 'HelixAccessibilityReport' but does not detail what the report contains (e.g., pass/fail, scores, details). Additionally, it lacks guidance on how this tool fits with siblings like check_a11y_usage, leaving gaps for the agent.

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 covers both parameters with descriptions, achieving 100% coverage. The description adds value by explaining the enriched behavior when libraryRoot is provided alongside tagName, and notes that omitting tagName analyzes all components. This goes beyond the schema's basic descriptions.

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 it analyzes accessibility profiles of web components from CEM data and lists specific checks (ARIA roles, attributes, etc.). It distinguishes between analyzing one component or all. However, it does not explicitly differentiate from sibling tools like check_a11y_usage, which may have overlapping but narrower scope.

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. It does not mention prerequisites, when not to use, or context that would help an agent decide between this and related tools like check_a11y_usage or check_color_contrast.

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

analyze_token_canonicalityB

Look up a single token (or every alias in the loaded map) against the helix R-round deprecation history. Returns whether the name is canonical, the canonical replacement, and provenance metadata (R-round, commit, removal version). Backbone of M4 finding generation; expose for ad-hoc consumer queries.

ParametersJSON Schema

Name	Required	Description	Default
`tokenName`	No	CSS variable name (e.g. "--hx-color-border-on-dark-default"). Omit to dump every alias in the map.
`libraryId`	No	Optional library ID for multi-library workspaces (resolved by the dispatcher).

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. It discloses output contents (canonical status, replacement, provenance) but does not mention any behavioral traits such as side effects (e.g., if it modifies state), authentication needs, rate limits, or whether it is read-only. The agent cannot infer safety or permissions from this description.

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 two sentences and front-loads the core action. Every word is functional, with no redundancy. It could be slightly more structured, but overall it's efficient.

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 2 parameters and no output schema, the description explains what it does and what it returns. However, it misses context about prerequisites (e.g., that a token map must be loaded), output format details, and whether pagination or limits apply. The role relative to sibling tools is hinted but not fully contextualized.

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% and both parameter descriptions match the description text exactly (e.g., 'Omit to dump every alias in the map.' is repeated). The description adds no new meaning beyond what the schema already provides, so baseline 3 applies.

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 looks up token canonicality against deprecation history, returns canonical status, replacement, and provenance. It mentions its role as backbone of M4 finding generation and ad-hoc queries. However, it does not explicitly differentiate from siblings like find_token or check_token_fallbacks, which may have overlapping purposes.

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 when needing canonicality info (e.g., for M4 findings or ad-hoc queries), but it does not provide explicit guidance on when to use this tool over alternatives or when not to use it. No exclusions or alternatives are mentioned.

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

apply_theme_tokensA

Map a theme token definition to specific components, showing how to apply it with correct CSS custom property overrides. Accepts a map of CSS variable names to values, then generates per-component CSS blocks and a global :root block. Use this after create_theme to wire your theme tokens to individual component CSS properties.

ParametersJSON Schema

Name	Required	Description
`themeTokens`	Yes	Map of CSS custom property names to their values. E.g. { "--hx-color-primary": "#0066cc", "--hx-spacing-md": "1rem" }. Property names that match component CSS properties generate per-component CSS blocks.
`tagNames`	No	Optional list of component tag names to filter results. When omitted, all components with CSS properties are included.
`libraryId`	No	Optional multi-library dispatch hint. When set, src/mcp/index.ts uses it to pick the correct CEM before invoking this tool.

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses that the tool accepts a map of CSS variable names to values and generates per-component and global CSS blocks. It does not mention side effects, preconditions (e.g., library loaded), or permissions, but the non-destructive nature is implied. Slightly more detail on preconditions would improve transparency.

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 consists of two efficient sentences with no fluff. Every sentence earns its place: first defines the core operation, second gives usage guidance. Well-structured and front-loaded.

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

Completeness4/5

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

Given no output schema, the description could mention the return format (e.g., what the generated output looks like). It says 'generates per-component CSS blocks' but doesn't specify if the return is a string, object, or something else. However, for a mapping tool with good sibling context, it covers most needs. Slightly incomplete on return type.

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%, and the schema already provides detailed descriptions for all three parameters (themeTokens with example, tagNames, libraryId). The description does not add significant meaning beyond the schema, so 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's purpose: 'Map a theme token definition to specific components...generates per-component CSS blocks and a global :root block.' It uses a specific verb (map, generate) and resources (theme token definition, components) and distinguishes from sibling 'create_theme' by indicating it is used after that.

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

Usage Guidelines5/5

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

Explicit guidance: 'Use this after create_theme to wire your theme tokens to individual component CSS properties.' This tells the agent when to use the tool and in what sequence relative to a sibling tool, providing clear usage context.

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

audit_component_with_codexA

Run a structured codex adversarial audit against one component. Caches results by contract-surface hash so unchanged surfaces hit cache instantly; surface changes force a fresh review. Findings reference the helix defect-class corpus (01–14). Use this BEFORE shipping an extending component or migrating between helix versions.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	Custom element tag name (e.g. "hx-button"). Must match a declaration in the loaded CEM.
`force`	No	Skip the cache and force a fresh codex run. Default false. Use when you suspect a stale audit or want a deterministic re-evaluation.
`auditsRoot`	No	Override the audits output directory. Defaults to <projectRoot>/audits/. Use for monorepo setups that prefer per-package audit dirs.
`libraryId`	No	Optional library ID for multi-library workspaces (resolved by the dispatcher).

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains caching behavior ('Caches results by contract-surface hash so unchanged surfaces hit cache instantly; surface changes force a fresh review') and output format ('Findings reference the helix defect-class corpus (01–14)'). This is comprehensive for a read-only audit 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?

The description is two sentences long, front-loaded with the primary purpose, and every sentence adds value. No unnecessary words or redundancy.

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

Completeness4/5

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

The description explains caching, defect corpus, and appropriate usage context. It lacks explicit details about the return value format (since no output schema), but the mention of 'findings referencing defect classes' provides sufficient expectation. Compared to siblings, this is adequately complete.

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 all parameters. The tool description adds minor context (e.g., monorepo usage for auditsRoot) but does not significantly extend meaning beyond the schema's parameter descriptions. 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's action: 'Run a structured codex adversarial audit against one component.' It specifies the verb (run), the resource (one component), and the method (codex adversarial audit). The caching behavior and defect corpus reference further distinguish it from sibling tools.

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

Usage Guidelines4/5

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

The description explicitly advises when to use the tool: 'Use this BEFORE shipping an extending component or migrating between helix versions.' It provides clear context but does not mention when not to use it or suggest alternative tools among the many sibling checks.

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

audit_libraryA

Generates a JSONL audit report scoring every component across all dimensions of the registered scoring system. Returns file path (if outputPath given) and summary stats. Each line is valid JSON for one component.

ParametersJSON Schema

Name	Required	Description
`outputPath`	No	Optional file path (relative to project root) to write the JSONL report to. e.g. "audit/health.jsonl"
`libraryId`	No	The library ID to audit (default: "default").
`libraryRoot`	No	Optional absolute path to the library root. When provided, source-level a11y evidence is collected for every component. Omit for CDN-loaded libraries — source-dependent dims return unknown rather than being scored against unrelated workspace files.

TDQS

A4.2/5.0

Behavior4/5

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

No annotations are provided, so the description fully carries the burden. It discloses output format (JSONL), return values (file path, summary stats), and conditional behavior for libraryRoot parameter (source-level evidence vs unknown). However, it does not explicitly state whether the operation is read-only or has 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 concise with three short sentences. It front-loads the core purpose and output format without unnecessary words. Every sentence adds value.

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

Completeness4/5

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

For a tool with three optional parameters and no output schema, the description adequately covers key behaviors and return values. However, it lacks detail on what 'summary stats' include, which could be clarified.

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?

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the optional outputPath, default libraryId, and the behavioral difference when libraryRoot is provided (source-level a11y evidence). This goes beyond the schema.

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 it generates a JSONL audit report scoring every component across all dimensions. It uses specific verbs and identifies the resource (library) and output format, distinguishing it from sibling tools that focus on individual checks.

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 full library auditing but does not explicitly state when to use this tool versus specific check tools (e.g., check_color_contrast). No when-not-to-use or alternative guidance is provided.

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

benchmark_librariesA

Compares 2-10 web component libraries by normalizing metrics (properties, events, CSS properties, documentation quality, slots) and producing a weighted score and markdown comparison table.

ParametersJSON Schema

Name	Required	Description	Default
`libraries`	Yes	Array of 2-10 libraries to compare.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations exist, so description must disclose behavior. It describes normalizing metrics and producing output but does not mention side effects (e.g., read-only), performance, or required state (e.g., libraries must be loaded). Basic transparency is present but could be enhanced.

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 that is highly efficient and front-loaded with the core action. Every word serves a purpose, no redundancy or filler.

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

Completeness4/5

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

For a tool with one parameter and no output schema, the description covers the operation and output clearly. Lacks mention of prerequisites (e.g., libraries need to be loaded via load_library) but is otherwise complete.

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 covers all parameters with descriptions, so baseline is 3. The description adds context by listing the metrics compared (properties, events, etc.), but this does not directly elaborate on the parameters themselves. No additional parameter-level details beyond schema.

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 it compares web component libraries, normalizes metrics, and produces a weighted score and markdown table. The verb 'compares' and resource 'web component libraries' are specific, and the tool is distinct from sibling tools like check_* or analyze_* which focus on individual aspects.

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?

Description implies usage for comparing libraries but provides no explicit guidance on when to use this tool versus alternatives like analyze_library or check_* tools. No exclusions or prerequisites are mentioned.

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

check_a11y_usageA

Validates consumer HTML for accessibility mistakes when using web components — catches missing accessible labels on icon buttons/dialogs/selects, and manual role overrides on components that self-assign ARIA roles. Run this on any HTML using web components to catch a11y issues.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`htmlText`	Yes	The HTML code to validate for accessibility issues.
`tagName`	Yes	The custom element tag name to check accessibility for (e.g. "sl-icon-button").

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations, the description must disclose behavior. It states validations performed but not the return format or side effects. It implies a read-only check but lacks details on error handling or output structure.

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?

Two sentences, front-loaded with the primary action and key examples. Every sentence adds value; no wasted 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?

While the description adequately covers the tool's purpose, it lacks details on return values or how to interpret results. Given the absence of an output schema, an agent would benefit from more information on the output format.

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?

All parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description adds context to the validation purpose but doesn't enhance parameter semantics beyond the schema.

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 validates consumer HTML for accessibility mistakes in web components, with specific examples (missing labels, role overrides). This distinguishes it from siblings like 'check_html_usage' or 'validate_usage'.

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

Usage Guidelines4/5

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

The description advises to 'Run this on any HTML using web components to catch a11y issues,' providing clear context. It doesn't explicitly mention when not to use or name alternatives, but the context is well-defined.

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

check_attribute_conflictsA

Detects conditional attributes used without their guard conditions — catches "target" without "href", "min"/"max" on non-number inputs, "checked" without type="checkbox", and other attribute interaction mistakes. Parses CEM member descriptions for "Only used when" and "Only applies to" patterns.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`htmlText`	Yes	The HTML code containing the component to check for attribute conflicts.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-button").

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 fully convey behavioral traits. It indicates the tool is a detector (read-only), but does not mention any side effects, permissions, or rate limits. The description is sufficient for basic understanding but lacks depth on non-obvious behavior.

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?

Two sentences convey the core purpose and mechanism efficiently. The first sentence provides a clear action and examples, the second explains the parsing approach. No redundant or extraneous information.

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 explains the detection logic but omits what the tool returns (e.g., list of conflicts, error messages). It does not mention prerequisites or side effects. It is adequate but not comprehensive.

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 baseline is 3. The description adds general context for the tool's operation but does not elaborate on parameter specifics beyond what the schema provides. For example, it does not explain how 'htmlText' should be formatted or what 'tagName' values are valid.

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 detects conditional attributes used without guard conditions, with concrete examples ('target' without 'href', 'min'/'max' on non-number inputs). It also explains the parsing mechanism ('Only used when' patterns). This distinguishes it from sibling tools like check_html_usage, which likely have broader scope.

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 validating attribute interactions in custom elements, but does not explicitly state when to use this tool versus alternatives (e.g., check_html_usage or check_event_usage). No exclusions or context are provided.

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

check_breaking_changesA

Run a breaking-change scan across ALL components in the CEM, comparing the current branch against a base branch. Returns a per-component summary with emoji status indicators.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`baseBranch`	Yes	The git branch or ref to compare against (e.g. "main").

TDQS

A4.1/5.0

Behavior3/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 performs a scan and returns a summary, but lacks details on side effects, permissions, or whether it is read-only. The disclosure is adequate but not comprehensive.

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 two sentences, front-loaded with the action and scope, and contains no unnecessary words. It is efficiently structured.

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

Completeness5/5

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

Given the tool has two parameters, no output schema, and low complexity, the description adequately explains the purpose, scope, and return format. It is complete for an agent to decide to invoke it.

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%, and the description adds minimal new meaning beyond the schema for the two parameters. The baseline 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 tool runs a breaking-change scan across all components in the CEM, comparing branches, and returns a per-component summary with emoji indicators. It distinctly differentiates from sibling tools like 'check_a11y_usage' and 'check_css_vars'.

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

Usage Guidelines4/5

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

The description explicitly indicates the tool is for scanning all components and comparing branches. It does not provide when-not-to-use or alternatives, but the context is clear and distinct from siblings.

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

check_color_contrastA

Detects color contrast issues in CSS: low-contrast hardcoded color pairs (light-on-light, dark-on-dark), mixed color sources (one design token + one hardcoded), and low opacity on text. Catches patterns that break readability across theme changes.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	CSS code to analyze for color contrast issues

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, so the description bears full burden. However, it only describes what the tool detects, not behavioral traits like whether it performs static analysis, returns results, or has any side effects. It lacks disclosure of authentication requirements or rate limits.

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 very concise at two sentences, front-loaded with the main action, and every sentence adds value. No wasted words.

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

Completeness4/5

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

For a tool with one parameter and no output schema, the description provides sufficient context about the types of issues found. However, it lacks information about the output format or return value, which would be helpful for an agent to invoke it 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 single parameter cssText is described in the schema with adequate detail. The description adds context about what issues are detected but does not enhance parameter meaning beyond the schema. With 100% schema coverage, baseline score is 3.

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 specific verb 'Detects' and resource 'color contrast issues in CSS'. It lists three distinct patterns it catches, which differentiates it from sibling tools like check_a11y_usage or check_dark_mode_patterns.

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 context (analyzing CSS for contrast issues) but does not explicitly state when to use this tool over alternatives like check_a11y_usage or check_dark_mode_patterns. No when-not-to-use or exclusion criteria are provided.

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

check_component_importsA

Scans HTML/JSX/template code for all custom element tags and verifies they exist in the loaded CEM. Catches non-existent components and misspelled tag names with fuzzy suggestions. Use this to verify that generated code only references real components.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`codeText`	Yes	The HTML/JSX/template code to scan for custom element tags.

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations provided, the description must fully disclose behavioral traits. It mentions scanning code and catching non-existent/misspelled tags, but does not explain the output format (e.g., list of errors, warnings) or side effects. Lack of output schema further amplifies this gap. The description is adequate but not thorough.

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 concise at two sentences, front-loading the primary action and purpose. It could be slightly more structured (e.g., bullet points), but it is efficient and contains no filler.

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's moderate complexity (2 parameters, no output schema), the description covers main functions and usage context. However, it lacks details on output behavior, error handling, and performance implications. This makes it adequate but not fully complete.

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 covers 100% of parameters with descriptions. The description adds no extra meaning beyond what the schema already provides. Baseline score of 3 is appropriate as the 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 that the tool scans HTML/JSX/template code for custom element tags and verifies their existence in the loaded Custom Elements Manifest (CEM). It also specifies that it catches non-existent components and misspelled tags with fuzzy suggestions. This clearly distinguishes it from sibling tools like check_html_usage or check_composition, making the purpose unmistakable.

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

Usage Guidelines4/5

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

The description explicitly advises using the tool 'to verify that generated code only references real components', which provides clear when-to-use guidance. However, it does not mention when not to use it or compare with alternative tools (e.g., check_html_usage), leaving some room for ambiguity.

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

check_compositionA

Validates cross-component composition patterns — catches tab/panel count mismatches, unlinked cross-references (tab panel="x" without matching panel name="x"), and empty containers (select with no options). Detects component pairs automatically from CEM slot descriptions. Run this on any HTML using compound components like tab-groups, selects, accordions, etc.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`htmlText`	Yes	The HTML code containing compound component patterns to validate.

TDQS

A3.7/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 implies read-only validation but does not explicitly state side effects, permissions, or nondestructive nature. Discloses detection method (CEM slot descriptions) but lacks safety or 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.

Conciseness5/5

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

Three sentences, front-loaded with purpose, no wasted words. Efficiently conveys what the tool does and when to use it.

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 validation tool with no output schema, description explains inputs and validation targets but omits return format (e.g., list of errors) or error handling. Adequate but not fully complete.

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 both parameters described. The tool description adds context about 'compound component patterns' but does not significantly enhance meaning beyond the schema. 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?

Description clearly states the tool validates cross-component composition patterns and lists specific issues (tab/panel count mismatches, unlinked cross-references, empty containers). It distinguishes from sibling tools that focus on other aspects like imports, accessibility, or CSS.

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

Usage Guidelines4/5

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

Explicitly says 'Run this on any HTML using compound components like tab-groups, selects, accordions, etc.' Provides clear context but does not compare to alternatives or state when not to use.

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

check_css_scopeA

Detects when component-scoped CSS custom properties are set at the wrong scope. Catches component tokens placed on :root, html, body, or * selectors instead of on the component host element. Component tokens only take effect when set on the host — setting them on :root has no effect through shadow DOM.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	The CSS code to check for scope mismatches.
`tagName`	Yes	The web component tag name (e.g. "sl-button").

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It explains the detection logic and the shadow DOM rationale. It does not disclose error conditions or output format, but provides sufficient behavioral context for a check 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?

The description is three sentences, each earning its place: purpose, examples, and reason. No fluff, front-loaded with key information.

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

Completeness4/5

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

For a simple check tool with two parameters and no output schema, the description is adequate. It explains what it checks and why, though it could mention the output format for completeness.

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 baseline is 3. The description adds no extra meaning beyond the schema definitions for cssText and tagName, which are already clear.

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 detects when component-scoped CSS custom properties are set at the wrong scope. It specifies exact selectors to check (:root, html, body, *) and explains why (shadow DOM), effectively distinguishing it from sibling tools like check_css_vars or check_css_shorthand.

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

Usage Guidelines4/5

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

The description implies usage for checking CSS scope in web components. It provides clear context for when to use, but lacks explicit guidance on when not to use or alternatives among the many CSS-related sibling tools.

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

check_css_shorthandA

Detects risky CSS shorthand + var() combinations that can fail silently. When var() is mixed with literal values in shorthand properties (border, background, font, margin, etc.), if any var() is undefined the ENTIRE declaration fails — not just the dynamic part. Suggests decomposing into longhand properties.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	The CSS code to check for risky shorthand + var() patterns.

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses the tool's purpose and suggested action but does not mention behavioral traits like read-only status, network usage, or side effects. For a static analysis tool, this is acceptable but not fully transparent.

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 three sentences, front-loaded with the main purpose, and every sentence adds value. No fluff 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?

The description explains the tool's purpose and suggests a recommendation but does not describe the output format or return value. Given no output schema, the agent might benefit from knowing the result structure. However, the description is sufficient for basic 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 single parameter 'cssText' has 100% schema coverage with a clear description. The tool description adds context about what the tool does with the parameter but provides minimal additional 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.

Purpose5/5

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

The description clearly states the tool detects risky CSS shorthand + var() combinations that can fail silently, specifying the resource and action. It distinguishes from siblings like check_css_vars which likely focus on other CSS variable issues.

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

Usage Guidelines4/5

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

The description explains when to use the tool (to detect silent failures from shorthand + var() mixtures) and suggests a remediation (decompose into longhands). It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools provides differentiation.

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

check_css_specificityA

Detects CSS specificity anti-patterns that cause styling issues with web components — catches !important usage, ID selectors targeting components, deeply nested selectors (4+ levels), and inline style attributes. Supports both CSS and HTML mode. Run this on any CSS or HTML to prevent specificity wars.

ParametersJSON Schema

Name	Required	Description	Default
`code`	Yes	The CSS or HTML code to analyze for specificity issues.
`mode`	No	Analysis mode — "css" checks stylesheets for !important/ID/nesting issues, "html" checks for inline style attributes on web components. Defaults to "css".

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses that the tool detects issues and supports two modes, but does not state whether it modifies code, side effects, or performance implications. As a check tool, read-only behavior 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 two sentences, front-loading the main purpose and then listing specifics. Every sentence is meaningful, with no redundancy or fluff.

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

Completeness4/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 params, no output schema, no nested objects), the description covers the key aspects: what it detects, modes, and purpose. It could mention the output type (e.g., list of issues) but is largely complete for a check tool.

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?

Schema coverage is 100%, and the description adds value by explaining that 'code' can be CSS or HTML and that 'mode' defaults to 'css'. It clarifies the meaning of each parameter beyond the schema's brief descriptions.

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 it detects CSS specificity anti-patterns like !important, ID selectors, deeply nested selectors, and inline styles. It specifies that it supports CSS and HTML modes, making its purpose distinct from sibling tools like check_css_scope or check_css_vars.

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?

While it says 'Run this on any CSS or HTML to prevent specificity wars,' it does not provide explicit guidance on when to use this tool versus alternatives (e.g., check_css_scope for scoping issues). No exclusions or when-not-to-use advice given.

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

check_css_varsA

Validates consumer CSS for custom property usage against a component CEM — catches unknown CSS custom properties with typo suggestions, and !important on design tokens (anti-pattern). Run this on any CSS that sets component-scoped custom properties.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to validate for custom property usage.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-button").

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden. It discloses the tool catches unknown custom properties with typo suggestions and flags !important on design tokens as an anti-pattern. It implies a non-destructive validation but doesn't detail side effects or permissions. Still, it adequately describes the tool's behavioral traits.

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 two sentences, each earning its place: the first conveys purpose and key features, the second provides usage context. No superfluous words or repetition. Highly efficient and front-loaded.

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

Completeness4/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, but the description is sufficient for an agent to understand its purpose, inputs, and when to apply it. It covers the core functionality and usage context. While it doesn't specify return format, the validation nature implies a report of issues. Given the tool complexity and sibling count, the description is adequately complete.

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 baseline is 3. The description does not add additional meaning beyond the schema; it mentions 'consumer CSS' and 'component CEM' but doesn't elaborate on parameter details. The schema already adequately documents the three parameters, so the description meets the minimum viable standard.

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 validates CSS for custom property usage against a component CEM, catching unknown properties with typo suggestions and detecting !important on design tokens. It specifies the input (consumer CSS setting component-scoped custom properties) and distinguishes itself from sibling tools like check_css_scope or check_css_shorthand by focusing on custom properties.

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

Usage Guidelines4/5

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

The description explicitly advises when to run this tool: 'Run this on any CSS that sets component-scoped custom properties.' It provides clear context but does not explicitly state when not to use it or mention alternative tools. However, the guidance is sufficient for correct usage.

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

check_dark_mode_patternsA

Detects dark mode styling anti-patterns specific to web components with Shadow DOM. Catches: (1) theme-scoped selectors (.dark, [data-theme], @media prefers-color-scheme) setting standard CSS properties on web component hosts — these won't reach shadow DOM internals, (2) descendant selectors inside theme scopes trying to pierce shadow boundaries. Suggests using CSS custom properties to communicate theme changes through shadow DOM. Run this on any CSS that implements dark mode or theming for web components.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	The CSS code to check for dark mode anti-patterns.

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description elaborates on what the tool checks (two specific anti-patterns) and suggests using CSS custom properties as a solution. This goes beyond a generic statement, though it doesn't cover output format or performance.

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 concise (4 sentences), front-loaded with the main purpose, and every sentence adds value. No waste or redundancy.

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

Completeness5/5

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

Given the tool's simplicity (one parameter, no output schema) and rich examples in the description, it is fully adequate for an agent to understand and invoke the tool 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 sole parameter cssText has a schema description that covers its meaning. The tool description repeats that it's CSS code but adds no new semantics, so the baseline of 3 is appropriate given 100% schema 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 tool detects dark mode styling anti-patterns specific to web components with Shadow DOM, with specific examples of what it catches. This makes its purpose unambiguous and distinct from sibling tools like check_css_scope or check_css_vars.

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

Usage Guidelines4/5

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

The description explicitly says 'Run this on any CSS that implements dark mode or theming for web components,' providing clear usage context. It lacks explicit when-not-to-use or alternative tool mentions, but the guidance is sufficient for typical use.

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

check_event_usageA

Validates event listener patterns against a component CEM — catches React onXxx props for custom events (won't work), unknown event names, misspelled events, and framework-specific binding mistakes. Supports React, Vue, and Angular patterns.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`codeText`	Yes	The code (JSX, template, etc.) to validate event usage in.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-button").
`framework`	No	Optional framework hint. Enables framework-specific checks (e.g. React onXxx prop detection).

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description bears full responsibility. It explains the validation behavior (catches error patterns) but does not disclose non-obvious traits such as whether it modifies state, requires network access, or has side effects. It could mention that the tool is read-only or expect a loaded library.

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 two sentences, front-loading the core action ('validates event listener patterns') and immediately specifying the types of errors caught. Every sentence adds value, with no redundant or filler content.

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

Completeness4/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 could describe return values or response format. It covers the main validation aspects and frameworks but omits what the user gets back (e.g., list of issues). Given the tool's simplicity and clear purpose, the description is largely complete.

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%, so baseline is 3. The description does not add any extra semantics beyond the schema; it only restates the overall purpose without detailing how each parameter influences behavior.

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 validates event listener patterns against a component CEM, listing specific errors it catches (React onXxx, unknown names, misspellings, binding mistakes) and supported frameworks (React, Vue, Angular). It differentiates from sibling tools like check_method_calls or check_html_usage by focusing exclusively on event-related validation.

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

Usage Guidelines4/5

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

The description specifies when to use the tool (for validating event patterns and catching framework-specific mistakes) and lists supported frameworks, but does not explicitly mention when not to use it or provide alternatives among siblings. The context is clear but lacks exclusions.

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

check_html_usageB

Validates consumer HTML against a component CEM — catches invalid slot names, wrong enum attribute values, boolean attribute misuse, and unknown attributes with typo suggestions. Run this on any HTML using web components to catch markup mistakes.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`htmlText`	Yes	The HTML code to validate against the component CEM.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-button").

TDQS

B3.4/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It describes what the tool catches but does not state whether it is read-only or has side effects. Since it is a validation tool, it is likely non-destructive, but that is not explicitly stated. The listed checks provide useful transparency, but safety and side effects are omitted.

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 two concise sentences with no extraneous words. The first sentence efficiently lists what the tool catches, and the second provides usage advice. It is front-loaded with key purpose and features. Slightly more structure (e.g., separating checks and usage) could improve readability, but overall very efficient.

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, the description should explain what the tool returns (e.g., errors list, success message). It does not mention return format or behavior on success/failure. The purpose is clear, but for a validation tool, agents may need to know how to interpret results. Sibling tools likely have similar expectations.

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 all three parameters. The description adds minimal extra meaning beyond mentioning 'consumer HTML', 'component CEM', and 'tag name'. It does not explain libraryId or htmlText further. Baseline 3 is appropriate since schema already describes parameters adequately.

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 validates consumer HTML against a component CEM and lists specific checks (invalid slot names, wrong enum attribute values, boolean attribute misuse, unknown attributes with typo suggestions). It also says to run on any HTML using web components. However, it does not explicitly differentiate from sibling tools like validate_usage or check_slot_children, so it loses a point for lack of sibling distinction.

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 by saying 'Run this on any HTML using web components to catch markup mistakes.' This provides context but no explicit when-to-use or when-not-to-use guidance, nor alternatives. Given the many sibling tools for similar checks, better usage directions would help.

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

check_layout_patternsA

Detects layout anti-patterns when styling web component host elements — catches display overrides (components manage their own display), fixed pixel dimensions (breaks responsive), position absolute/fixed (conflicts with component positioning), and overflow: hidden (clips shadow DOM popups/tooltips). Run this on any CSS that sets layout properties on web components.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	The CSS code to check for layout anti-patterns on web component hosts.

TDQS

A4.3/5.0

Behavior4/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 explicitly lists the anti-patterns detected, making the tool's behavior transparent. It could mention that it is non-destructive, but the listed patterns imply static analysis.

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 followed by an instruction, with no wasted words. Information is front-loaded and efficient.

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 does not explain return values or output format, which is a gap for a detection tool. However, given the simplicity (1 parameter) and lack of output schema, it is minimally adequate but not fully complete.

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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the types of anti-patterns detected, beyond the schema's generic 'CSS code' description.

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 detects layout anti-patterns on web component hosts, listing specific cases (display overrides, fixed dimensions, etc.), which distinguishes it from sibling tools focusing on other CSS aspects.

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

Usage Guidelines4/5

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

The description advises running the tool on CSS that sets layout properties on web components, providing clear usage context. It does not explicitly state when not to use or mention alternatives, but the purpose is specific enough.

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

check_method_callsA

Validates JavaScript/TypeScript code for correct method and property usage on web components — catches hallucinated API calls (methods that do not exist), properties called as methods (e.g. dialog.open() when open is a boolean), methods assigned as properties (e.g. dialog.show = true), and typos with suggestions. Run this on any JS code that interacts with web component APIs.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`codeText`	Yes	The JavaScript/TypeScript code to validate for method/property usage.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-dialog").

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden. It discloses what the tool catches (hallucinated calls, type mismatches, typos) and provides examples. It does not mention side effects, permissions, or output format, but the tool's analytic nature makes this acceptable.

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 two sentences that efficiently convey purpose, examples, and usage guidance. Each sentence adds value; no fluff.

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, the description should explain what the tool returns. It mentions 'catches' issues but does not describe the output format (e.g., list of errors, suggestions). This gap reduces completeness for a validation 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%, so baseline is 3. The description adds minimal extra meaning beyond the schema's parameter descriptions (e.g., libraryId is optional). While it clarifies the role of codeText and tagName, it does not provide significant new information.

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 validates JavaScript/TypeScript code for correct method and property usage on web components, listing specific error types (hallucinated API calls, properties as methods, methods as properties, typos). It distinguishes from sibling tools like check_html_usage or check_event_usage by focusing on method/property correctness.

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

Usage Guidelines4/5

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

The description gives clear context: 'Run this on any JS code that interacts with web component APIs.' It implies appropriate use cases but does not explicitly state when not to use it or list alternatives, though sibling diversity provides implicit differentiation.

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

check_shadow_dom_jsA

Detects JavaScript anti-patterns that violate Shadow DOM encapsulation from consumer code. Catches: accessing .shadowRoot.querySelector() to bypass encapsulation, calling attachShadow() on existing components, setting innerHTML on web components (overwriting slot content), and using style.cssText instead of CSS custom properties.

ParametersJSON Schema

Name	Required	Description	Default
`codeText`	Yes	JavaScript/TypeScript code to analyze
`tagName`	No	Optional tag name of the web component for context-aware checks (e.g., "sl-button")

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses the patterns detected but does not state whether the tool is read-only, what happens on invalid input, or whether it modifies anything. The diagnostic 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 two sentences, listing patterns efficiently without fluff. It is front-loaded with purpose and scope, making it quick to parse.

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 tool has no output schema, so the description should explain return values. It does not mention output format (e.g., list of findings, severity). The listed patterns provide some context but leave the result structure unspecified, making it incomplete.

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%, so the baseline is 3. The description does not add significant meaning beyond the schema; it restates that codeText is code and tagName is optional for context. No additional parameter details are provided.

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 detects JavaScript anti-patterns violating Shadow DOM encapsulation, listing four specific patterns. The verb 'detects' and resource 'JavaScript anti-patterns' are specific, and it distinguishes from sibling tools like check_shadow_dom_usage.

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 is for analyzing consumer code for encapsulation violations, but does not provide explicit when-to-use, when-not-to-use, or alternatives among siblings like check_shadow_dom_usage. Usage context is clear but not comprehensive.

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

check_shadow_dom_usageA

Scans consumer CSS code for Shadow DOM anti-patterns — descendant selectors piercing shadow boundaries, ::slotted() misuse, invalid ::part() chaining, !important on tokens, unknown part names, and typo detection. Run this on any CSS targeting web components to catch mistakes before they reach production.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to scan for Shadow DOM anti-patterns.
`tagName`	No	Optional tag name to scope checks. When provided, enables CEM-based validation (unknown parts, typo detection).

TDQS

A4.3/5.0

Behavior4/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 discloses the types of anti-patterns checked and notes that tagName enables CEM-based validation. However, it does not describe the output format or any side effects, which is a minor gap.

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 two sentences: the first focuses on the tool's function and lists specific anti-patterns, the second provides usage guidance. No redundant words, and it is front-loaded with key details.

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 explain what the tool returns (e.g., a report of issues, pass/fail, etc.). It lists what is checked but not the output format, which is needed for an agent to interpret results. This is a moderate gap.

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?

All three parameters are described in the schema with 100% coverage. The description adds meaning by explaining that tagName enables CEM-based validation (unknown parts, typo detection) and libraryId targets a specific library. This adds value beyond the schema.

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 scans consumer CSS code for Shadow DOM anti-patterns, listing specific issues like descendant selectors, ::slotted() misuse, etc. It distinguishes from siblings like check_shadow_dom_js by focusing on CSS side.

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

Usage Guidelines4/5

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

The description says 'Run this on any CSS targeting web components to catch mistakes before they reach production,' providing clear usage context. It does not explicitly mention when not to use or compare to alternatives, but the context is strong.

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

check_slot_childrenB

Validates that children placed inside a web component's slots match the expected element types from the CEM — catches wrong child elements in constrained slots (e.g. putting a inside which requires ). Parses slot descriptions for "Must be", "Works best with", and "Accepts" patterns.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`htmlText`	Yes	The HTML code containing the component and its children to validate.
`tagName`	Yes	The parent custom element tag name to check slot children for (e.g. "sl-select").

TDQS

B3.4/5.0

Behavior3/5

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

No annotations provided, so the description carries the full burden. It discloses it parses slot descriptions for specific patterns ('Must be', 'Works best with', 'Accepts') and gives an example, but does not cover edge cases, error handling, or performance implications.

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 concise with two sentences, front-loaded with the primary purpose. The first sentence is slightly lengthy but packs necessary details.

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 complexity of slot validation and lack of output schema, the description is reasonably complete, mentioning pattern parsing and example. However, it does not explain return format or success/failure behavior.

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 baseline is 3. The description does not add significant meaning beyond the schema; it reiterates the purpose of the parameters without providing format or syntax details.

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 'validates' and the resource 'children placed inside a web component's slots', with a concrete example. It distinguishes slot validation from sibling tools by focusing on slot children matching CEM types.

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 explicit guidance on when to use this tool versus alternatives. The description implies usage for catching wrong child elements but does not mention when not to use or compare to similar tools like 'check_composition' or 'validate_usage'.

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

check_theme_compatibilityA

Validates consumer CSS for dark mode and theme compatibility — catches hardcoded colors on background/color/border properties, hardcoded shadow colors, and potential contrast issues (light-on-light or dark-on-dark pairings). Does NOT require a CEM — works on any CSS. Run this on styling code to ensure it adapts to theme changes.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to check for theme compatibility issues.

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, but description covers main behavior: validates CSS, detects specific issues. Implies read-only operation (no side effects mentioned). Could add more on error handling or output format, but adequate for a validation 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?

Two sentences, front-loaded with purpose, followed by usage context. No unnecessary words; efficient and clear.

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?

No output schema, but description does not explain what the tool returns (e.g., list of issues, pass/fail, severity). For a validation tool, this is a notable gap. However, complexity is low and parameters are well-documented.

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. Description does not add significant extra meaning beyond the schema; 'cssText' and 'libraryId' are self-explanatory. 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 validates consumer CSS for dark mode and theme compatibility, listing specific checks (hardcoded colors, shadows, contrast). It distinguishes from sibling tools like 'check_color_contrast' and 'check_dark_mode_patterns' by focusing on CSS code validation.

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

Usage Guidelines4/5

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

Provides clear context: 'Run this on styling code to ensure it adapts to theme changes.' Notes it works on any CSS and does not require CEM. Does not explicitly mention when not to use or name alternatives, but context is sufficient for most agents.

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

check_token_fallbacksB

Validates consumer CSS for proper var() fallback chains and detects hardcoded colors that break theme switching. Catches var() calls without fallback values (fragile if token undefined), hardcoded hex/rgb/hsl/named colors on color properties (breaks dark mode), and named CSS colors used directly instead of tokens. Run this on any CSS that references design tokens.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to validate for token fallback usage.
`tagName`	Yes	The custom element tag name to validate against (e.g. "sl-button").

TDQS

B3.4/5.0

Behavior3/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 describes validation and detection of issues, implying a read-only analysis, but does not specify output format, side effects, or whether modifications occur.

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 concise with three sentences: purpose, specific detections, and usage context. It is front-loaded and contains no unnecessary words or redundancies.

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 lack of output schema and the tool's analytical nature, the description should explain what the validation result looks like (e.g., warnings list, pass/fail). It also omits that tagName and cssText are required, which is important for agent usage.

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 baseline is 3. The description adds context about the tool's validation purpose but does not elaborate on parameter meanings beyond the schema. No new parameter semantics are provided.

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 validates CSS for var() fallback chains and detects hardcoded colors that break theme switching, with specific examples. However, it does not explicitly differentiate from sibling tools like check_css_vars or check_dark_mode_patterns, which could overlap.

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 advises to run on any CSS referencing design tokens, providing a clear context. But it lacks explicit when-not-to-use instructions or comparisons to alternatives, leaving some ambiguity among the many sibling tools.

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

check_transition_animationA

Detects CSS transitions and animations on web component hosts that target standard properties which cannot cross Shadow DOM boundaries. Transitions on standard properties (color, background, opacity) only affect the host element box, not the component internals. Use CSS custom properties for animations that the component consumes.

ParametersJSON Schema

Name	Required	Description	Default
`cssText`	Yes	CSS code to analyze
`tagName`	Yes	Tag name of the web component (e.g., "sl-button")

TDQS

A4.2/5.0

Behavior3/5

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. It explains what the tool detects and the implications (transitions affecting only host box), but does not disclose whether the tool is read-only or describe its output format. However, it does not contradict any annotations.

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 three concise sentences. The first front-loads the purpose, the second explains the issue, and the third offers guidance. No wasted words.

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

Completeness4/5

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

Given the 100% schema coverage and lack of output schema, the description provides sufficient context for a detection tool. It explains the problem and recommended practice, but could be more complete by stating what the tool returns (e.g., list of violating properties).

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. The description adds no additional meaning beyond the schema, making a baseline of 3 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 detects CSS transitions and animations on web component hosts targeting standard properties that cannot cross Shadow DOM boundaries. This distinguishes it from sibling tools like check_css_scope or check_css_vars.

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

Usage Guidelines5/5

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

The description explicitly advises when to use the tool (for detecting problematic transitions) and provides an alternative: 'Use CSS custom properties for animations that the component consumes.' This gives clear guidance.

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

create_themeA

Scaffold a complete enterprise CSS theme from the component library's design tokens. Analyzes the CEM to detect the token prefix and categories, then generates a ready-to-customize CSS file with light mode variables, dark mode overrides (via prefers-color-scheme and explicit class), and color-scheme declarations. Returns the full CSS content and per-category token counts.

ParametersJSON Schema

Name	Required	Description
`themeName`	No	Name for the theme (used in CSS class selectors). E.g. "brand" generates ".brand-light" and ".brand-dark". Defaults to "theme".
`prefix`	No	Override the CSS custom property prefix detected from the CEM. E.g. "--hx-". When omitted, the prefix is detected automatically.
`libraryId`	No	Optional multi-library dispatch hint. When set, src/mcp/index.ts uses it to pick the correct CEM before invoking this tool. Schema-aware MCP clients must allow it through to support multi-library projects.

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description discloses that it analyzes the CEM for token prefix and categories, generates CSS with light/dark mode variables, and returns full CSS content and token counts. It does not mention side effects or permissions, but the behavior is transparent.

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?

Two sentences are efficiently packed with information. The first sentence states the high-level purpose, the second details output and behavior. No wasted words, and it is front-loaded.

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

Completeness5/5

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

Given the complexity of scaffolding a theme, the description covers inputs (parameters), process (analyzes CEM, generates CSS), and outputs (CSS content, token counts). Without an output schema, it adequately explains return values.

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?

Schema coverage is 100%, providing baseline 3. The description adds value by explaining parameter usage: themeName generates class selectors (e.g., 'brand'), prefix overrides detection, and libraryId is for multi-library dispatch. This adds context beyond schema.

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: 'Scaffold a complete enterprise CSS theme from the component library's design tokens.' It specifies the output (CSS file with light/dark modes) and differentiates from siblings like apply_theme_tokens which applies tokens.

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

Usage Guidelines4/5

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

The description implies when to use the tool (for initial scaffolding) but does not explicitly state when not to use it or compare with alternatives. However, the purpose is clear enough given the sibling context.

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

detect_frameworkA

Identifies which web component framework the project uses by inspecting package.json dependencies, CEM metadata, and config files. Returns the framework name, version, CEM generator, and regeneration notes.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It discloses the inspection approach and return fields, but does not explicitly state that the tool is read-only or has no side effects. However, 'inspects' implies read-only, so it is minimally transparent.

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 two sentences, front-loading the purpose and method. Every sentence provides essential information without redundancy.

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

Completeness4/5

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

Given no parameters, no output schema, and no annotations, the description covers the essential inputs and outputs. It could mention return value formatting or any preconditions, but overall it is complete enough for a simple detection tool.

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?

There are no parameters, and schema coverage is 100% (trivially). The description adds value by explaining what the tool inspects and returns, which goes beyond the empty schema. Baseline is 4, which 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 specifies the tool's function: identifying the web component framework. It uses a specific verb ('Identifies') and resource ('web component framework'), and distinguishes itself from sibling detection tools like detect_helix_evidence and detect_theme_support.

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 framework detection but does not explicitly state when to use it over alternatives or provide exclusions. The context of inspecting package.json, CEM, and config files gives some guidance, but no direct comparison to siblings.

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

detect_helix_evidenceA

Detect helix-native AAA evidence (helixMeta in CEM, aaa-verdicts.json snapshot, AAA-AUDIT.md sidecar, source-level signals) for a single tagName. Returns the raw HelixAaaEvidence object — useful for surfacing the same evidence helixir scores against (Storybook a11y card, readiness pipeline).

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	The tag name of the component to inspect (e.g. "hx-button").
`libraryRoot`	No	Absolute path to library root; if omitted, source-level checks are skipped (verdict snapshot from helixMeta only).
`libraryId`	No	The library ID to scope CEM lookups (default: "default").

TDQS

A4.2/5.0

Behavior3/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 operation is 'Detect' and discusses parameter effects (e.g., skipping source-level checks if libraryRoot omitted), but it does not disclose safety profile (non-destructive), error conditions, or side effects. The description is adequate but lacks depth.

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 concise, consisting of two sentences that efficiently convey purpose, inputs, output, and usage context. No extraneous information, and key details are front-loaded.

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

Completeness4/5

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

Given the tool's complexity (detecting evidence from multiple sources) and the absence of an output schema, the description adequately covers the main behavior, inputs, and intended use. It could benefit from more detail about the return structure, but the provided context is sufficient for most use cases.

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?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaningful context beyond the schema, such as explaining that omitting libraryRoot skips source-level checks and specifying the default for libraryId. This additional information enhances understanding.

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 ('Detect helix-native AAA evidence'), the resource ('for a single tagName'), and the output ('Returns the raw HelixAaaEvidence object'). It distinguishes from sibling tools by specifying the exact type of evidence and context (helixMeta in CEM, aaa-verdicts.json, etc.), which is unique among the many sibling tools.

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

Usage Guidelines4/5

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 the tool ('for a single tagName') and its utility ('useful for surfacing the same evidence helixir scores against (Storybook a11y card, readiness pipeline)'). However, it does not explicitly state when not to use it or mention alternatives, leaving room for improvement.

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

detect_theme_supportA

Analyzes a component library for theming capabilities — token categories (color, spacing, typography, etc.), semantic naming patterns, dark mode readiness, and coverage score. Library-wide analysis, not per-component.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description bears full responsibility. It discloses the scope of analysis (token categories, naming, dark mode, coverage score) but does not state whether the tool is read-only, has side effects, requires authentication, or has rate limits. The behavior is adequately described for a static analysis tool, but lacks depth on output format or potential mutations.

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 two sentences: the first front-loads the main action and key details, the second clarifies scope. Every sentence adds value, and there is no redundancy or fluff.

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

Completeness4/5

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

Given the tool has one optional parameter, no output schema, and no annotations, the description sufficiently covers its purpose and scope. It lists what is analyzed, giving a good idea of expected output. However, it could be slightly more complete by explicitly stating the output is a report or score, but the current level is nearly complete for a simple analysis 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 one optional parameter with 100% schema coverage, where the schema description already explains its purpose ('Optional library ID to target a specific loaded library instead of the default'). The tool description adds no additional semantic information beyond the schema, so a 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 tool 'Analyzes a component library for theming capabilities' and lists specific aspects: token categories, semantic naming patterns, dark mode readiness, and coverage score. It explicitly says 'Library-wide analysis, not per-component', distinguishing it from per-component sibling tools like 'check_dark_mode_patterns' or 'analyze_token_canonicality'.

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 library-level theming analysis and explicitly warns against per-component use, but does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives like 'analyze_accessibility' or 'analyze_token_canonicality'. It lacks exclusion criteria or alternative recommendations.

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

diagnose_stylingA

Generates a Shadow DOM styling guide for a web component — token prefix, theming approach, dark mode support, anti-pattern warnings, and correct CSS usage snippets. Use this before writing any component CSS to prevent Shadow DOM mistakes.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name to diagnose (e.g. "sl-button").

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description fully discloses the generated guide's contents (token prefix, theming, dark mode, anti-patterns, snippets), giving adequate behavioral context for a diagnostic tool. No side effects or destructive actions are implied.

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?

Two sentences: first clearly defines output, second gives usage context. Every word adds value; no fluff or redundancy.

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

Completeness4/5

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

Given no output schema, the description sufficiently describes the output structure. It could mention error cases (e.g., missing tagName) but is otherwise complete for a diagnostic guide.

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%, so the description adds minimal value beyond default schema descriptions. It provides an example tagName ('sl-button'), which is helpful but not essential.

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 it 'Generates a Shadow DOM styling guide' and lists specific elements (token prefix, theming approach, dark mode support, anti-pattern warnings, CSS snippets), distinguishing it from sibling tools that perform specific checks rather than generating a comprehensive guide.

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

Usage Guidelines4/5

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

The description explicitly says 'Use this before writing any component CSS to prevent Shadow DOM mistakes,' providing clear when-to-use guidance. It does not explicitly state when not to use, but the sibling tools cover alternative use cases.

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

diff_cemA

Compare a component's CEM metadata between the current branch and a base branch, reporting breaking changes (removals, type changes) and non-breaking additions.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The HTML tag name of the component to diff (e.g. "my-button").
`baseBranch`	Yes	The git branch or ref to compare against (e.g. "main").

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided. The description implies a read-only diff operation but does not explicitly state mutability, permissions, or other behavioral traits. It covers the basic behavior of comparison and reporting.

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 that front-loads the key purpose. It is efficient but could benefit from minor structural improvements for readability.

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 lacks details on output format or error handling, which would be helpful given the absence of an output schema. It is adequate for a tool with moderate complexity.

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 parameter descriptions. The tool description does not add significant meaning beyond the schema. 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 compares a component's CEM metadata between branches and reports specific change types (breaking and non-breaking). It uses a specific verb and resource, and the scope 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 Guidelines3/5

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

The description explains what the tool does but does not provide guidance on when to use it versus siblings like check_breaking_changes. No exclusions or alternatives are mentioned.

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

estimate_bundle_sizeA

Estimate the bundle size (minified + gzipped) for a web component or its parent npm package. Queries bundlephobia and the npm registry. Results are cached in memory for 24 hours.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	The custom element tag name, e.g. "sl-button".
`package`	No	Optional: explicit npm package name (e.g. "@shoelace-style/shoelace"). If omitted, the package is derived from componentPrefix in your config using a built-in prefix→package map (e.g. "sl"→"@shoelace-style/shoelace", "fluent-"→"@fluentui/web-components", "mwc-"→"@material/web", "ion-"→"@ionic/core", "vaadin-"→"@vaadin/components", "lion-"→"@lion/ui", "pf-"→"@patternfly/elements", "carbon-"→"@carbon/web-components"). If your prefix is not in this list, you must provide the package explicitly — omitting it will return a VALIDATION error.
`version`	No	Package version to look up. Defaults to "latest".
`include_full_package`	No	When false, suppresses the full_package size from the result. Defaults to true.

TDQS

A4.1/5.0

Behavior3/5

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

The description mentions caching (24-hour in-memory) and queries to bundlephobia/npm registry, but omits details like network dependency, latency, or error handling. With no annotations, the description provides partial transparency.

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?

Two concise, well-structured sentences with no fluff. Key information is front-loaded and every sentence adds value.

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

Completeness4/5

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

The tool is well-described for its purpose, but lacks details on the return value structure (e.g., whether result includes only sizes or other metadata). Given no output schema, the description could clarify the output format fully.

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

Parameters5/5

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

The description adds significant value beyond the schema: explains tagName→package derivation, lists prefix mappings, warns about validation errors, and clarifies defaults for version and include_full_package. Schema coverage is 100%, and the description enhances usability.

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 estimates bundle size (minified + gzipped) for web components or npm packages, distinct from sibling tools which focus on accessibility, styling, or component analysis.

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?

No explicit when-to-use or when-not-to-use guidance is provided. Usage is implied by the task but no alternatives or exclusions are mentioned, leaving the agent to infer context.

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

extend_componentA

Generates a properly subclassed TypeScript component extending an existing web component. Produces the correct inheritance chain (class NewClass extends ParentClass), CEM @customElement annotation, CSS part forwarding guidance (exportparts), inherited slot documentation, TypeScript HTMLElementTagNameMap declaration, and Shadow DOM style encapsulation warnings. Prevents common extension anti-patterns such as broken inheritance chains, missing exportparts declarations, and style isolation surprises.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`parentTagName`	Yes	Tag name of the existing parent component to extend (e.g. "hx-button").
`newTagName`	Yes	Tag name for the new subclass component (e.g. "my-custom-button"). Must contain a hyphen.
`newClassName`	No	Optional explicit class name for the new subclass. Defaults to PascalCase derived from newTagName (e.g. "MyCustomButton").

TDQS

A3.6/5.0

Behavior3/5

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

The description details what is generated and prevented, but lacks information on side effects (e.g., file modifications), permissions, or whether it returns code or modifies existing files. Annotations are absent, so description carries full burden.

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 paragraph, front-loaded with key action, lists outputs and then prevention. Efficient but slightly dense.

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?

Adequately describes generated artifacts, but lacks details on output format (e.g., code block vs. inline) and how to use the result, especially given no output schema.

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?

Schema covers all 4 parameters with descriptions (100% coverage). The description adds minimal extra value for newClassName (default PascalCase derivation), but otherwise reinforces schema info.

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 states it 'Generates a properly subclassed TypeScript component extending an existing web component' and lists specific outputs (inheritance chain, CEM annotation, CSS part forwarding, etc.), clearly distinguishing it from analytical sibling tools.

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 vs. alternatives, no prerequisites mentioned, and no context for when not to use it.

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

find_componentA

Semantically search for components by name, description, or member names using token-overlap scoring. Returns the top 3 matches with scores above zero.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`query`	Yes	Search query to match against component tag names, descriptions, and member names.

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description discloses key behavioral details: uses token-overlap scoring, returns top 3 matches with scores above zero. This is sufficient for a read-only search tool, though precise scoring mechanism could be expanded.

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?

Two sentences efficiently convey purpose, method, and output constraints. No redundant information; every word contributes to clarity.

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

Completeness4/5

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

Description specifies input and output (top 3 matches with scores >0) but omits details on the structure of matches (e.g., fields returned). Still, it provides essential context for an agent to invoke the tool correctly.

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?

Schema coverage is 100%, but the description adds context: query matches against tag names, descriptions, and member names. This enriches understanding beyond the schema's parameter descriptions, which are already clear.

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 it performs semantic search on components by multiple fields using token-overlap scoring, and distinguishes from sibling tools like find_components_by_token or list_components by specifying the search method and result criteria.

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 use for fuzzy semantic matching but does not explicitly contrast with alternative search tools (e.g., exact match, listing). No when-not-to-use scenarios or prerequisites are mentioned.

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

find_components_by_tokenA

Find all components that expose or use a given CSS custom property token. Returns tagName, token description, and default value for each match.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tokenName`	Yes	CSS custom property name (must start with "--", e.g. "--sl-color-primary-600")
`partialMatch`	No	If true (default), match any token containing tokenName as a substring.

TDQS

A3.5/5.0

Behavior3/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 discloses the return fields but does not explicitly state it is read-only or mention any side effects, permissions, or limitations.

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?

Two sentences concisely state purpose and output fields without redundancy or fluff.

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

Completeness4/5

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

The description adequately explains the tool's purpose and output, given no output schema. However, it could mention order or completeness of results.

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?

Schema covers all parameters, and the description adds value beyond the schema by specifying the token name format (must start with '--') and the default for partialMatch.

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 it finds components using a CSS custom property token and specifies the returned fields. However, it does not differentiate from the sibling 'find_components_using_token', which may be redundant.

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 'find_components_using_token' or 'find_token'. The description lacks usage context.

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

find_components_using_tokenA

Find all components that reference a given CSS custom property token in their cssProperties array. Useful for impact analysis before renaming or removing a design token. Works without tokensPath configured.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tokenName`	Yes	CSS custom property token name to search for (e.g. "--color-primary-500").
`fuzzy`	No	When true, supports wildcard (*) and substring matching (default: false).

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It states the search domain (cssProperties array) and a condition (works without tokensPath). It implies a read operation but does not detail behavior on empty results or error handling. Still fairly transparent.

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?

Three concise sentences, front-loaded with purpose, followed by use case and a clarifying condition. No wasted 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?

Lacks output schema and does not describe return format (e.g., list of component names or IDs). For an impact analysis tool, knowing what information is returned is important. No mention of errors or performance. Could be more complete given the complexity of the search.

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 each parameter described. The description adds minimal extra value; it reinforces tokenName purpose and fuzzy matching but does not significantly enhance understanding beyond the schema.

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 the verb (find), resource (components referencing a token), and context (impact analysis). It also differentiates by noting it works without tokensPath configured, distinguishing it from potential siblings like find_components_by_token.

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

Usage Guidelines4/5

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

Specifies the use case: 'impact analysis before renaming or removing a design token.' However, it does not explicitly mention when not to use or list alternative tools, but the context is clear.

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

find_tokenA

Find design tokens by name pattern or value using a case-insensitive substring match. Requires tokensPath to be set in mcpwc.config.json or MCP_WC_TOKENS_PATH.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	The search string to match against token names and values (case-insensitive substring match).

TDQS

A3.5/5.0

Behavior3/5

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

No annotations provided, so the description carries full burden. It discloses the case-insensitive substring match behavior and a configuration requirement, but does not describe return values, error handling, or 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 extremely concise: two sentences, no waste. The main action is 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 low complexity, the description is mostly adequate but fails to hint at the return format. This is a gap for agent expectations.

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% for the single parameter, and the tool description adds no additional semantic value beyond what is already in 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 finds design tokens by name pattern or value using case-insensitive substring match. It specifies the resource (design tokens) and action, but does not explicitly distinguish it from sibling tools like find_components_by_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 mentions a prerequisite (tokensPath configuration), which provides some usage context. However, it does not specify when to use this tool over alternatives or when not to use it.

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

generate_importA

Generates import statements for a component based on the CEM exports and package.json. Returns both a side-effect import and a named import.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").

TDQS

A3.8/5.0

Behavior3/5

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

No annotations exist, so description carries full burden. It discloses that the tool uses CEM exports and package.json, and returns two types of imports. However, it does not mention if the tool modifies state, requires a loaded library (implied by libraryId), or any side effects. The behavior is partially transparent but lacks detail on prerequisites or consequences.

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?

Two sentences, no filler. The first sentence states the core action, and the second specifies the return format. Every word earns its place, and the structure front-loads the key purpose.

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

Completeness4/5

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

For a simple generation tool, the description covers the return value (side-effect and named import) and data sources. No output schema exists, so this provides necessary context. It could be improved by clarifying the role of libraryId, but given that is in the schema, the description is nearly complete.

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 covers 100% of parameters with descriptions. The description does not add new meaning beyond what the schema provides for the parameters; it only mentions the general data sources. Baseline 3 is appropriate as schema already documents parameters adequately.

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 import statements for a component based on CEM exports and package.json, and specifies the return type (side-effect and named import). This distinguishes it from sibling tools like check_component_imports, which checks imports rather than generating them.

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 when to use (when needing import statements) but does not explicitly state when not to use or mention alternatives among the many sibling tools. No comparison or exclusion criteria are provided, leaving the agent to infer usage context.

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

generate_storyA

Generates a Storybook CSF3 story file for a web component based on its CEM declaration. Returns TypeScript source ready to paste into a .stories.ts file, with argTypes, default args, a render function, and named story exports for each variant value.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").

TDQS

A4.2/5.0

Behavior4/5

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

No annotations are provided, so the description bears the full burden. It discloses that the tool returns TypeScript source ready to paste, and lists the structural elements included (argTypes, default args, render function, named exports). This gives a good behavioral expectation without mentioning side effects (likely none) or auth. The level of detail is appropriate 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?

The description consists of two well-structured sentences. The first sentence states the primary purpose, and the second elaborates on the output content. Every word earns its place; there is no redundancy or fluff. It is front-loaded with the core action.

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

Completeness4/5

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

Given the tool's moderate complexity (generates text output from two parameters), the description is largely complete. It explains the output format and includes details about the content. However, it does not mention whether a library must be loaded first (implied by the optional libraryId), which could be considered a slight gap. The absence of an output schema is compensated by the detailed description.

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 rephrases their purpose: 'libraryId' is optional and targets a specific library, 'tagName' is the custom element tag. This adds minimal extra meaning beyond the schema, so 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 uses a specific verb 'Generates' and clearly identifies the resource as 'Storybook CSF3 story file for a web component based on its CEM declaration'. The output is detailed (TypeScript source with argTypes, default args, render function, named story exports). This distinguishes it from sibling tools like generate_import and generate_types, which have different outputs.

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

Usage Guidelines4/5

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

The description implicitly states usage: when you need to generate a Storybook story from a component's CEM data. It does not explicitly exclude conditions or mention alternatives, but the context is clear enough for an AI agent to infer appropriate use. No sibling tool generates stories, so no confusion.

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

generate_typesA

Generates TypeScript type definitions (.d.ts content) for all custom elements in the CEM. Attribute interface property names are sourced from the CEM attribute field (the HTML attribute name), not the JavaScript property name, ensuring the output accurately reflects the component API. Returns a string ready to save as helix.d.ts or similar.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided, so description carries burden. It mentions the output reflects component API accurately and is ready to save, but does not disclose error handling, side effects (it generates, likely safe), or performance considerations.

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?

Two sentences efficiently cover main purpose and key output detail. No wasted words; front-loaded with action verb and resource.

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

Completeness4/5

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

Without output schema, description adequately indicates return is a string ready for a file. Simple tool with one optional param; no missing context critical for use.

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% for the only parameter (libraryId). Description does not add meaning beyond the schema; it references 'all custom elements' but does not tie to the parameter.

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?

Clearly states it generates TypeScript type definitions (.d.ts) for custom elements, with specific detail about attribute naming from CEM. Distinguishable from siblings as no other tool generates type definitions.

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 vs alternatives, no prerequisites or when-not-to-use indications. The tool is isolated among many siblings but conditions of use are not described.

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

get_componentA

Get full metadata for a web component by tag name, including members, events, slots, CSS parts, and CSS properties.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided. The description declares the tool returns 'full metadata' but does not disclose potential errors (e.g., missing tag), behavior with default vs. explicit library, or if any side effects exist. Adequate but unexceptional.

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 of 18 words, front-loaded with action and resource. No redundant content. Efficient.

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

Completeness4/5

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

No output schema, so description must explain return content. It lists key categories (members, events, etc.), which covers the main expected output. However, lacks mention of attributes or description field, and could better differentiate from siblings. Still fairly complete for a simple retrieval 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?

Input schema has 100% coverage with clear parameter descriptions. The tool description adds no extra meaning beyond what's already in the schema (e.g., it just restates 'tag name'). 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?

The description clearly states the verb 'Get' and resource 'full metadata for a web component', and enumerates specific categories (members, events, etc.). It distinguishes from sibling tools that retrieve specific aspects (e.g., list_events, get_component_dependencies).

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 the many specialized siblings (e.g., get_component_dependencies, list_slots). The agent is left to infer that this returns everything, but no explicit when/when-not or alternative suggestions.

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

get_component_dependenciesA

Returns the dependency graph for a component — direct dependencies (components it renders) and transitive dependencies (full tree). Requires a CEM built with dependency reference data.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name to inspect (e.g. "my-dialog").
`includeTransitive`	No	When true (default), resolves the full transitive dependency tree.

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations, the description carries the burden for behavioral disclosure. It discloses the requirement for dependency reference data and mentions direct vs transitive dependencies. However, it omits details like response format, error conditions, or performance considerations, leaving gaps for the agent.

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?

Two concise sentences with no unnecessary words. The first sentence states the main function, and the second adds a critical requirement. It is front-loaded and efficient.

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?

While the description explains what the tool does and its prerequisite, it lacks information about output format (e.g., graph structure, nodes/edges). Given the absence of an output schema, the agent would benefit from knowing how the dependency graph is represented. The description is adequate but not fully complete.

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%, so the schema documents all three parameters. The description does not add additional semantic meaning beyond what the schema provides. For instance, it doesn't clarify the meaning of 'includeTransitive' beyond aligning with 'transitive dependencies' in the description.

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 it returns a dependency graph (direct and transitive) for a component. The verb 'returns' and resource 'dependency graph' are specific. This distinguishes it from siblings like 'get_component' or 'list_components' which serve different purposes.

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

Usage Guidelines4/5

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

Description mentions a prerequisite: requires a CEM built with dependency reference data, implying when it should be used. It does not explicitly state when not to use or name alternatives, but the sibling context makes the niche clear for an AI agent.

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

get_component_narrativeA

Returns a 3-5 paragraph markdown prose description of a component — what it is, when to use it, how to customize it, its slots, and its events. Optimized for LLM comprehension.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").

TDQS

A3.6/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 full burden. It describes the output format and content but fails to mention potential errors (e.g., component not found), side effects (none), or any behavioral traits beyond the 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 two sentences that immediately convey the core purpose and content of the output. Every sentence adds essential information; there is no fluff or wasted words.

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

Completeness4/5

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

Given no output schema, the description adequately specifies output length and content categories. Minor gap: does not mention error handling or behavior when tagName does not exist, but this is a simple read operation.

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 both parameters already described in the input schema. The description does not add extra meaning or context for the parameters, so 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 tool returns a 3-5 paragraph markdown prose description covering what a component is, when to use it, customization, slots, and events. This is distinct from sibling tools like get_component (structured data) and get_component_quick_ref (shorter ref), so it effectively differentiates.

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 LLM comprehension and high-level understanding, but does not explicitly state when to use it versus alternatives like get_component or list_components. No when-not-to-use guidance is provided.

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

get_component_quick_refA

Returns a complete quick reference for a web component — all attributes with types and valid enum values, methods, events, slots, CSS custom properties with examples, CSS parts with ::part() selectors, a ready-to-use CSS snippet, Shadow DOM warnings, and antiPatterns (component-specific "don't do this" negative examples using real tag/part/token names). Use this as the FIRST call when working with any web component to get the complete API surface and avoid common mistakes.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "sl-button").

TDQS

A3.7/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 fully disclose behavior. It describes what the tool returns but does not mention any side effects, idempotency, authorization requirements, error conditions, or performance characteristics. For a read operation that might depend on loaded libraries (implied by optional libraryId), this is insufficient.

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, dense sentence that front-loads the purpose and lists all returned elements efficiently. While it is packed, it avoids redundancy and every item is meaningful. Could be slightly improved with bullet points but already very concise.

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

Completeness4/5

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

Given the complexity of the tool (returns many different types of information) and no output schema, the description does a good job enumerating what is included. It covers the major categories and adds context about antiPatterns and Shadow DOM warnings. However, it doesn't specify the structure or format of the output.

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 both parameters described. The description adds no additional meaning beyond the schema. The baseline of 3 is appropriate as the schema already 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?

Description specifies exact resources returned (attributes, methods, events, slots, CSS properties, parts, snippet, warnings, antiPatterns) with a specific verb 'Returns'. Distinguishes from sibling tools like get_component (just component info) or list_events (only events) by being comprehensive.

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

Usage Guidelines4/5

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

Explicitly states 'Use this as the FIRST call when working with any web component', providing clear when-to-use guidance. Though it doesn't explicitly say when-not-to-use, the context implies other tools like check_slot_children or list_events are for deeper analysis after this initial reference.

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

get_composition_exampleA

Generates a realistic HTML snippet showing how to compose two or more web components together. Slot assignments are drawn from CEM slot definitions. Provide 1–4 component tag names; a single tag name returns a standalone usage example.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagNames`	Yes	Array of 1–4 custom element tag names to compose (e.g. ["my-card", "my-button"]).

TDQS

A4/5.0

Behavior3/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 mentions that slot assignments come from CEM slot definitions, but does not state that the tool is read-only, has no side effects, or requires the library to be loaded. The description is adequate but lacks explicit safety or prerequisite information.

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 two sentences long, clear, and front-loaded. Every sentence provides essential information without redundancy or unnecessary detail.

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

Completeness4/5

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

For a tool with two parameters and no output schema, the description covers the input constraints, behavior for single vs multiple tags, and the source of slot data. Minor gaps exist (e.g., handling of missing slot definitions), but overall it is sufficiently complete for effective use.

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?

Schema coverage is 100%, meaning parameters are described in the schema. The description adds value by explaining that slot assignments are drawn from CEM definitions and that a single tag yields a standalone example, which is not evident from the schema alone.

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 uses specific verbs ('Generates a realistic HTML snippet') and identifies the resource ('composition of web components using slot definitions'). It also distinguishes from siblings like 'check_composition' and 'get_component' by focusing on example generation and composition.

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 clear input constraints (1–4 tag names) and a special case (single tag returns standalone example). However, it does not specify when to use this tool over alternatives like 'check_composition' or 'get_component', nor does it mention prerequisites such as loading the library.

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

get_design_tokensA

List all design tokens from the configured tokens file, optionally filtered by category (e.g. "color", "spacing", "typography"). Requires tokensPath to be set in mcpwc.config.json or MCP_WC_TOKENS_PATH.

ParametersJSON Schema

Name	Required	Description	Default
`category`	No	Optional category to filter by (e.g. "color", "spacing", "typography"). Case-insensitive.

TDQS

A3.8/5.0

Behavior3/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 accurately describes the listing and filtering behavior, but does not disclose potential performance limits, error handling (e.g., missing file), or return format. Basic transparency is adequate for a simple read 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?

Two sentences: the first covers the core functionality and optional filtering, the second states a prerequisite. No unnecessary words, information is front-loaded.

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

Completeness4/5

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

Given the absence of an output schema and annotations, the description is fairly complete. It states what the tool does, its optional parameter, and a configuration requirement. However, it does not describe the return format or expected behavior if the tokens file is missing, which would add completeness for a read-only 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 schema description coverage is 100% with a single parameter. The tool description repeats the examples from the schema almost verbatim. It adds no new semantic value beyond what the schema already provides, so 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 tool lists all design tokens from a configured file, optionally filtered by category. This specific verb-resource-scope distinguishes it from sibling tools like find_token or check_token_fallbacks.

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 mentions a prerequisite (tokensPath configuration) but does not explicitly guide when to use this tool vs. siblings like find_token or check_token_fallbacks. Usage context is implied but not stated.

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

get_file_diagnosticsA

Run TypeScript diagnostics on a single file and return any type errors or warnings.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	Relative path to the TypeScript file (no path traversal or absolute paths allowed).

TDQS

A3.6/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 states that it 'run diagnostics' and 'return' results, implying a read operation, but does not explicitly state read-only, side effects, permissions, or response behavior. The description is minimal and adds little beyond the tool's name.

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 efficiently conveys the purpose without extraneous details. Every word contributes to understanding, making it highly concise and well-structured.

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 absence of annotations and output schema, the description is too minimal. It does not explain the return format, error handling, or how diagnostics are produced (e.g., using tsconfig). This limits the agent's ability to effectively use the tool's output.

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 parameter 'filePath' has a description in both schema and tool description, with additional constraints like 'no path traversal or absolute paths allowed'. This provides semantic meaning beyond the type string, helping the agent provide correct input.

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 'run diagnostics' and the resource 'single TypeScript file', and the output 'type errors or warnings'. This distinguishes it from sibling tools that focus on components, themes, or accessibility rather than file-level diagnostics.

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?

No explicit guidance on when to use this tool versus alternatives like 'get_project_diagnostics'. The usage is implied from the name and description (single file), but no exclusions or context about when not to use it are provided.

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

get_health_diffA

Compares health between the current branch and a base branch, returning before/after scores with improvement or regression verdict.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	The tag name of the component (e.g. "my-button").
`baseBranch`	No	The base branch to compare against (default: "main").
`libraryId`	No	The library ID to scope the health history lookup (default: "default").

TDQS

A4/5.0

Behavior4/5

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

No annotations exist, so description fully carries transparency burden. It states returns before/after scores with improvement/regression verdict, which is clear. However, it doesn't disclose if the tool is read-only, any side effects, or performance implications.

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, concise sentence front-loads the action and output. Every word adds value with no redundancy.

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

Completeness4/5

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

No output schema, so description explains return value (scores and verdict). Adequate for a simple tool with 3 params, but could elaborate on what 'health' means or the comparison methodology.

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 has 100% description coverage, so baseline is 3. The tool description does not add extra meaning beyond the schema's param descriptions, which already explain tagName, baseBranch, and libraryId adequately.

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 compares health between branches, returning scores and a verdict. It distinguishes from siblings like get_health_summary and get_health_trend by specifying comparison and verdict.

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 comparing branch health but lacks explicit when-to-use or when-not-to-use guidance. No alternatives or exclusions are mentioned despite many sibling tools for different analyses.

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

get_health_summaryA

Returns aggregate health statistics for all components: average score, grade distribution, total count, library-wide trend, per-dimension averages, and components needing attention (score below 70).

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`libraryRoot`	No	Optional absolute path to the consuming library root. When provided, source-level evidence (focus-visible, attachInternals, forced-colors) feeds the multi-dim scoring. Omit for CDN-loaded libraries — source-dependent dims return unknown rather than being contaminated by unrelated workspace files.

TDQS

A3.5/5.0

Behavior2/5

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

No annotations provided; description does not disclose safety, performance, or prerequisites beyond the return value. Does not mention read-only nature or dependency on loaded library.

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 efficiently lists all returned statistics but could be improved by breaking into bullet points for clarity.

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

Completeness4/5

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

Given no output schema, description adequately defines return values. Lacks mention of prerequisites like library loading, but context from sibling tools implies it.

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 already covers both parameters with descriptions (100% coverage). Tool description adds no extra meaning beyond the schema, so 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?

Clear verb 'Returns aggregate health statistics' and specific resources listed, distinguishing it from siblings like get_health_diff or get_health_trend.

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?

No explicit when-to-use or when-not-to-use guidance, but the return type implies it's for an overall health overview. Context from sibling names suggests differentiation but not stated in description.

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

get_health_trendB

Returns the health trend for a component over the last N days, including data points, trend direction, and change percent.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	The tag name of the component (e.g. "my-button").
`days`	No	Number of days to look back (default: 7).
`libraryId`	No	The library ID to scope the health history lookup (default: "default").

TDQS

B3.4/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 describes outputs but does not state that the tool is read-only, has no side effects, or any auth/rate requirements.

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, front-loaded with purpose, no wasted words.

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

Completeness4/5

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

For a tool with 3 params and no output schema, the description covers the main return fields. Missing detail on defaults (days=7, libraryId='default') but those are in schema.

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%, so baseline 3. Description adds context for output but not for parameters beyond mentioning 'component' and 'N days'. libraryId is not mentioned.

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 function: returns health trend for a component over N days, listing specific outputs (data points, trend direction, change percent). However, it does not explicitly differentiate from sibling tools like get_health_summary or get_health_diff.

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?

Implies use for time-series trend data, but provides no guidance on when to use vs alternatives or when not to use. Could mention scenarios where summary or diff would be more appropriate.

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

get_library_summaryA

Get an overview of the component library: component count, average health score, grade distribution, and last health check timestamp.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.

TDQS

A3.8/5.0

Behavior3/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 states the tool returns specific aggregate data, indicating a read-only operation, but does not explicitly declare safety (e.g., no side effects) or address authorization or rate limits. Some behavioral context is provided but incomplete.

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 approximately 15 words, front-loading the purpose and listing key outputs. Every phrase adds value, with no redundancy or filler.

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

Completeness4/5

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

For a simple tool with one optional parameter and no output schema, the description adequately covers what the tool returns. It could be improved by clarifying how 'default' library is determined, but overall is sufficiently complete for the tool's complexity.

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% and the sole parameter 'libraryId' is already well-described in the schema. The tool description adds no extra semantic detail beyond what the schema provides, so baseline score of 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?

The description uses a specific verb ('Get an overview') and resource ('component library'), listing exactly what is returned: component count, average health score, grade distribution, and last health check timestamp. This clearly distinguishes it from sibling tools like 'get_component' or 'get_health_summary'.

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 use for a high-level library overview but does not specify when to prefer this over alternative tools (e.g., 'get_health_summary' or 'list_libraries'), nor does it mention prerequisites like having loaded a library. The guidance is implied but not explicit.

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

get_project_diagnosticsA

Run a full TypeScript diagnostic pass on the entire project and return error and warning counts.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states the operation is a diagnostic pass, implying a read-only operation, but does not explicitly confirm non-destructiveness, potential performance impact, or authentication requirements.

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 with no extraneous words. Action and scope are front-loaded. Every word adds value.

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

Completeness4/5

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

Given zero parameters and no output schema, the description covers the essential purpose and return (counts). It could optionally mention if only counts or full diagnostics are returned, but is adequate for use.

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

Parameters5/5

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

With no parameters and 100% schema coverage, the description adds meaning by confirming the tool accepts no arguments and operates on the entire project. This is sufficient and clear.

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 identifies the action ('run'), the scope ('full TypeScript diagnostic pass on the entire project'), and the return value ('error and warning counts'). This distinguishes it from sibling tools like get_file_diagnostics, which focus on individual files.

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

Usage Guidelines4/5

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

Description implies usage for whole-project diagnostics but does not explicitly state when to use this tool versus alternatives (e.g., get_file_diagnostics for files). No exclusion criteria or prerequisites are mentioned.

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

get_prop_constraintsA

Returns a structured constraint table for a component attribute. Union type attributes include all valid values with descriptions. Non-union types return simple type info.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "sl-button").
`attributeName`	Yes	The attribute or property name to inspect (e.g. "variant").

TDQS

A4/5.0

Behavior4/5

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

Given no annotations, the description transparently explains the output behavior for union and non-union types. It does not cover error handling or side effects, but the tool is read-only and straightforward, so the transparency is adequate.

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 two concise sentences with the purpose front-loaded. Every word adds value, with no redundancy or extraneous information.

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

Completeness4/5

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

For a simple query tool with 3 parameters and no output schema, the description covers the core behavior adequately. However, it could mention the return format or typical responses to be fully complete.

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%, so the baseline is 3. The description adds context about union versus non-union types, which relates to the attributeName parameter, but does not enhance understanding of libraryId or tagName beyond the schema.

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 returns a structured constraint table for a component attribute, with specific behavior for union vs non-union types. It effectively distinguishes this tool from sibling audit/check tools by focusing on attribute constraints.

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 is used when needing attribute constraints, but does not explicitly state when to use it versus alternatives or when not to use it. No guidance on 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.

list_componentsA

List all custom element components registered in the Custom Elements Manifest.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations provided; description implies a read-only listing from 'List' but does not explicitly state safety, performance, or side effects. Adequate but not thorough.

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?

One concise sentence with no unnecessary words, efficiently conveying the tool's action and scope.

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

Completeness4/5

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

For a simple listing tool with one optional parameter, the description is mostly complete. However, it does not mention return format or pagination, which would be helpful.

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 full description for the only parameter. Description adds no extra meaning beyond schema, baseline score 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?

The description clearly states the tool lists all custom element components from the manifest, distinguishing it from siblings like get_component (single) and list_components_by_category (filtered).

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?

No explicit guidance on when to use this tool vs alternatives (e.g., list_components_by_category, find_component). Usage is implied but not clarified.

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

list_components_by_categoryA

Group components by functional category (form, navigation, feedback, layout, data-display, media, overlay). Uses @category JSDoc tag when present, falls back to heuristic tag-name pattern matching.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`category`	No	Optional category to filter to (e.g. "form", "navigation"). If omitted, returns all categories.
`includeUncategorized`	No	When true, includes components that could not be categorized (default: false).

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses the categorization logic but does not state that the tool is read-only, specify performance traits, or mention dependencies like requiring a loaded library despite having a libraryId parameter.

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 highly concise with two sentences. The main purpose and method are front-loaded, and every sentence contributes meaning without redundancy.

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

Completeness4/5

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

Given the tool has 3 optional parameters and no output schema, the description adequately covers the grouping logic and categories. However, it omits the output format and default behavior for libraryId, leaving some gaps for an AI 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?

Schema coverage is 100%, so each parameter is described in the schema. The description adds limited value: it lists categories but does not elaborate on parameter behavior or defaults beyond what the schema provides.

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: grouping components by functional category, listing specific categories. It differentiates from sibling tools like list_components by focusing on categorization rather than flat listing.

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 explains the categorization method (using @category tag or heuristic fallback) but does not provide explicit guidance on when to use this tool versus alternatives like list_components or find_component. Usage context is implied but not clarified.

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

list_css_partsA

List all CSS parts (::part()) across all components in the library. Optionally filter by component tag name. Returns part name, component tag, and description.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	No	Optional component tag name to filter CSS parts (e.g. "my-button").

TDQS

A3.8/5.0

Behavior3/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 action (listing), optional filter, and return fields, providing basic behavioral context. However, it does not mention whether the tool is read-only, performance implications, or access requirements. This is adequate but not rich.

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 two sentences, front-loaded with the core action, and includes the optional filter and return information. Every part is necessary, no fluff.

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

Completeness4/5

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

Given no output schema, the description specifies the return fields (part name, component tag, description), which is sufficient for a list tool. It lacks details on pagination, ordering, or result limits, but these are not critical for a simple listing 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% with both parameters described. The description adds no further detail beyond the schema, so it meets the baseline. No extra context is provided about parameter formats or constraints.

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 'List all CSS parts ... across all components', specifying the verb (list), resource (CSS parts), and scope. It distinguishes from sibling tools like list_components, list_events, list_slots by focusing on CSS parts.

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 exploring CSS parts and optionally filtering by tag name, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No guidance on when not to use it.

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

list_eventsA

List all events across all components in the library. Optionally filter by component tag name. Returns event name, component tag, description, and detail type.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	No	Optional component tag name to filter events (e.g. "my-button").

TDQS

A4.5/5.0

Behavior4/5

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

The description indicates that the tool returns event name, component tag, description, and detail type. With no annotations provided, it adequately covers the tool's read-only nature and output structure, though it could mention lack of 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 two sentences, front-loaded with the primary action, and includes return information. Every sentence adds value without redundancy.

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

Completeness5/5

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

Given the tool's simplicity, lack of output schema, and no annotations, the description covers purpose, parameters, and return values completely. No critical information is missing.

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?

Schema coverage is 100%, and the description adds meaning by explaining that 'tagName' is an optional filter and 'libraryId' targets a specific library. This enriches the schema definitions.

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 uses a specific verb ('list') and resource ('all events across all components'), clearly stating the tool's function. It distinguishes from siblings like 'check_event_usage' which focuses on usage checking.

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

Usage Guidelines4/5

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

The description mentions optional filtering by tag name, but does not explicitly state when to use this tool versus alternatives. However, the context of listing vs checking events is clear enough for an agent to discern usage.

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

list_helixir_toolsA

Discover the helixir MCP tool catalog: every registered tool with its summary, when-to-call triggers, input shape, and tags. Filter by tag or substring. Use this FIRST when you are unsure which helixir tool fits a task — install ≠ adoption.

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No	Restrict to tools matching ALL supplied tags (audit, verify, scaffold, validation, tokens, extension, scoring, discovery, read, analyze).
`search`	No	Substring match on tool name.

TDQS

A4.8/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns a catalog with summaries, triggers, input shape, and tags. It does not explicitly state read-only or non-destructive behavior, but the context implies it is a listing/discovery operation. No contradictions.

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?

Two sentences plus a parenthetical note. Extremely concise, front-loaded with the primary purpose. Every sentence adds value without redundancy.

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

Completeness5/5

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

Despite no output schema, the description thoroughly explains what the response contains (every tool with summary, triggers, input shape, tags). Given the tool's purpose as a catalog, this is fully sufficient.

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

Parameters5/5

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

Schema coverage is 100% and the description adds value by explaining parameter semantics: 'Restrict to tools matching ALL supplied tags' and 'Substring match on tool name' – clarifying the matching logic (AND vs OR) and what 'search' operates on.

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 it is a discovery tool for the helixir MCP tool catalog, listing all registered tools with summaries, triggers, input shapes, and tags, with filtering by tag or substring. This directly distinguishes it from sibling tools that are specific actions.

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

Usage Guidelines5/5

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

Explicitly advises 'Use this FIRST when you are unsure which helixir tool fits a task,' providing clear when-to-use guidance and implied when-not-to-use (when you already know the tool). Also notes 'install ≠ adoption' for nuance.

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

list_librariesA

List all loaded web component libraries with their IDs, component counts, and source types.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It indicates a read-only operation ('List') but does not explain what 'loaded' means, whether the state is persistent, or any side effects/permissions. Basic transparency, but missing context.

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 fluff. It is front-loaded with the verb and resource, making it efficient and easy to parse.

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

Completeness4/5

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 covers return fields (IDs, component counts, source types). Missing details on ordering, pagination, or limits, but for a parameterless list tool it is fairly complete.

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 100%. The description adds no parameter info because none is needed. Baseline 4 is appropriate as the description is sufficient without adding parameter details.

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 'List' and resource 'all loaded web component libraries', specifying returned fields (IDs, component counts, source types). This distinguishes it from sibling tools like list_components which list components.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description implies it is for listing loaded libraries, but does not compare to alternatives like get_library_summary or benchmark_libraries.

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

list_slotsA

List all slots across all components in the library. Optionally filter by component tag name. Returns slot name, component tag, description, and whether the slot is named or default.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	No	Optional component tag name to filter slots (e.g. "my-button").

TDQS

A4/5.0

Behavior4/5

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

No annotations exist, so description carries full burden. It discloses return shape (slot name, tag, description, type) and scoping across all components. Missing details on library scope behavior but overall transparent.

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?

Two efficient sentences: first states action, second adds filtering and return info. No fluff, every sentence contributes.

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

Completeness4/5

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

For a simple list tool with 2 optional params and no output schema, description covers main points. Minor gap: behavior when libraryId is omitted not explicit. Still sufficient for agent decision-making.

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%, so baseline is 3. Description reinforces tagName filtering but does not add meaning beyond schema for libraryId. No extra value provided.

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 the verb (List) and resource (slots across all components), and distinguishes from siblings like list_components or list_events by specifying the resource type.

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?

Description mentions optional filtering by tag name, which provides some guidance, but lacks explicit when-not-to-use or alternatives. For a straightforward list tool, this is adequate but not exceptional.

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

load_libraryA

Load an additional web component library into memory by libraryId. Provide either a local cemPath or a packageName (+ optional version) to fetch from CDN. Once loaded, all CEM-dependent tools can target this library using the libraryId parameter.

ParametersJSON Schema

Name	Required	Description
`libraryId`	Yes	Unique identifier for this library (e.g. "shoelace", "spectrum"). Used to reference it in subsequent tool calls.
`cemPath`	No	Local file path to the custom-elements.json file. Relative paths are resolved from projectRoot.
`packageName`	No	npm package name to fetch CEM from CDN (e.g. "@shoelace-style/shoelace"). Used when cemPath is not provided.
`version`	No	Package version for CDN fetch (default: "latest").
`registry`	No	CDN registry for package fetch (default: "jsdelivr").

TDQS

A4.1/5.0

Behavior3/5

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

With no annotations, the description must fully disclose behavior. It mentions loading into memory and affecting subsequent tool calls, but does not detail side effects (e.g., idempotency, error handling, network dependencies). It adds some context beyond basic functionality, but lacks comprehensive safety or performance traits.

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 concise (two sentences), front-loaded with the action and resource, and contains no verbose or redundant information. Every sentence adds necessary context.

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's role as a prerequisite for many sibling tools and the absence of an output schema, the description does not explain return behavior, failure scenarios, or multiple-load handling. It covers basic usage but lacks completeness for error states or edge cases.

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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between cemPath and packageName, and that the registry defaults to jsdelivr and version to latest. This clarifies the dual-path setup beyond what the schema descriptions provide individually.

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 ('Load an additional web component library into memory by libraryId') and specifies the resource (web component library). It distinguishes from siblings by explaining that after loading, other CEM-dependent tools can target this library, which sets it apart from tools like unload_library or list_libraries.

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

Usage Guidelines4/5

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

The description provides clear guidance on when to use each parameter option ('Provide either a local cemPath or a packageName (+ optional version) to fetch from CDN'). However, it does not explicitly state when not to use the tool or mention alternatives, such as checking if the library is already loaded or comparing with unload_library.

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

recommend_checksA

Analyzes code to determine which validation tools are most relevant — detects HTML, CSS, JavaScript, and JSX patterns, identifies custom element tags, and returns a prioritized list of tool names. Use this as a meta-tool to discover which validators to run on a given piece of code without running them all.

ParametersJSON Schema

Name	Required	Description	Default
`codeText`	Yes	The code to analyze for determining which validation tools are relevant.

TDQS

A4.2/5.0

Behavior3/5

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

Discloses analytical behavior (detects patterns, returns list) and that it avoids running all validators. However, with no annotations, it does not explicitly state it is non-destructive or read-only, nor mention any limitations (e.g., file size, unsupported languages).

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?

Two concise sentences: the first explains functionality, the second states usage. Every word adds value; no redundancy.

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

Completeness4/5

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

For a one-parameter meta-tool with no output schema or annotations, the description sufficiently covers purpose, input, and output (prioritized list of tool names). It could briefly mention the output format (e.g., array of strings) but is otherwise complete.

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 only parameter 'codeText' is fully described in the schema. The description adds valuable context about the patterns detected (HTML, CSS, JS, JSX, custom elements) beyond the schema's minimal description.

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 the tool analyzes code to detect patterns (HTML, CSS, JS, JSX, custom element tags) and returns a prioritized list of relevant validation tool names. It is explicitly framed as a meta-tool, distinguishing it from sibling validators.

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

Usage Guidelines4/5

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

Explicitly recommends using this tool before running all validators to discover which are relevant. Provides clear usage context but does not mention when not to use it or any alternatives.

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

resolve_cdn_cemA

Fetch and cache a web component library's Custom Elements Manifest (CEM) from a CDN registry (jsDelivr or UNPKG) by npm package name. Useful when the library is loaded via CDN without a local npm install. By default (register: false) the CEM is only fetched and cached locally — server state is NOT modified. Set register: true to also register the CEM into the multi-library store for use with other tools.

ParametersJSON Schema

Name	Required	Description
`package`	Yes	npm package name, e.g. "@shoelace-style/shoelace"
`version`	No	Package version, e.g. "2.15.0". Defaults to "latest".
`registry`	No	Which CDN to use. Default: "jsdelivr".
`register`	No	When true, registers the fetched CEM into the multi-library store. Default: false (preview only, does not mutate server state).
`cemPath`	No	Optional path to the CEM file within the package, e.g. "dist/custom-elements.json". If omitted, tries "custom-elements.json", then "dist/custom-elements.json", then "lib/custom-elements.json".

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, description clearly states that by default server state is NOT modified (register:false) and explains registration behavior. Discloses caching locally. Could elaborate on idempotency or error handling, but covers key behavioral aspects.

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?

Three sentences, no waste. Front-loaded with core action, then usage context, then behavioral detail. Every sentence earns its place.

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?

Covers main functionality and usage but omits return value/output description. With no output schema, the agent is left guessing what the tool returns. Also missing error handling notes. Adequate but incomplete.

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?

Schema has 100% coverage, but description adds value: explains default behavior for register, fallback logic for cemPath, and purpose of each parameter. Provides context beyond schema descriptions.

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?

Clearly states verb+resource: 'Fetch and cache a web component library's Custom Elements Manifest (CEM) from a CDN registry'. Differentiates from siblings by specifying CDN source (jsDelivr/UNPKG) and npm package name, which no other sibling tool does.

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

Usage Guidelines4/5

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

Provides clear when-to-use context: 'Useful when the library is loaded via CDN without a local npm install'. Explains default behavior and when to set register:true. Does not explicitly mention alternatives or when not to use, but the context is sufficient.

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

resolve_css_apiA

Resolves every ::part(), CSS custom property, and slot reference in agent-generated code against the actual component CEM data. Returns a structured report showing which references are valid, which are hallucinated, and suggests the closest valid alternatives. Call this BEFORE shipping any CSS to verify that every part name, token name, and slot name actually exists on the target component.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to resolve against the component API.
`tagName`	Yes	The custom element tag name (e.g. "sl-dialog").
`htmlText`	No	Optional HTML code to validate slot attribute references against the component API.

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses that the tool returns a structured report about validity, hallucinated references, and alternative suggestions. Does not mention side effects, but the tool appears to be a pure analysis operation based on input.

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?

Two sentences, front-loaded with the primary action and output. No wasted words; every part adds value.

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

Completeness4/5

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

Given 4 parameters and no output schema, the description adequately explains the tool's purpose, inputs, and the structured output. It lacks details on the exact format of the report but is sufficient for an agent to understand usage.

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?

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining the role of each parameter: libraryId for targeting a library, cssText and htmlText for resolving references, tagName for the target component. This enriches the schema descriptions without redundancy.

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 it resolves CSS references (::part(), custom properties, slots) against CEM data and returns a structured report with validity and alternatives. Distinguishes from sibling tools like check_css_vars by explicitly covering all three reference types in one tool.

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

Usage Guidelines4/5

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

Explicitly says 'Call this BEFORE shipping any CSS to verify...' providing a clear usage context. Does not explicitly list when not to use or contrast with alternatives, but the guidance is actionable and well-placed.

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

scaffold_componentA

Generate a complete Helix-pattern web component scaffold: Lit class with decorators, CEM annotations (@slot, @csspart, @fires), Vitest test stub, Storybook CSF3 story, and CSS structure. Conventions (tag prefix, base class) are auto-detected from the library CEM so the generated code matches existing library patterns.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	Custom element tag name (e.g. "hx-button"). Must be lowercase and contain a hyphen.
`baseClass`	No	Base class to extend (e.g. "LitElement"). If omitted, detected from the CEM or defaults to "LitElement".
`slots`	No	Slots to expose. Use name "" or "default" for the unnamed default slot.
`cssParts`	No	CSS parts to expose via ::part().
`events`	No	Custom events to dispatch.
`properties`	No	Reactive properties / attributes to declare.

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations provided, the description carries full burden. It describes what is generated but omits behavioral details like whether it writes files to disk, overwrites existing files, or requires any permissions/dependencies. For a code-generation tool, this is a notable gap.

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?

Two concise sentences with no redundancy. The first sentence lists outputs, the second adds key auto-detection behavior. Every word serves a 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?

Given 6 parameters and no output schema or annotations, the description is adequate but incomplete. It does not explain file placement, overwrite behavior, or how structured inputs like 'properties' map to generated code. More context would help an agent invoke the tool 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?

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal value beyond the schema, only mentioning auto-detection for baseClass. Baseline 3 is appropriate as the schema already 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 tool generates a 'complete Helix-pattern web component scaffold' and enumerates specific outputs (Lit class, CEM annotations, test stub, story, CSS). It also mentions auto-detection from library CEM to match existing patterns, distinguishing this generation tool from siblings like 'extend_component' or 'generate_story'.

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

Usage Guidelines4/5

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

The description implies usage for creating new components that fit library patterns, but does not explicitly state when not to use this tool or mention alternatives among the extensive sibling list. The auto-detection hint gives context but lacks direct usage boundaries.

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

score_all_componentsA

Returns health scores for all components in the library. Set multiDimensional=true for full 11-dimension enterprise scoring.

ParametersJSON Schema

Name	Required	Description	Default
`multiDimensional`	No	When true, returns multi-dimensional scores with 11 dimensions per component. Default: false.
`libraryRoot`	No	Optional absolute path to the consuming library root. Threaded into helix-AAA evidence detection for the 8 split a11y dims when multiDimensional=true.

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations, the description carries the burden. It discloses that setting multiDimensional=true returns 11 dimensions and that libraryRoot is used for evidence detection in a11y dims. However, it does not state whether the operation is read-only or if there are 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?

Two sentences with no waste. The first sentence states the core purpose, and the second provides critical detail about the key parameter. Information is front-loaded and efficient.

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?

While the description covers the tool's function and key parameter behavior, it lacks details about the return format (e.g., structure of health scores, default vs. multi-dimensional output). Given the tool's complexity and lack of output schema, additional context would help an agent fully understand the output.

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?

Schema coverage is 100%, but the description adds value beyond the schema: for multiDimensional, it explains 'full 11-dimension enterprise scoring'; for libraryRoot, it clarifies it is 'threaded into helix-AAA evidence detection for the 8 split a11y dims.' This provides useful context.

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 'Returns health scores for all components in the library,' specifying the verb (returns), resource (health scores), and scope (all components). This distinguishes it from the sibling tool 'score_component' which targets a single component.

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 explicit guidance on when to use this tool versus alternatives like 'score_component' or other analysis tools. The description only hints at parameter behavior but does not provide context for selection.

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

score_componentA

Returns the latest health score for a single web component, including grade, dimension scores, and issues. Set multiDimensional=true for the full 11-dimension enterprise scoring with tier gates.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	The tag name of the component to score (e.g. "my-button").
`libraryId`	No	The library ID to scope the health history lookup (default: "default").
`multiDimensional`	No	When true, returns the full multi-dimensional health score with 11 dimensions, enterprise grade algorithm, and confidence levels. Default: false for backward compatibility.
`libraryRoot`	No	Optional absolute path to the consuming library root (e.g. /path/to/helix). When provided alongside multiDimensional=true, enables helix-AAA evidence collection (helixMeta, aaa-verdicts.json, AAA-AUDIT.md sidecar, source-level checks) that the 8 split a11y dims score against. Omit to skip source-level checks and fall back to CEM-only evidence.

TDQS

A3.5/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It explains that setting multiDimensional=true changes the output to 11-dimension enterprise scoring with tier gates, and mentions libraryRoot enables helix-AAA evidence collection. However, it does not disclose whether the tool is read-only, has side effects, or any performance implications.

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?

Two concise sentences with no fluff. The first states the main purpose, and the second highlights the key parameter option. Every sentence earns its place.

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?

With no output schema, the description gives a high-level overview but does not detail the return format (e.g., score range, structure of issues). Adequate for basic understanding but lacking completeness for an agent to fully anticipate the response.

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 detailed parameter descriptions. The description adds minimal value beyond the schema, only restating the purpose of multiDimensional. The baseline of 3 is appropriate as the schema already provides full semantics.

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 returns the latest health score for a single web component, specifying it includes grade, dimension scores, and issues. It distinguishes itself from the sibling 'score_all_components' by explicitly noting it is for a single component, and explains the multi-dimensional option.

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 get_health_summary or get_health_trend. The description does not mention when not to use it or provide any comparative context with siblings.

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

styling_preflightA

Single-call styling validation that combines component API discovery, CSS reference resolution, and anti-pattern detection. Returns: the component's full style API surface (parts, tokens, slots), valid/invalid status for every ::part() and token reference, Shadow DOM and theme validation issues with inline fix suggestions (each issue includes a fix object with corrected code + explanation), antiPatterns (component-specific negative examples), a correct CSS snippet, and a pass/fail verdict. Call this ONCE before finalizing any component CSS — fixes are embedded in each issue so you don't need a separate suggest_fix call.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The CSS code to validate against the component API.
`tagName`	Yes	The custom element tag name (e.g. "hx-button").
`htmlText`	No	Optional HTML code to validate slot attribute references against the component API.

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It discloses that the tool is a comprehensive single-call validation, returns detailed diagnostics with inline fix suggestions, and that no separate suggest_fix call is needed. It does not mention side effects or performance, but the behavioral profile is well-covered.

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, informative paragraph with no fluff. It front-loads the purpose and then lists return items. Could be slightly more structured (e.g., bullet points) but is otherwise efficient.

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

Completeness4/5

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

Given the complexity (4 params, no output schema, many siblings), the description covers the tool's comprehensive nature, return items, and usage timing. It lacks details on output format and error handling but is sufficient for an AI agent to understand when and why to use it.

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 all parameters. The description adds some context (e.g., 'HTML code to validate slot attribute references') but does not significantly extend beyond what the schema provides.

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 it performs 'single-call styling validation' combining component API discovery, CSS reference resolution, and anti-pattern detection. It distinguishes itself from sibling tools like suggest_fix by noting that fixes are embedded, eliminating the need for a separate call.

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

Usage Guidelines4/5

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

Explicitly says 'Call this ONCE before finalizing any component CSS', providing clear timing. It implies a comprehensive alternative to running multiple individual checks, but does not explicitly list which sibling tools it replaces.

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

suggest_fixA

Generates concrete, copy-pasteable code fixes for validation issues. Pass the issue type (shadow-dom, token-fallback, theme-compat, method-call, event-usage, specificity, layout), the specific issue kind, and the original code — returns a corrected code snippet with an explanation. NOTE: styling_preflight and validate_css_file now embed fixes inline in each issue — only call suggest_fix directly for issues from other validators or when you need a fix for code not already validated.

ParametersJSON Schema

Name	Required	Description
`type`	Yes	The category of validation issue.
`issue`	Yes	The specific issue kind (e.g. "descendant-piercing", "missing-fallback", "hardcoded-color", "property-as-method", "react-custom-event").
`original`	Yes	The original problematic code.
`tagName`	No	Optional tag name of the component.
`partNames`	No	Optional list of CSS part names exposed by the component.
`property`	No	Optional CSS property name for token/theme fixes.
`memberName`	No	Optional method/property name for method call fixes.
`suggestedName`	No	Optional corrected name for typo fixes.
`eventName`	No	Optional event name for event usage fixes.
`tokenPrefix`	No	Optional token prefix from the component library (e.g. "--hx-", "--fast-", "--md-"). When provided, suggested replacement tokens use this prefix. Get this from diagnose_styling.

TDQS

A4.6/5.0

Behavior4/5

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

The description discloses that the tool returns a corrected code snippet with an explanation, adding behavioral context beyond the input schema. No annotations are present, so the description carries full responsibility; it is mostly transparent about the tool's output but does not mention potential side effects or authorization needs.

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 concise, consisting of two main sentences and a note. It is front-loaded with the core purpose and efficiently uses each sentence to convey key information without redundancy.

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

Completeness4/5

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

Given the tool's complexity (10 parameters, 3 required) and lack of output schema, the description adequately explains its role and integration with other tools. It could be improved by providing an example output or more detail on the fix format, but the current description is sufficient for selection.

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?

Schema coverage is 100%, providing baseline 3. The description adds value by explaining the purpose of optional parameters (e.g., 'Get this from diagnose_styling' for tokenPrefix) and contextualizing required parameters beyond the schema names.

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 concrete, copy-pasteable code fixes for validation issues, listing specific issue types and required inputs. It effectively differentiates from similar tools by noting that styling_preflight and validate_css_file embed fixes inline.

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

Usage Guidelines5/5

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

Explicit guidance is provided on when to use the tool (for issues from other validators or code not already validated) and when not to (for styling_preflight and validate_css_file which embed fixes). The description includes a clear note with directives.

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

suggest_usageA

Generates an HTML usage snippet for a component, showing key attributes with their default values. Lists required vs optional attributes and variant options from union types.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").
`framework`	No	Target framework for usage snippet. Auto-detected from package.json if omitted. Use "html" for plain HTML output.

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It describes the output but does not disclose any behavioral traits such as whether it makes network calls, relies on loaded libraries, or is read-only. The tool likely reads library data but this is not stated.

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 sentence that efficiently conveys the tool's purpose. It is front-loaded with the verb and resource, and every clause adds value.

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

Completeness4/5

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

Given no output schema, the description adequately explains what the output contains. It covers expected content but could be more explicit about the output format per framework. Sibling tools are well-distinguished.

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%, so the schema already documents each parameter. The description adds no extra detail about parameter usage, format, or constraints beyond what the schema provides.

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 'Generates' and the resource 'HTML usage snippet'. It specifies what the snippet includes: key attributes with defaults, required vs optional attributes, and variant options. This distinguishes it from siblings like generate_import (import statements) and validate_usage (validation).

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 when an HTML usage snippet for a component is needed, but it does not explicitly state when to use this tool versus alternatives like generate_import or check_html_usage. No exclusions or context are provided.

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

unload_libraryA

Remove a loaded library from memory. Cannot unload the "default" library. Subsequent tool calls with this libraryId will fail.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	Yes	The library ID to unload.

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description discloses key behaviors: the 'default' library exclusion and the consequence of future calls failing. It doesn't mention permissions or reversibility, but it's sufficient for a simple unload operation.

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?

Two concise sentences convey all necessary information without extraneous detail.

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

Completeness4/5

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

Reasonably complete: describes action, constraint, and post-effect. However, lacks detail on return value or error handling, which could be helpful given no output schema.

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?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying that 'libraryId' cannot be 'default', a constraint not in the schema.

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 'Remove a loaded library from memory' and specifies the exception for the 'default' library, distinguishing it from loading or other library operations.

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

Usage Guidelines4/5

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

Provides explicit guidance on the 'default' library constraint and warns that subsequent calls with the same libraryId will fail, but does not compare to sibling tools like 'load_library' or 'list_libraries'.

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

validate_cemA

Validates the documentation completeness of a component in the Custom Elements Manifest. Returns a pass/fail result with a score and list of issues.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name to validate.

TDQS

A3.6/5.0

Behavior3/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 discloses the return format (pass/fail, score, issues) and implies a read-only operation (no mention of side effects). However, it does not discuss permissions, rate limits, states dependencies (e.g., need for a loaded library), or whether the tool modifies state. Given the absence of annotations, the description provides moderate but incomplete behavioral coverage.

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 extremely concise: two sentences that directly state the purpose and output. No extraneous words, and the key information is front-loaded. Every sentence earns its place.

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

Completeness4/5

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

Given the tool's low complexity (2 parameters, 1 required, no nested objects) and no output schema, the description adequately covers the return value. However, it misses stating that a library must be loaded for validation (implied by the libraryId parameter) and what 'documentation completeness' specifically entails. The description is mostly complete but has minor gaps.

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%, with both parameters (libraryId, tagName) already described. The description adds no new information about parameters beyond what the schema provides. According to guidelines, baseline is 3 when coverage is high, which is appropriate here.

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 ('Validates'), the resource ('documentation completeness of a component in the Custom Elements Manifest'), and the outcome ('Returns a pass/fail result with a score and list of issues'). It effectively distinguishes this tool from siblings, as none of the listed siblings specifically target documentation completeness.

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 does not provide guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or scenarios where other tools (e.g., validate_component_code, validate_usage) would be more appropriate. The usage context is only implied by the tool's purpose.

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

validate_component_codeA

ALL-IN-ONE validator — runs 19 anti-hallucination sub-validators on agent-generated code in a single call. Validates HTML attributes, slot children, attribute conflicts, a11y patterns, Shadow DOM CSS, custom properties, token fallbacks, theme compatibility, CSS specificity, layout patterns, inline styles, event bindings, method calls, composition patterns, component imports, color contrast, CSS scope, shorthand safety, and transition/animation patterns. Returns antiPatterns (component-specific negative examples) and auto-generated fix suggestions on issues. Use this as the FINAL check before submitting any code that uses web components.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`html`	Yes	The HTML markup to validate.
`css`	No	Optional CSS code to validate for Shadow DOM and custom property issues.
`code`	No	Optional JS/JSX/template code to validate event bindings.
`tagName`	Yes	The primary custom element tag name to validate against.
`framework`	No	Optional framework hint for event validation.

TDQS

A4.1/5.0

Behavior4/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 lists all validated aspects and states the output includes antiPatterns and fix suggestions. It does not mention side effects or limitations, but it is sufficiently transparent for a validation tool.

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 structured and front-loaded with the purpose. It lists validations efficiently and provides output details. While slightly verbose, it earns its sentences without redundancy.

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

Completeness4/5

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

Given the tool's complexity (6 parameters, many sibling tools, no output schema), the description covers the validation scope and output format well. It lacks details on return value structure or performance considerations, but overall it is complete enough for selection.

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%, setting a baseline of 3. The description does not add significant meaning beyond the schema; it only indirectly references parameters through the validated items. It meets the baseline but does not exceed it.

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: an all-in-one validator for agent-generated code, listing 19 specific sub-validators. It distinguishes itself from sibling tools by being a comprehensive final check rather than a focused validator.

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

Usage Guidelines4/5

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

The description explicitly says 'Use this as the FINAL check before submitting any code that uses web components.' This provides clear when-to-use guidance. It does not explicitly mention when not to use it or name alternatives, but the sibling tools are specific checks, so the context is clear.

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

validate_css_fileA

Validates an entire CSS file targeting multiple web components in one call. Auto-detects all web component tag names in selectors, runs per-component validation (Shadow DOM, ::part() resolution, token validation, scope checks) and global validation (theme compatibility, color contrast, specificity, shorthand). Each component result includes antiPatterns (negative examples) and each issue includes an inline fix object with corrected code + explanation. Returns issues grouped by component plus global issues. Use this when reviewing a CSS file that styles multiple components — no need to know which components are used.

ParametersJSON Schema

Name	Required	Description	Default
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`cssText`	Yes	The full CSS file content to validate.

TDQS

A4.3/5.0

Behavior4/5

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

No annotations, but description details validations performed (Shadow DOM, ::part(), tokens, contrast, etc.) and mentions antiPatterns and fix objects. Does not mention side effects, but likely read-only.

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?

Concise, front-loaded, every sentence adds value. Well-structured, no waste.

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

Completeness5/5

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

Complex tool with multiple validation types and grouped results. Description covers return format (issues grouped by component, fix objects) and key validations. No output schema, so description compensates well.

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 100%, baseline 3. Description adds minimal new meaning; libraryId and cssText descriptions are already in schema.

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 it validates a CSS file for multiple web components, auto-detects tags, and runs per-component and global validation. Distinguishes from siblings which are more specific.

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

Usage Guidelines4/5

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

Explicitly says to use when reviewing a CSS file with multiple components, implying not for single components or specific checks. Does not list alternatives but context of sibling tools provides that.

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

validate_usageA

Validates proposed HTML usage of a web component against its CEM spec. Checks for unknown attributes, deprecated properties, invalid slot names, and enum type mismatches. Returns a pass/fail result with specific issues and "did you mean?" suggestions for typos.

ParametersJSON Schema

Name	Required	Description
`libraryId`	No	Optional library ID to target a specific loaded library instead of the default.
`tagName`	Yes	The custom element tag name (e.g. "my-button").
`html`	Yes	The HTML snippet to validate (e.g. "<my-button variant=\"primary\">Click</my-button>").

TDQS

A3.7/5.0

Behavior3/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 mentions that validation is against a CEM spec and returns pass/fail with issues and suggestions, but does not clarify key behaviors such as whether it requires a loaded library (parameter libraryId hints at it) or if it modifies state. It also doesn't explain default library behavior.

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?

Three concise sentences: first states the action, second lists specific checks, third describes output. Front-loaded with purpose, no redundant 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 complexity (3 params, no output schema, many sibling tools, no annotations), the description provides the core functionality but lacks context on dependencies (e.g., requirement to load a library first) and integration with other tools. The output description is minimal but sufficient for a validation 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 each parameter is already described. The tool description adds no extra meaning to the parameters beyond listing them. Baseline 3 is appropriate as the description does not need to compensate for missing schema 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 ('validates') and the resource ('proposed HTML usage of a web component against its CEM spec'). It lists specific checks (unknown attributes, deprecated properties, etc.), distinguishing it from sibling tools like check_html_usage which likely perform simpler validation.

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?

No explicit guidance on when to use this tool versus alternatives (e.g., check_html_usage, validate_cem). The description implies use for spec-based validation but does not state prerequisites (e.g., library must be loaded) or exclusions.

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

verify_extensionA

Audit an extending component against its parent's contract surface. Catches slot drift, ARIA regressions, lost form-association, suppressed events, missing forced-colors blocks, sub-44px touch targets, and broken accessible-label devWarn patterns. Findings reference defect-corpus classes 05-11. Use this BEFORE shipping any helix-pattern subclass.

ParametersJSON Schema

Name	Required	Description
`parentTagName`	Yes	Tag name of the parent component (e.g. "hx-button").
`subclassTagName`	Yes	Tag name of the extending subclass (e.g. "figgy-button").
`subclassSourcePaths`	No	Optional subclass source paths for deeper checks. Without these, the audit only inspects the CEM surface.
`libraryId`	No	Optional library ID for multi-library workspaces (resolved by the dispatcher).

TDQS

A4/5.0

Behavior4/5

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

No annotations exist, so the description carries the full burden. It details what the tool catches and notes that without subclassSourcePaths, the audit only inspects the CEM surface. No contradictions; the behavior is well disclosed.

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 paragraph that efficiently front-loads the purpose and then lists specific issues. It is clear and not overly verbose, though it could benefit from bullet points or a more structured format.

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, the description explains the audit scope and behavior well. However, it does not describe the return format or what findings look like, which is a gap for an audit tool. Adequate but could be more complete.

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% (all parameters described in the schema). The description adds value by explaining the impact of subclassSourcePaths (deeper checks vs. CEM surface only), but this is only a slight enhancement over the schema. 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 audits an extending component against its parent's contract surface, listing specific issues it catches (slot drift, ARIA regressions, etc.) and referencing defect-corpus classes. This distinguishes it from other audit/check tools in the sibling list.

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

Usage Guidelines4/5

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

The description explicitly says 'Use this BEFORE shipping any helix-pattern subclass', providing clear usage context. However, it does not mention when not to use or suggest alternative tools, which would improve the score.

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

verify_token_inheritanceA

Audit a component for token-related defects across helix R8/R11/R14/R32 alias renames, cascade gaps under dark / high-contrast overlays, and raw color literals where tokens exist. Findings reference defect-corpus classes 01, 02, 03, 14. Use this BEFORE shipping an extending component or migrating across helix major versions.

ParametersJSON Schema

Name	Required	Description
`tagName`	Yes	Custom element tag name (e.g. "hx-button").
`cssSourcePaths`	No	Optional CSS source paths (relative to projectRoot). When provided, the color-literal scan runs across them. Without this, only the CEM-declared cssProperties surface is checked.
`overlays`	No	Optional pre-computed CSS-prop key sets per theme overlay. Used by the cascade-gap check.
`libraryId`	No	Optional library ID for multi-library workspaces (resolved by the dispatcher).

TDQS

A3.7/5.0

Behavior2/5

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

No annotations provided, so description must fully disclose behavioral traits. It describes what defects are checked but does not state whether the tool is read-only, requires permissions, or has side effects. The read-only nature is implicit from 'audit' but should be 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?

Two sentences, front-loaded with action and scope. Every sentence adds value without waste.

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?

With no output schema, the description should explain what findings look like or how to interpret defect classes. It mentions 'defect-corpus classes' but does not elaborate on output format. Adequate for an audit tool but leaves gaps.

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 each parameter already has a description. The tool description does not add meaning beyond the schema, e.g., how parameters affect the audit. 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?

Description clearly states the tool audits a component for token-related defects including alias renames, cascade gaps, and color literals. It distinguishes from sibling tools like analyze_token_canonicality or check_token_fallbacks by covering a broader set of defects and referencing specific defect classes.

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

Usage Guidelines4/5

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

Description explicitly advises using this tool before shipping extending components or migrating helix major versions. While it doesn't list when not to use or alternatives, the context is clear and actionable.

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

Install Server

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

TDQS

A3.6/5.0

Disambiguation3/5

Many tools have distinct purposes, but there is significant overlap between the all-in-one validator (validate_component_code) and multiple individual check tools. Similarly, styling_preflight and validate_css_file have overlapping functionality, which could confuse an agent on which to call.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (e.g., check_color_contrast, generate_types). A few outliers exist like 'styling_preflight' (noun_verb) and 'diff_cem' (abbreviation), but overall naming is predictable and consistent.

Tool Count3/5

79 tools is higher than typical, but the server covers a broad domain of web component development (analysis, validation, code generation, health, etc.). The count is borderline; some tools could be merged (e.g., the many check_ tools) without losing functionality.

Completeness4/5

The tool surface covers nearly all aspects of working with web components: discovery, validation, code generation, health monitoring, and more. Minor gaps exist (e.g., no tool for bulk component migration), but the set is very comprehensive for its stated purpose.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

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

UnifAPI
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181

Related MCP Servers

w3c-mcp
Developer Tools Documentation Access Search
shuji-bonji
A
license
A
quality
C
maintenance
MCP Server for accessing W3C/WHATWG/IETF web specifications. Provides AI assistants with access to official web standards data including specifications, WebIDL definitions, CSS properties, and HTML elements.
Updated 10 days ago (2026-08-24 15:06 UTC)
11
33
4
MIT
ds-pilot
Design Tools Developer Tools
lyse-labs
A
license
Not graded
quality
C
maintenance
MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
Updated 4 months ago (2026-05-13 14:09 UTC)
18
9
MIT
Component Library MCP
Developer Tools Code Analysis
vasyl-bilous
A
license
B
quality
D
maintenance
An MCP server that scans React and Vue projects, extracts component metadata (props, slots, events, imports, usage), and exposes it to AI coding agents via structured tools.
Updated 4 months ago (2026-04-28 17:00 UTC)
7
1
MIT
api-docs-mcp
Documentation Access Developer Tools
DucDA177
A
license
Not graded
quality
D
maintenance
An MCP server that enables AI agents to explore, search, and query API definitions from OpenAPI/Swagger JSON files.
Updated 7 months ago (2026-01-27 14:25 UTC)
59
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/bookedsolidtech/helixir'

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