The css-is-awesome MCP server exposes 32 tools with consistent naming patterns (verb_noun structure) and documented descriptions. However, there are critical gaps in parameter descriptions, output schema documentation, and error handling guidance. All tools are READ_ONLY, which is positive for safety. The server follows a clear pattern of list/get/search variants for design system resources (themes, mixins, functions, tokens, animations, components, recipes) plus file readers and utility tools. However, most tools lack detailed schema documentation for their responses, only input schemas are visible. Parameter descriptions are present but often generic ('The name of the [resource] to retrieve'). No tools demonstrate error recovery guidance or structured error responses. The naming is consistently clear (get_theme, search_tokens, resolve_size), but descriptions average ~70 characters and lack actionable guidance on when to use each tool or what it returns structurally.

• Add complete output schema documentation for every tool. At minimum, document return field names, types, and semantics. For list_* tools, clarify if results are paginated, total count is included, and what the default/max limit is.
• Replace generic parameter descriptions with concrete guidance. For get_theme, change 'The name of the theme to retrieve' to 'The theme name (case-sensitive; see list_themes for available options)'.
• For search_* tools, document the search algorithm: Is it substring match, fuzzy, regex? Case-sensitive? Which fields does it search across?
• Add error recovery guidance to parameter descriptions. E.g., 'If the theme name is unknown, call list_themes first or use search_themes with a partial name.'
• For read_* file tools, document the file size/line count and advise on context impact. E.g., 'Returns the full README.md (~2KB). For large responses, consider reading specific sections.'
• For theme_from_tokens, document the expected structure of the tokens object (a detailed example or JSON schema).
• For assemble_prompt, enumerate the allowed intent values and valid args keys for each intent.
• Add tool annotations (readOnlyHint: true) to all tools in the server definition to make safety metadata explicit.
• Consider consolidating list_* and search_* variants with optional parameters (e.g., a single discover_resources tool with optional query and limit params) to reduce cognitive load.
• Add pagination parameters (limit, offset/cursor) to list_* tools to future-proof against large result sets.