Spring MCP Demo exposes 4 shopping cart tools with basic descriptions and input schemas. All tools have descriptions (10-100 chars) and typed parameters, but lack depth for LLM optimization. Naming is clear (verb_noun pattern: addItem, removeItem, getCart, clearCart). Schemas are present but minimal, no output schemas documented, no pagination, no error guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Descriptions are functional but generic; they do not explain WHEN to use each tool or what happens on failure. Parameter descriptions are present but terse. No evidence of idempotency, retry guidance, or recovery paths. This is a minimal proof-of-concept, not production-grade.

• Add output schemas for all tools. Document what getCart returns (e.g., {items: [{name, quantity, price}], total, itemCount}). This enables LLMs to plan downstream operations.
• Add tool annotations: mark getCart with readOnlyHint=true; mark addItem, removeItem, clearCart with destructiveHint=true (or idempotentHint for addItem if it is idempotent). This guides LLM retry logic.
• Expand descriptions to 50-150 chars with recovery hints. E.g., 'Remove an item or reduce its quantity. If quantity exceeds available stock, returns error with available quantity.' This teaches LLMs how to handle failures.
• Document parameter constraints explicitly. For removeItem.quantity, state: 'Quantity to remove (positive integer). If 0 or omitted, removes all of the item. If quantity exceeds available stock, returns error.'
• Add error response examples in tool documentation (not in descriptions). E.g., 'Error: Item not found in cart. Available items: [apple, banana].' This enables LLMs to self-correct without extra discovery calls.