This server has 4 tools with clear naming and reasonable descriptions, but suffers from critical gaps in schema documentation, parameter descriptions, and error handling guidance. All tools are READ_ONLY web scraping operations with basic error handling that returns generic messages. Input schemas are present but minimal, only URL parameters with descriptions. Output schemas are entirely undocumented. The server lacks idempotency guarantees, pagination support, and actionable error recovery guidance. Most critically, there is no documentation of what fields these tools return or how downstream tools should use the results.
Output schemas are completely undocumented. Tools return JSON structures (colors, typography, skill.md) but LLMs cannot know what fields to expect, making downstream tool chaining impossible and forcing agents to parse unstructured output.
Error handling returns generic messages without recovery guidance. Errors like 'Error extracting design system: <message>' or 'Error extracting colors: <message>' do not tell the agent what to do next, whether to retry, or what the root cause was.
No idempotency guarantees documented. Web scraping tools are inherently stateless, but there is no declaration that repeated calls with the same URL produce identical results, or if they differ (due to dynamic content), how the agent should handle variance.
extract_design_systemget_site_colors
Recommendations
Document the complete output schema for each tool. For extract_design_system, specify: 'Returns a text/markdown field containing the generated skill.md file. Format: Markdown with sections for colors, typography, layout rules, and component specs.' For get_site_colors, specify: 'Returns an object with primary (array of color objects with hex, rgb, usage, name), secondary, neutral, cssVariables (map of CSS custom property names to values), and totalColors (number).' For get_site_typography, document the returned structure (fonts array, sizes, weights, line-heights, etc.).
Enhance error messages with recovery guidance. For 'Error extracting colors: <message>', add context like: 'if message contains "timeout", suggest retry; if "not found", suggest "URL may not be publicly accessible, ensure it is a published website"; if "no colors detected", suggest "website may use dynamic styling or CSS-in-JS, extraction may be incomplete."'
Add explicit idempotency guarantees to each tool description. E.g., 'Calling this tool multiple times with the same URL will produce identical results. Note: if the target website updates its styles, results may differ between calls; results always reflect the current state of the live site.'
Implement result size limits and pagination. For extract_design_system, add optional parameters 'max_lines: number (default 2000)' and 'include_components: boolean (default true)' to control output scope. For get_site_colors, add 'limit: number (1-500, default 100)' to cap color count. Specify in descriptions: 'Results are limited to 2000 lines to avoid context window overflow. Increase limit at your own risk.'
No pagination or result limiting declared. If a design system extraction returns large amounts of CSS or typography data, there is no mechanism to page results or cap output size, risking context window overflow.
Parameter descriptions lack format/constraint details. The 'url' parameter is declared as z.string().url() (which validates URL format in TypeScript), but the description does not explicitly state format requirements, accepted protocols (http vs https), or any restrictions on domains (e.g., 'https only', 'public sites only').
Tool composition assumes no follow-up. A user calling extract_design_system gets back skill.md content, but there is no way to request just colors, just fonts, or specific sections without running the full extraction again. The dedicated get_site_colors and get_site_typography tools help, but their relationship is not documented.
Clarify URL constraints in parameter descriptions. Replace 'The website URL to extract design system from' with: 'A publicly accessible website URL (http:// or https://, no local/private IPs). Must be a valid, live website; extracted content reflects the current live state of the site.'
Document tool relationships and when to use each. Add to extract_design_system description: 'Use this for a complete design system snapshot. For color-only or typography-only extraction, use get_site_colors or get_site_typography instead, they are faster and produce smaller outputs.'
Return structured, chainable data. Modify get_site_colors to return: { primary: [{hex, rgb, semanticName, usage, confidence}], secondary: [...], neutral: [...], cssVariables: {}, metadata: {totalExtracted: number, extractionTimeMs: number} } with explicit field names so agents can reference specific colors in follow-up calls.
Add a dry-run or preview mode. For extract_design_system, add optional parameter 'preview: boolean (default false)'. When true, return only first 500 characters of skill.md and a summary of what will be extracted, allowing the agent to preview before requesting full output.