A demo MCP server that manages user data with tools for creating users, generating random users, and accessing user resources via prompts
Two tools registered with explicit schemas and descriptions. Naming is action-verb-based and clear. Descriptions are adequate (80-90 chars) but lack critical details about side effects and prerequisites. Input schemas are well-structured with Zod validation and parameter descriptions. However, output schemas are not documented, LLMs receive untyped text responses. Tool annotations are present but generic. Error handling returns human-readable messages but lacks recovery guidance or error classification. The 'create-random-user' tool relies on deprecated server-initiated Sampling pattern (sampling/createMessage), which is a protocol compliance issue addressed separately.
Create a new random user and save to users.json file
Create a new user and save to users.json file
Output schemas not documented. Tools return untyped text content wrapped in a generic structure. LLMs cannot determine what fields to expect or plan downstream calls. Both tools return only {content: [{type: 'text', text: '...'}]} with no structured data. Baseline: 100% of A+ tools have documented return types.
create-random-user uses server-initiated Sampling (sampling/createMessage). This pattern is deprecated since ~2025-03. Servers should integrate directly with LLM provider APIs instead of delegating sampling to the host. Migration: either accept user-provided user data as a parameter, or call the LLM provider's API directly within the tool implementation.
Tool descriptions lack context about when to use them and operational side effects. 'Create a new user and save to users.json file' is functional but does not state: (1) this modifies persistent state, (2) users are idempotent or not (calling twice with same data creates duplicate IDs), (3) what IDs are valid, (4) success criteria. Baseline: descriptions should answer 'What does it do? When should the LLM call it instead of a similar tool? What does it return?'
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 50 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 37 | - | v1 |
Error handling does not classify errors or guide recovery. Both tools return {isError: true} or {content: [error text]} with no indication whether the error is retryable, user-fixable, or fatal. Example: 'Failed to create user: ENOENT' tells the LLM nothing about what to do next. Baseline: error responses must tell the LLM what to do next and categorize as retryable/user-fixable/fatal.
create-random-user has no declared input schema. The tool accepts no parameters (empty {}), but the lack of explicit schema declaration means LLMs cannot validate inputs or understand what the tool does without reading implementation. Baseline: every tool must have a documented input schema.
Tool annotations are generic and misleading. Both tools declare {readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true}. 'destructiveHint: false' is incorrect, both tools write to users.json and are destructive operations. 'idempotentHint: false' is correct but should clarify that calling twice creates duplicate users. 'openWorldHint: true' is unclear in this context. LLMs rely on accurate annotations for safety and replay logic.
create-user requires email parameter with email() validation, but no format guidance in description. 'User's email address' does not clarify format constraints. Baseline: parameter descriptions should include format, range, and allowed values (e.g., 'Valid email address (RFC 5322 format)').