MCP server exposing the linux-hardware homelab lab as queryable tools for reading hardware diagnostics, scripts, and troubleshooting guides.
Server exposes 7 read-only tools with basic schemas and descriptions. All tools have names starting with action verbs (list_, get_, search_, symptom_lookup) and non-empty descriptions (range 50 - 180 chars). Input schemas are present with type declarations. However, descriptions lack LLM-optimized guidance on WHEN to use each tool vs. alternatives, parameter descriptions are minimal (e.g., 'Topic name' without enum values), and output schemas are not documented. No error handling guidance, no recovery paths. Naming is clear but generic ('get_readme', 'get_script', 'get_cheatsheet' could be more specific about content type). Tool composition is sound, each does one thing, but descriptions do not explain dependencies or sequencing (e.g., 'call list_topics first to orient').
Return the global cheatsheet, or one topic's section. Args: topic: Optional topic name. If omitted, returns the full cheatsheet.
Return a topic's full README markdown. Args: topic: One of: 01-hardware, 02-disk-io, 03-network-io, 04-memory, 05-performance, 06-app-debugging, 07-network-debug.
Return the full source of a script. Args: path: Path relative to the repo root, e.g. "01-hardware/02-pcie-link-status.sh".
List scripts in a topic, with each script's `Scenario:` block. Stress scripts are flagged with `destructive: true` — they require `yes-i-understand` confirmation when run.
List the seven topic directories with one-line descriptions. Use this first to orient. Topics are returned in numeric order.
Naive grep across READMEs and script header comments (top 30 lines). Args: query: Search term (case-insensitive regex). max_results: Maximum number of results to return (default 30).
Parameter descriptions are minimal and lack enum constraints. 'topic' param in get_readme lists valid values in the description text (01-hardware, 02-disk-io, etc.) but not as a formal enum in the schema. LLMs cannot parse text constraints reliably, they need JSON Schema enums.
Output schemas are not documented. Tools return unstructured text (README markdown, script source, search results) without specifying field names, types, or structure. LLMs cannot plan downstream calls or extract structured data reliably.
Descriptions lack WHEN-to-use guidance and tool sequencing hints. E.g., 'list_topics' says 'Use this first to orient' but other tools do not explain their relationship to list_topics or when to call them instead of search(). LLMs waste reasoning cycles deciding between similar tools.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
Find symptom rows whose first column mentions the keyword. Args: keyword: Symptom keyword to search for.
No error handling or recovery guidance. If a topic name is invalid, search returns no results, or a script path does not exist, tools do not indicate what the LLM should do next (retry, call a discovery tool, ask the user). Bare failures block agent progress.
search() and symptom_lookup() have overlapping intent but no description explaining when to use one vs. the other. Both search for keywords, one across READMEs/headers, one across symptom rows. LLMs will guess which to call.