Agent tools
The full toolset the shopping agent uses — and the auth check on each one.
The shopping agent works through a small, explicit set of tools. Every
tool receives the verified Principal (the JWT payload) and runs its
own authorization check before doing anything.
Catalog tools (public)
These accept anonymous shoppers — anyone browsing the store can use them.
search_products
Returns a list of product summaries (id, title, image, price, stock) matching a free-text query. Backed by Firestore prefix scan + (when configured) vector similarity on product embeddings. Scoped to the caller's tenant.
get_product
Full detail for one product: description, all images, variants, average rating, and recent reviews. Useful when the shopper asks "tell me more about this".
Cart tool (authenticated)
add_to_cart
Appends { productId, variantId?, quantity } to the shopper's
persistent cart. Rejected for anonymous principals. The tool does the
same stock and variant validation as the API endpoint.
Order tools (authenticated)
get_orders
Lists the current customer's orders at this tenant's store. Returns
status, total, line items, and tracking links. Rejected for anonymous
principals; rejected for principals whose uid doesn't match the order
owner.
get_order_detail
Full breakdown of one order — every line item, addresses, fulfillment, refund history, invoice URL. Same auth check as above plus an ownership check on the specific order.
Preference tools (authenticated)
read_preferences
Returns the shopper's saved preferences (size, color, dietary, whatever). The agent uses these to filter recommendations without asking every time.
remember_preference
Saves a new preference. The agent uses this when the shopper says "I usually buy Medium", "I'm allergic to nuts", "I prefer organic cotton".
Thread management (mixed)
create_thread, list_threads
For logged-in shoppers, listed and created in Firestore. For anonymous, the agent works against in-browser state with the HMAC-signed key.
adopt_anonymous_messages
When an anonymous shopper signs in, this tool can migrate their browser history into their Firestore thread — but only with explicit consent.
Why per-tool checks?
A single "is admin?" check at the door wouldn't work, because the same agent serves anonymous browsers, logged-in shoppers, and (in the future) admins. Per-tool auth lets the model attempt anything it wants — the tool either runs or returns a structured "not authorized" result. The agent loop sees that, apologizes, and picks a different path.