Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
The server provides 5 tools with basic structure, but has significant quality gaps. Tool names are reasonably clear (verb_noun pattern), but descriptions are minimal and parameter annotations lack depth. Input schemas are present for all tools but inconsistently documented. Error handling exists but provides no recovery guidance. Output schemas are not documented. The schema completeness is moderate, but LLM-facing documentation is weak.
Destructive operation (delete_expense) lacks confirmation mechanism or dry-run support. No explicit statement in description that this is irreversible.
Category parameter appears in 3 tools but is free-form string with no enum constraint. Valid categories are hardcoded in categories.json ('food', 'transport', etc.) but LLMs are not told what values to pass.
Error handling is minimal and non-actionable. list_expenses returns [{'error': '...'}] which is awkward. No recovery guidance (e.g. 'Invalid date format. Use YYYY-MM-DD') in most tools.
Recommendations
Add explicit output schemas to all tool docstrings. Example for add_expense: 'Returns: {"status": "success"|"error", "id": <int>, "message": <string>}'
Implement confirmation flow for delete_expense: add a 'confirm' parameter (bool, default false) and return {"status": "confirm_required", "expense_id": <id>, "message": "Are you sure? This cannot be undone."} on first call, then execute on confirm=true. Or implement MRTR pattern (Multi Round-Trip Request) with result:input_required.
Convert 'category' parameters to enums by reading categories.json at startup and validating against it. Document valid values in parameter description: 'Category enum: food|transport|utilities|entertainment|shopping|health|education|other'
Expand tool descriptions to 100-200 chars with use-case context. Example for list_expenses: 'Retrieve a list of recent expense entries, optionally filtered by date range or category. Use this to explore past spending before generating a summary. Returns up to 50 entries ordered by date (newest first).'
Add recovery guidance to error messages. Example in add_expense: 'Invalid category "%s". Valid options: food, transport, utilities, entertainment, shopping, health, education, other' instead of generic error.
Document that list_expenses has a hard limit of 50 results. Add a 'next_cursor' field to response (or add offset/page parameters) to enable true pagination. Describe in tool docstring: 'Results are ordered by date (newest first). Pass limit=50 to get the first 50; use offset=50 for the next batch.'
analyze_expenses_with_ai relies on Gemini API setup that can silently fail (setup_gemini() returns None if key is missing). Tool does not check if gemini_model is available before invoking it. Missing error message for user.
Tool descriptions are generic and short (24-57 chars). Baseline for A+ tools is 194 chars. Descriptions lack context on use cases, distinctions from similar tools, or prerequisites.
No pagination or result limiting documented in tool descriptions. list_expenses accepts 'limit' parameter with default 50, but LLM is not told this is a limit or how to paginate for more results.
add_expense does not return the full expense object (id, date, amount, category, etc.), only a success message with id. Downstream tools or agent interactions may need full data.
add_expense
Have add_expense return the full expense object: {"status": "success", "expense": {"id": <id>, "date": <date>, "amount": <amount>, "category": <category>, "subcategory": <subcategory>, "note": <note>, "created_at": <timestamp>}}
Add explicit check in analyze_expenses_with_ai: if gemini_model is None, return {"status": "error", "message": "Gemini AI not configured. Set GEMINI_API_KEY environment variable."}
For delete_expense, document expected response: {"status": "success", "message": "Expense <id> deleted.", "id": <id>} so LLM knows what to expect.
Add min/max constraints to numeric parameters. Example: 'amount' should validate > 0; 'days' in analyze_expenses_with_ai should be 1-365. Document in descriptions: 'Expense amount in currency units (must be positive, e.g. 50 for ₹50)'.