Tool Execution Flow
This page describes the complete lifecycle of a user message, from input to final response.
Sequence
Customer App (Chat UI) LLM Proxy LLM Provider
│ │ │ │
│ "Add milk to │ │ │
│ my cart" │ │ │
│──────────────────▶│ │ │
│ │ │ │
│ │ POST /chat/v1/ │ │
│ │ conversation │ │
│ │ {messages, tools, │ │
│ │ systemPrompt, │ │
│ │ context} │ │
│ │───────────────────▶│ │
│ │ │ │
│ │ │ Send to LLM with │
│ │ │ base prompt + │
│ │ │ extension + tools │
│ │ │───────────────────▶│
│ │ │ │
│ │ │ Response: │
│ │ │ tool_call: │
│ │ │ search_products │
│ │ │ {query: "milk"} │
│ │ │◀───────────────────│
│ │ │ │
│ │ tool_call: │ │
│ │ search_products │ │
│ │ {query: "milk"} │ │
│ │◀──────────────────│ │
│ │ │ │
│ │ Execute locally │ │
│ │ via MCP Server │ │
│ │ (Hybris search) │ │
│ │ │ │
│ │ tool_result: │ │
│ │ {products: [...]} │ │
│ │───────────────────▶│ │
│ │ │ │
│ │ │ tool_result + │
│ │ │ continue │
│ │ │───────────────────▶│
│ │ │ │
│ │ │ Response: │
│ │ │ tool_call: │
│ │ │ add_to_cart │
│ │ │ {code: "...", │
│ │ │ qty: 1} │
│ │ │◀───────────────────│
│ │ │ │
│ │ (execute locally) │ │
│ │ ... │ │
│ │ tool_result │ │
│ │───────────────────▶│───────────────────▶│
│ │ │ │
│ │ │ "I've added │
│ │ │ Full Cream Milk │
│ │ │ to your cart!" │
│ │ │◀───────────────────│
│ │ │ │
│ │ Final response │ │
│ │◀──────────────────│ │
│ │ │ │
│ "I've added │ │ │
│ Full Cream Milk │ │ │
│ to your cart!" │ │ │
│◀─────────────────│ │ │
Key Points
Tool call loop
The LLM can make multiple tool calls in sequence. For example, "add milk and bread" might result in:
search_products("milk")→ resultsadd_to_cart(milk_code)→ successsearch_products("bread")→ resultsadd_to_cart(bread_code)→ success- Final text response
The loop continues until the LLM returns a text response with no tool calls, or a safety limit is hit.
Safety limits
| Limit | Value | Purpose |
|---|---|---|
| Max tool turns per request | 50 | Prevents infinite tool call loops |
| Max tool turns per session | 200 | Prevents runaway sessions (Android) |
| Rate limit | 30 req/min | Prevents abuse |
Local execution
Tools execute inside the app using existing services:
search_products→ Hybris product search APIadd_to_cart→ Cart manager (Hybris cart API)get_cart→ Local cart state + Hybris refresh- Navigation tools → App coordinator / navigation controller
This means tool execution has zero additional network latency beyond what the app's existing services require.
iOS vs Android execution differences
| Aspect | iOS | Android |
|---|---|---|
| MCP Server | EcommerceMCPServer (single server) | EcommerceMCPServerImpl + AppMCPServerImpl (two servers via router) |
| Tool routing | Switch statement in single server | MCPToolRouter aggregates multiple servers |
| Navigation | Not exposed as tools (coordinator pattern) | Exposed as 8 navigation MCP tools |
| UI display | show_cart / show_products tools | Not yet implemented — text responses only |
| Division scoping | Via DivisionalContainer | Via @DivisionScope Dagger scoping |