Bar Assistant MCP has 8 tools with explicit schemas and descriptions visible in server.py. However, the implementation exhibits significant gaps in parameter descriptions, output schema documentation, and error handling guidance. Naming is consistent (verb_noun pattern) but descriptions are minimal (average ~80 chars, below the 194-char production baseline). Parameter descriptions exist but are brief and lack constraints (enums, ranges, formats). No output schemas are documented, making it unclear what fields agents should expect. Tool chaining dependencies are mentioned in some descriptions (e.g., create_cocktail references search_ingredients first) but not consistently. The server lacks error handling guidance, recovery hints, and actionable error messages. Pagination is supported (page parameter) but no total count or next_cursor is documented. Security: environment variable injection is implemented correctly (BAR_ASSISTANT_TOKEN, BAR_ASSISTANT_BAR_ID), but the tool definitions do not declare required permissions. Overall, this is a functional but below-median implementation that would benefit from more complete descriptions and explicit output schema documentation.
No output schemas documented. Tools return data from Bar Assistant API but responses are not formally specified, forcing LLMs to guess at field structure and breaking tool chaining.
Parameter descriptions lack constraints (enums, ranges, formats). E.g., 'page' has no minimum/maximum; 'strength' has no unit specification; 'bar_id' uses 'number' type but should clarify integer-only. LLMs cannot self-validate without explicit constraints.
No error handling guidance. Tools lack recovery hints (e.g., 'If bar not found, call list_bars()'), error classification (retryable vs fatal), or actionable error messages. API failures will produce opaque responses.
Recommendations
Add full output schemas for all 8 tools. For list_bars, document the structure: [{id: number, name: string, description?: string, created_at?: string}, ...]. For get_shelf_ingredients, document fields like: {data: [{id, name, strength?, color?, description?}, ...], total: number, page: number}.
Expand parameter descriptions to 50 - 150 chars with explicit constraints. Example: 'bar_id (number, positive integer; optional if BAR_ASSISTANT_BAR_ID env var is set). Identifies which bar to query.' Replace 'page: Page number for pagination (optional)' with 'page (positive integer, minimum 1, default 1). Results per page defaults to 20. Omit if fetching first page.'
Add enums and ranges for constrained parameters. E.g., strength: {type: 'number', minimum: 0, maximum: 100, description: 'Alcohol strength as ABV percentage (0-100). E.g., 40 for 40% ABV.'}. For create_cocktail ingredients array, change schema to {type: 'array', items: {type: 'object', properties: {id: {type: 'number'}, amount: {type: 'number', minimum: 0}, units: {type: 'string', enum: ['ml', 'oz', 'dash', 'tsp', 'tbsp'], description: 'Unit of measurement'}}, required: ['id', 'amount', 'units']}}.
Add error handling guidance in tool descriptions. E.g., for add_ingredients_to_shelf: 'Fails with 404 if bar_id does not exist (call list_bars() to find valid bar IDs) or if any ingredient_id is invalid (call search_ingredients() first). On network timeout, wait and retry; the operation is idempotent.'
Implement a dry_run parameter for destructive operations (remove_ingredients_from_shelf, create_cocktail). When true, return the expected result without modifying state, letting agents preview changes.
Score history
Overall score trend
↑ 40 points across a rubric change (v1 → v2)
55/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
55
2026-07-28+
v2
2026-03-09
F
15
-
v1
destructiveauthsource verified78/100
Remove ingredients from your bar shelf by their IDs
Destructive/write operations (remove_ingredients_from_shelf, create_ingredient, create_cocktail) lack confirmation or dry-run capability. Agents can make irreversible mistakes without a safety gate.
Tool descriptions below production baseline (average 80 chars vs 194 expected). Too brief to guide LLM selection. E.g., 'Get all ingredients currently on your bar shelf with detailed information' does not explain when to use this vs search_ingredients.
create_cocktail expects an 'ingredients' array with 'id, amount, and units' per the description, but the schema only declares {'type': 'object'} with no properties. LLMs cannot know the exact field names needed.
Pagination support (page parameter) but no total_count or next_cursor documented. LLMs cannot determine if more results exist or how many pages to retrieve.
Document pagination fully. Add 'total_count' and 'page_count' fields to responses. Update tool descriptions: 'Supports pagination. Pass page=2 for second batch. Returns up to 20 items per page; set limit parameter (1-100) to customize. Omit if you want defaults.'
Add per-tool permission scope declarations in the description. E.g., 'Requires: read:shelf. Callable by: bar owner, editors, viewers.' For write/destructive ops: 'Requires: write:shelf or admin. Callable by: bar owner, editors.'
Clarify tool selection differences in descriptions. E.g., get_shelf_ingredients retrieves 'ingredients already added to your shelf'; search_ingredients finds 'any ingredient in the database (not yet added to shelf)'. This prevents LLM confusion.
For create_cocktail, add a prerequisite hint: 'Use search_ingredients() to find ingredient IDs, then create_ingredient() for any missing ones. The ingredients array must include only IDs that exist in the database.'
Return user-friendly field names in responses (name instead of ingredient_name; id not uuid). Document that all dates return ISO 8601 format (e.g., '2024-12-15T14:30:00Z') not timestamps.