An offline Notes and FAQ Search MCP server for the NextFlows Academy project.
Server has well-structured tool definitions with complete schemas and descriptions for all 7 tools. Naming follows verb_noun convention (search_notes, get_note, add_note, etc.). All parameters include type definitions and descriptions with constraints (minLength, maxLength, pattern, minimum, maximum). However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs alternatives. Error handling is minimal, no recovery guidance or actionable error messages visible in tool implementations. Output schemas are not documented. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels. Composition is sound: tools are single-responsibility and chainable (search returns IDs that get_note accepts).
Create a new note with title, content, and optional tags
Delete a note by its ID
Retrieve a specific note by its ID
List locally stored notes, optionally filtered by tag
Search locally stored FAQ entries by query text
Search locally stored notes by query text
Update an existing note's title, content, or tags
Tool descriptions lack LLM-optimized guidance. Descriptions are 40-60 chars, below the 50-200 char baseline for A+ tools. Missing WHEN to use each tool and how it differs from similar tools (e.g., search_notes vs list_notes). No dependency hints or prerequisites stated.
No output schemas documented. Tool implementations return results but LLMs cannot see what fields to expect. Prevents downstream tool chaining and forces LLMs to guess field names.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels. delete_note is DESTRUCTIVE but unmarked. search_notes and get_note are READ_ONLY but unmarked. Prevents LLMs from reasoning about safety and retry logic.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | 2026-07-28+ | v2 |
Error handling not visible in source. No recovery guidance, actionable error messages, or error classification (retryable vs user-fixable vs fatal). Agents cannot self-correct on failures.
Destructive operations (delete_note) lack confirmation or dry-run support. Agents can permanently delete notes without a safety gate. No compensation tools to undo deletions.