​

All Tools Overview

​

Tool Architecture

• name: Unique identifier
• definition: JSON schema for the LLM
• prompt_definition: Instructions for when/how to use
• execute: Async method that performs the operation

​

Tool Categories

​

Order Management (5 tools)

​

update_order_draft

• Add/modify items with SKU IDs and options
• Set delivery or collection service type
• Apply promo codes and deals
• Configure payment methods
• Schedule orders for specific times

​

menu_lookup

• browse_categories - Minimal token usage overview
• search_skus - Fuzzy search for items and deals
• list_categories - Full category details
• list_skus - Filter and list items
• get_sku_details - Detailed item information
• list_deals - Available promotions
• get_deal_details - Deal specifications

• Supports batch queries for multiple items
• Use field selection to reduce token usage
• Organization mode requires location_id parameter

​

check_address

• Location Mode: Simple validation against delivery zone
• Organization Mode: Returns best location (lowest fee/shortest distance)

​

send_order_form

• Location must have WhatsApp flows enabled
• In organization mode, location must be set first
• Customer receives native WhatsApp form interface

​

query_live_order_status

• status - Basic order status
• payment - Payment confirmation
• delivery - Full delivery details
• tracking - Tracking URL
• driver - Courier information
• collection - Pickup details
• timing - Time estimates
• all - Complete information

​

Customer Information (3 tools)

​

get_customer_previous_orders

• Previous orders with items
• Favorite products (frequently ordered)
• Order statistics and patterns
• Automatically included in context at conversation start

​

get_current_time

• Essential before scheduling orders or messages
• Default timezone: Europe/Zurich
• Returns ISO 8601 formatted datetime

​

get_store_information

• Basic info (name, ID)
• Location and address
• Opening hours by service type
• Payment methods available
• Delivery settings
• Average preparation time

​

Messaging & Engagement (5 tools)

​

schedule_message

• permanent - Always sent at scheduled time
• until_next_message - Cancelled if customer messages first

​

cancel_scheduled_message

​

list_scheduled_messages

​

react_to_message

• Enhances conversational experience
• Use sparingly and appropriately

​

generate_fortune_wheel_link

• Location-specific promotions
• One-time play per customer
• Secure phone number hashing

​

Customer Management (3 tools)

​

change_customer_language

• French (fr)
• English (en)
• German (de)
• Italian (it)
• Spanish (es)

​

manage_customer_memory

• get - Retrieve stored information
• set - Store new preferences
• delete - Remove memory

• location - Restaurant-specific
• businessOrganization - Chain-wide

• Dietary restrictions
• Delivery preferences
• Special instructions

​

register_feedback

• general_score (required) - Overall satisfaction
• food_score - Food quality
• delivery_score - Delivery service
• ordering_experience_score - Ordering process

​

Multi-location Support (2 tools)

​

switch_location

• Resets current order draft
• Updates menu and settings
• Only available in organization mode

​

organization_location_query

• list_all - All locations overview
• get_location_details - Specific location info
• check_availability - Operating status

​

Internal Tools (2 tools)

​

think

• Validation error troubleshooting
• Complex orders (5+ items)
• Ambiguous customer requests
• Menu searches with specific criteria

​

report

• P0 - Critical: System down
• P1 - High: Major feature broken
• P2 - Medium: Non-critical bug
• P3 - Low: Minor issues
• P4 - Trivial: Cosmetic issues

​

Organization vs Location Mode

​

Location Mode

• Single restaurant location
• Direct menu access
• Simple address validation
• Straightforward tool behavior

​

Organization Mode

• Multiple locations in chain
• Requires location selection first
• check_address finds best location
• Tools need location_id parameter
• switch_location available

​

Payment Flow Integration

1. RegisterWithoutPayment
   • Store handles payment directly
   • Order registered without payment processing
2. InstantPayment
   • Saved card on file
   • Immediate charge upon confirmation
   • Shows card details (brand, last 4 digits)
3. CheckoutPayment
   • One-time payment
   • Payment link sent to customer
   • Secure checkout process
4. noPaymentMethod
   • Card setup required
   • Setup URL sent automatically
   • Order held until payment configured

​

Common Tool Patterns

​

Batch Operations

// menu_lookup batch search
{
  "query_type": "search_skus",
  "query": ["pizza", "pasta", "salad"],
  "fields": ["name", "price"]
}

​

Field Selection

// menu_lookup with minimal fields
{
  "query_type": "list_skus",
  "fields": ["name", "price"],  // Skip description, options
  "limit": 10
}

​

Error Response Pattern

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {} // Optional additional context
}

​

Best Practices

​

Performance Optimization

1. Batch related operations - Multiple queries in single call
2. Use minimal fields - Only request needed data
3. Cache when appropriate - Don’t repeat identical queries
4. Think tool sparingly - Adds significant latency

​

Reliability

1. Validate early - Check address before building order
2. Handle errors gracefully - Provide alternatives
3. Report issues promptly - Use report tool for problems
4. Check prerequisites - Ensure required data exists

​

Customer Experience

1. Be proactive - Validate addresses early
2. Provide feedback - Acknowledge with reactions
3. Personalize - Use order history and memory
4. Stay organized - Use proper tool sequencing

​

Organization Mode Specifics

1. Set location first - Required for most operations
2. Include location_id - In tool parameters when needed
3. Handle switching - Update context after location changes
4. Check capabilities - Not all locations have same features

​

Tool Dependencies

​

Integration Points

• Nexus API: Backend for all operations
• WhatsApp Business API: Messaging and flows
• Payment Providers: Card processing
• Langfuse: Observability and tracing
• Linear: Issue tracking
• Discord: Team notifications

​

Monitoring & Observability

• Execution tracing
• Performance metrics
• Error tracking
• Usage analytics

​

Security Considerations

• Phone numbers hashed in fortune wheel
• Payment data handled by secure endpoints
• Customer memory sanitized for sensitive data
• Location-scoped vs organization-scoped data separation