An MCP server for managing a todo list with add, list, get, complete, and delete operations stored in a local JSON file.
Server has 5 tools with clear verb-noun naming (add_todo, list_todos, get_todo, complete_todo, delete_todo). All tools have descriptions (10-50 chars) and visible input schemas with type definitions. However, descriptions are minimal (under 50 chars), lacking context on WHEN to use each tool or what happens on error. Parameter descriptions are present but terse. Output schemas are not documented, LLMs cannot predict response structure. Error handling returns dict with 'error' or 'message' keys but provides no recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (WRITE, DESTRUCTIVE). Missing pagination guidance for list_todos despite potential for growth.
Add a new todo item to the list.
Mark a todo item as completed.
Delete a todo item permanently.
Get a single todo item by its ID.
View all todo items currently saved, both completed and not completed.
Output schemas not documented. LLMs cannot predict response structure (dict with 'error'/'message'/'todo'/'count' keys). Breaks downstream tool chaining and forces agents to guess field names.
Tool descriptions are minimal (10-50 chars). Missing context on WHEN to use each tool, what state changes occur, and error recovery paths. Descriptions should be 50-200 chars with actionable guidance.
No tool annotations despite clear risk levels. delete_todo is DESTRUCTIVE but lacks destructiveHint. complete_todo and add_todo lack idempotentHint/readOnlyHint. Agents cannot reason about retry safety or side effects.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 55 | 2026-07-28+ | v2 |
Error responses lack recovery guidance. 'No todo found with id X' tells agent nothing, should suggest 'Call list_todos() to see available IDs' or return available alternatives.
list_todos lacks pagination parameters (limit, offset) and result cap. As todo count grows, response bloats context window. Should document max results and offer pagination.