A custom MCP server that implements a simple notes system demonstrating core MCP concepts like resources and tools
Single tool 'create_note' has a proper schema with all required fields typed and described. However, the description is minimal (21 characters), lacking context about the tool's behavior, when to use it, or what happens to state. No error handling guidance, no idempotency notes, and parameter descriptions are generic. The tool follows basic naming conventions but lacks depth in documentation expected for production-grade agents. Output schema is implicit rather than explicitly documented, forcing LLMs to infer the response structure.
Create a new note
Tool description is only 21 characters ('Create a new note'). Baseline for A+ tools is 194 chars. Missing context on state mutation, idempotency, side effects, and when this tool should be selected over alternatives.
Output schema is not explicitly documented. The response structure is inferred from code ('Created note {id}: {title}' text). LLMs cannot plan downstream calls or extract structured data without a documented response schema.
No error handling guidance. If title or content are empty, the error is 'Title and content are required', generic and offers no recovery path. Should guide LLM on retry strategy and whether error is retryable.
Parameter descriptions are minimal. 'Title of the note' and 'Text content of the note' do not specify length limits, format constraints, or character restrictions. Baseline annotation length is 72 chars; these are ~25 chars each.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 49 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 42 | - | v1 |
No mention of idempotency. If an agent retries create_note with identical title and content, will it create a duplicate note? The in-memory ID generation strategy (Object.keys(notes).length + 1) suggests yes, creating a hazard for retry logic.
No resource chaining support documented. After create_note succeeds, an agent may want to read that note via ReadResource. The response includes the note ID, but no explicit documentation that this ID can be used in note:///{id} URIs.