DocsReference
Order tools
The three caller tools behind every phone order, and the rules that keep the ticket honest.
By the Callaroo team. Updated November 2026
The assistant saves a draft with items from your menu, applies changes when needed, then confirms it. Nothing reaches the kitchen as a confirmed order until the caller has heard the order read back and agreed to it.
The three tools
- create_order
- Write: save a draft and return a read back
- update_order
- Write: change the draft and clear the old read back
- confirm_order
- Write: confirm at the read-back version after agreement
What each tool returns
The model receives structured fields, not a paragraph it has to interpret. Those fields are what make the read back and the version check reliable. The caller hears the meaning, not the raw object.
| Tool | Result on success | What the caller hears |
|---|---|---|
| search_menu | Up to eight available items, each with its stored price and modifiers. | The matching item names and prices. If nothing matches, a request to rephrase rather than a guess. |
| create_order | A draft order ID, its version, the priced lines, the total and a read-back sentence. | The full draft, including quantities, modifiers, pickup time and total. |
| update_order | A new version and a cleared read back, so the old agreement no longer applies. | Only the change, followed by a fresh read back of the current draft. |
| confirm_order | A confirmed order, or needs_review with a reason, plus the active short code. | Confirmation, the short code and what happens next. A review order is described as waiting for staff. |
The result fields are for the assistant and the stored order. They are not a public link and they are not sent to the caller as a message. A confirmation text is a separate action with its own opt-out rules.
1. Search the menu
create_order looks up each named item and size in your saved menu before saving the draft. If it needs a more specific item, the assistant asks the caller before trying again. The draft stores a snapshot of the menu, so changing a price tomorrow does not change what was agreed today.
- Order lines
- 1 to 30 lines
- Quantity per line
- 1 to 50
- Customer name
- 1 to 60 characters
- Pickup time
- “asap” or a full date-time
- Callback number
- Optional, in international format such as +12125551234
- Line note
- Up to 200 characters
The result includes the order ID, its version, the priced lines, the total and a sentence to read back. The assistant is expected to read that sentence to the caller rather than paraphrase the total from memory.
A draft is not a confirmed order. It is not sent to the kitchen and it does not receive an active short code until it is confirmed.
2. Update a draft
update_order changes an existing draft. It supports five operations, and every successful update creates a new version.
- add. Add a menu item with a quantity, optional modifiers and an optional note.
- remove. Remove a line by its position in the draft.
- set_quantity. Change one line to a quantity between 1 and 50.
- set_note. Replace the note on one line, up to 200 characters.
- set_pickup. Set the pickup time to “asap” or a full date and time.
The call must send the version it last saw. If the draft has moved on, the update fails with a version conflict instead of overwriting a newer order. A successful update also clears the previous read back, so the caller has to hear the changed order before it can be confirmed.
3. Confirm the order
confirm_order is deliberately strict. It requires the order ID, the same version that was read back, and an explicit caller confirmation. The call records that the read back happened at that version. A simple true from the assistant is not enough.
The assistant reads the current draft back, including quantities, modifiers and the total.
The caller agrees out loud.
confirm_order is called with the read-back version.
The order becomes confirmed, or needs_review if a review rule applies.
A four-digit short code is assigned to an active order so staff and caller can refer to the same ticket.
If confirmation arrives at the wrong version, the tool returns a read back requirement. The assistant reads the current order again rather than insisting that the caller already agreed.
When an order goes to review
Confirmation can produce needs_review instead of confirmed. That is not a failed order: it is the assistant saying a person should look before the kitchen starts.
- Large quantity
- A line above the per-item limit, 20 by default
- High total
- A total above the optional review threshold, when one is set
- Flag shown
- large_quantity or high_total on the order
- What to do
- Check the order in Orders, then approve or cancel it
A review order still holds its short code while it is active. Approving it moves it to confirmed; cancelling it releases the code from the active set.
Limits the tools enforce
- Menu search
- 80-character query, 8 results at most
- Draft size
- 30 lines at most
- Line quantity
- 1 to 50 per line
- Names and notes
- 60-character name, 200-character note
- Short code
- Four digits, unique among active orders
- Review threshold
- Item quantity 20 by default; total threshold optional
What the caller hears
- Items and quantities in the order they were added.
- Modifiers with the item they belong to, not as a separate list.
- The total from the stored prices, not a number recalculated aloud.
- The pickup time the caller chose.
- A clear request to confirm before anything is saved as confirmed.
When a tool returns an error
- invalid_args
- The request was malformed; the assistant asks again or corrects it
- item_unavailable
- The item was taken off the menu; it must not be sold
- item_not_found
- The menu has no match; the assistant asks the caller to rephrase
- version_conflict
- The draft changed; the assistant re-reads before trying again
- readback_required
- The order was not read back at this version
- caller_confirmation_required
- The caller has not explicitly agreed
- not_draft
- The order is already confirmed or closed
- tool_execution_failed
- A safe failure; the assistant should not claim success
What the order tools do not do
- Take a payment or process card details.
- Calculate kitchen capacity or invent a pickup time you did not offer.
- Edit a confirmed order silently. Staff handle changes in Orders and keep the note with the ticket.
- Delete an order or erase its history.
- Call the customer back. That is a separate callback request for staff.
- Let a second workspace read or change the order.
Make the menu work for these tools
- Use the prices you actually charge, including tax treatment, so the read-back total is the total you expect.
- Add caller-friendly aliases only if your menu data supports them. The current Menu page does not edit aliases.
- Use a line note for a kitchen instruction. A priced extra must exist in the stored menu data; the current Menu page does not add modifiers.
- Mark items unavailable when you run out instead of deleting them; old orders keep their snapshot.
- Keep names short enough to say and hear clearly.
- Set a review threshold if a large total should always reach a person before the kitchen starts.
If a caller changes their mind after confirmation, treat it as a staff change, not a new conversation. Add a note so the ticket, the transcript and the kitchen all tell the same story.