MCP server for managing customer records and processing refunds
Two tools with clear verb-noun naming (get_, trigger_) and basic schemas. Both have descriptions and input validation via Zod. However, descriptions are minimal (34-56 chars, below the 50-200 char LLM-optimized baseline), parameter descriptions lack context about constraints and error recovery, and output schemas are not documented. No error guidance for LLMs (e.g., what to do if customer not found). Missing tool annotations (readOnlyHint, destructiveHint). Composition is sound but descriptions need expansion to meet production standards.
Retrieve a customer record using a customer ID
Process a mock refund for an existing customer
Descriptions are too brief (34-56 chars vs. 50-200 char baseline). 'Retrieve a customer record using a customer ID' lacks context on when to use this tool, what it returns, or error recovery paths.
Parameter descriptions are missing or minimal. 'customer_id' has no description in tool registration (only in schema). 'amount' and 'reason' lack guidance on constraints, error cases, or recovery hints.
Output schemas are not documented. LLMs cannot plan downstream calls or extract fields without knowing the response structure. No documentation of refundId, status, processedAt fields.
Error responses lack recovery guidance. When customer not found, the error message does not suggest next steps (e.g., 'Try searching with a partial name' or 'Available customer IDs: CUST-12345, CUST-67890').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
Missing tool annotations. trigger_refund is destructive (WRITE risk) but lacks destructiveHint annotation. get_customer_record is read-only but lacks readOnlyHint. These hints help LLMs reason about safety and retry logic.