A modern template combining FastAPI REST API with MCP (Model Context Protocol) server for LLM integration, providing CRUD operations for items and users with comprehensive error handling and logging.
8 tools with complete schemas and descriptions. Naming follows verb_noun convention (get_, create_, update_, delete_, search_). Descriptions are present (avg ~80 chars) but lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. Parameters have types and descriptions. No output schemas documented. Error handling not visible in tool definitions. Missing tool annotations (readOnlyHint, destructiveHint). Composition is sound, tools are single-responsibility and chainable (e.g., search_items → get_item_by_id). No secrets exposed as parameters.
Create a new item in the database.
Delete an item from the database.
Export all database data as JSON.
Get statistics about the database.
Get a specific item by its ID.
Get items from the database with optional filtering.
Search for items by field value.
Output schemas not documented. LLMs cannot infer what fields to expect from tool responses, forcing them to guess at downstream field names and risk broken tool chains.
Tool annotations missing. delete_item and destructive operations lack destructiveHint; read-only tools lack readOnlyHint. Agents cannot distinguish safe from unsafe operations without explicit hints.
Descriptions lack WHEN-to-use guidance. 'Get items from the database' does not explain when to call get_items vs. search_items vs. get_item_by_id. LLMs waste reasoning cycles deciding between similar tools.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | <=2025-11-25 | v2 |
Update an existing item.
No dry-run or confirmation pattern for delete_item. Agents can irreversibly delete items without a safety gate. Destructive operations should support confirmation before execution.
Error handling not visible in tool definitions. No guidance on retryability, user-fixable errors, or recovery steps. Agents will not know how to respond to failures.