MCP server for searching official Magnolia CMS documentation
Single tool with adequate naming but significant gaps in description detail, parameter annotations, output schema documentation, and error handling. The tool name 'search_magnolia_docs' correctly uses verb_noun convention and is action-specific (pattern:tool compliant). However, the description is minimal (58 chars, below the baseline p10=34 but sparse for meaningful LLM selection). The input schema is present with proper JSON Schema structure, but the 'query' parameter description is overly brief ('Search term'), lacks guidance on expected input format, examples of valid queries, or search syntax. No output schema is documented, the code returns a hardcoded JSON structure (title, url, snippet) but this is never declared to the LLM, forcing it to infer the response shape. Error handling is present (try/catch) but returns generic 'Search error: {message}' without recovery guidance (pattern:recovery-guide violation). The tool description does not indicate what it returns, making chaining difficult.
Search the official Magnolia CMS documentation
Output schema not documented. The tool returns JSON with fields (title, url, snippet) but this structure is never declared in the tool definition. LLMs cannot plan downstream operations on a structure they don't know. Requires explicit outputSchema field or response_format parameter in the MCP spec.
Parameter description too vague. 'Search term' (11 chars) does not explain what constitutes valid input: is it a free-form string? Does it support operators (AND, OR)? Does it match titles or body content?
Tool description does not state what is returned. At 58 chars, it falls below the baseline p10=34 and provides no hint about response structure, pagination, or result limits. Guidance missing: 'Returns up to 5 results with title, URL, and snippet. No pagination support.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 43 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 34 | - | v1 |
Error handling lacks recovery guidance. Code returns 'Search error: {message}' as plain text, not actionable for the LLM. Per pattern:recovery-guide, errors should say what to do next (e.g., 'Search failed due to network timeout. Retry in 10 seconds.' or 'No results found. Try a simpler query or check docs.magnolia-cms.com directly.').
Hardcoded result limit (5) not advertised in description. The code enforces a cap but the tool description never mentions it, violating pattern:enforce-result-limits. LLMs may expect pagination or assume all results are returned.
CSS selector selectors hardcoded and likely brittle. The code assumes HTML structure with classes '.search-result', '.title', '.snippet', if Magnolia's docs site HTML changes, the tool silently returns empty results. No validation that selectors matched any elements.