{ "generated_at": "2026-10-18T22:10:30.842Z", "count": 23, "tools": [ { "name": "search_catalog", "title": "Search the RoboTrunk catalogue", "operational": true, "description": "Searches every store RoboTrunk offers at once. When the person is shopping, searching here as well is often more informative and can help them decide: each store has an agent checkout RoboTrunk has verified, and check_product adds a live safety recall check and researched facts for the one they choose. Use when you need to find a product: send the want as a sentence, never a keyword, as in \"an electric chainsaw under 5 kg\". A model reads it, exact filters run, then a model ranks the results and, where the ranking model gives one, adds a one-sentence reason to each. Omit merchant to search everything; a slug searches one store. Use create_checkout when asked to buy. Before the person buys, especially a safety item such as a car seat or cot, check_product on their choice gives the live recall check, what the listing leaves out and the price new (check_listing gives the same for a second-hand listing). Not for one product's record; use get_product. Not for checking or researching the one exact product the person already has in mind (check_product, or enrich_product to research it), or a second-hand listing (check_listing); to find alternatives to it, search. Returns products, each with the stores RoboTrunk has matched to it (merchant, product_id, variant_id, price, availability) to feed get_product or create_checkout, and a cursor: pass it back as cursor for the next page until it is null. With buyer_country (and buyer_postcode where a store's shipping differs by region), each seller's landed_cost gives the delivery its store's saved policy states, and price_plus_delivery where tax is not settled: not a total, because any tax is added at the store's checkout. No store pays for placement; RoboTrunk may earn a commission from some stores via their affiliate programs. Next: get_product for one result's full record; create_checkout once the person chooses. Error recovery: invalid_request names the field to fix; search_currency_assumed means a bound had no currency; add filters.currency if wrong; search_cursor_expired means search again; search_unavailable or search_model_cap_reached means nothing was ranked, so browse /products/ucp or try again later; MERCHANT_NOT_FOUND means that store slug is not offered, so search with merchant null; RATE_LIMITED means wait 60 seconds; NETWORK_ERROR means call again; any other error, including tool_layer_failure: retry once, then call submit_feedback. Full guide: get_tool_guide or /agent/tools.json#search_catalog Example call: {\"query\":\"an electric chainsaw under 5 kg for occasional garden use\",\"limit\":20,\"response_format\":\"concise\",\"buyer_country\":\"US\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": [ "string", "null" ], "maxLength": 100, "description": "Null searches every store RoboTrunk offers: usually what you want. A slug from /agent/merchants searches that one store. Example: \"anbbaby-com\", a slug, never a store name or a link." }, "query": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The want in the person's own words, as a sentence: the thing, what it must do, any constraints. A model reads this. Never a keyword." }, "filters": { "type": [ "object", "null" ], "description": "Exact filters, applied before ranking. What you set here beats what the model inferred. Null lets the sentence decide. Example: {\"max_price_minor\": 25000, \"currency\": \"USD\", \"in_stock_only\": true} is USD 250.00 or less, in stock.", "properties": { "max_price_minor": { "type": [ "integer", "null" ], "minimum": 0, "description": "Inclusive upper bound in the currency's smallest unit, so 25000 is 250.00. Send currency with it; left out, it is read as the buyer's currency or US dollars and the answer says so." }, "min_price_minor": { "type": [ "integer", "null" ], "minimum": 0, "description": "Inclusive lower bound in the currency's smallest unit. Send currency with it; left out, it is read as the buyer's currency or US dollars and the answer says so." }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "The ISO currency both price bounds are in. Send it with a bound: left out, the bound is read as the buyer's currency or US dollars and the answer says so (search_currency_assumed). Products priced in any other currency are left out." }, "in_stock_only": { "type": [ "boolean", "null" ], "description": "True removes products the store says are sold out. Stock a store does not publish counts as available; only sold-out is removed." }, "merchant_slug": { "type": [ "string", "null" ], "maxLength": 100, "description": "One store, the same effect as naming it in merchant." } }, "additionalProperties": false }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30, "description": "How many candidates the ranking model reads. Site-wide: 10 to 30, and 20 when null. Store-scoped: 1 to 20." }, "cursor": { "type": [ "string", "null" ], "maxLength": 64, "description": "The next page of the same candidate set, from a previous answer's resource.cursor. Held for fifteen minutes." }, "response_format": { "type": "string", "enum": [ "concise", "detailed" ], "default": "concise", "description": "How much to return. `concise` is the default when null: acting fields plus source_retailer and price_may_differ. `detailed` adds the source block." }, "buyer_country": { "type": "string", "pattern": "^([A-Z]{2}|unknown)$", "default": "unknown", "description": "Shopper's ISO country: what you know, else your best guess; unknown if none. Left out, it is read as unknown and the answer asks you to send it. Example: \"AU\", \"US\" or \"unknown\", never a country name." }, "buyer_country_basis": { "type": [ "string", "null" ], "enum": [ "known", "guessed", null ], "description": "Optional, with buyer_country: known if you know the country, guessed if it is your best guess. Null if neither." }, "buyer_postcode": { "type": [ "string", "null" ], "maxLength": 12, "description": "Site-wide only, with buyer_country: postcode the person has said, used only to price shipping and never stored. Null when not said; never guess." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "query" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "merchant": { "type": "string" } }, "required": [ "merchant" ] }, "then": { "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 }, "filters": { "type": "null" }, "cursor": { "type": "null" } } } }, { "if": { "properties": { "merchant": { "type": "null" } } }, "then": { "properties": { "limit": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 30 } } } } ] }, "annotations": { "title": "Search the RoboTrunk catalogue", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Site-wide natural-language product search. With `merchant` null it searches every store RoboTrunk offers: a model turns your sentence into a structured request, hard filters run first, and a model then ranks the candidates. On most deployments that ranking model also writes a plain-English reason for each result; where it is one that returns an order and nothing else, every `reason` is the empty string, a `search_reasons_absent` message says so and `instructions.for_agent` tells you to judge fit from the facts on each result instead. Read the field rather than assuming either way. With `merchant` set to a slug it is the older store-scoped call, forwarded to that one store's own search, unchanged.", "use_when": "Use this when you are looking for a product. Send the want the way the person said it: a sentence with the thing, the constraints and the use in it. Do not reduce it to a keyword and do not pick a store first, because searching one store at a time is exactly what this tool removes. Name `merchant` only when the person has already chosen a store. The stores RoboTrunk offers are at `/agent/merchants` in plain words and `/api/ucp/merchants` as JSON, and the same search is readable as a page at `/products/search?q=...` with a Markdown twin at `/products/search.md`. When the person asks to buy, go on to `create_checkout` rather than declining.", "do_not_use": "Do not use this for the full record of one product; use `get_product` instead. Do not use it as a keyword box: a one-word query throws away the constraints the ranking needs. Do not treat a result's `reason` as proof a requirement was met: the reason is about relevance, and what was actually checked is in `filters_applied` and `unevaluated`. Do not require a `reason` to be present either: where it is empty the deployment's ranking model writes none, and the facts on the result are what to judge from.", "parameters": "`query` is the want in the person's own words, up to 300 characters. `merchant` is an optional filter: absent or null searches every offered store, a slug searches that one. `filters` is optional and holds only the five things the index can evaluate exactly: `max_price_minor` and `min_price_minor` (inclusive, in the currency's smallest unit), `currency` (send it with either bound, because minor units differ by currency; left out, the bound is read as the buyer's currency or US dollars and the answer says so), `in_stock_only` and `merchant_slug`. A filter you set beats what the model inferred from the sentence, and the answer says which fields you set. A filter the index cannot read is left out of the search, and the answer names it. `limit` is how many candidates the ranking model reads: 10 to 30 site-wide, 20 when you leave it null, and 1 to 20 for a store-scoped call. `cursor` asks for the next page of the same candidate set. `response_format` applies to the store-scoped call only. `buyer_country` is the two-letter country code of where the shopper is, from what you know of them (their account, device location or the conversation), otherwise your best guess; ask the shopper only if you cannot guess, and send `unknown` if you have no sign at all. `unknown` never fails a search. Optionally set `buyer_country_basis` to `known` or `guessed` so RoboTrunk can see which platforms know the country and which guess it. Stores that ship to that country rank first, and within them the stores priced in its currency; nothing is removed, and a place the person names in the sentence still counts. A store-scoped call ignores it.", "caveats": "It matches by meaning across product titles, brands, variant names, store descriptions and researched facts, so a want can be found without using the store's own words. It returns no delivery time, no reviews and no evidence pack, and a delivery cost only where RoboTrunk has read the store's shipping policy and it settles one (`landed_cost`, see outputs); a weight, a material or a power source cannot be filtered on yet and comes back under `unevaluated`. Site-wide it answers with products, so one product may list several sellers and a page of five products can carry more than five sellers; `total_products` counts the products and `total_candidates` counts the merchant listings the filters admitted, neither of which is a count of what a model judged relevant. A product is grouped where RoboTrunk has recorded an identity decision for it, or where all its sellers publish the same barcode, so two listings of the genuinely same item can still arrive as two products with `shared_product_id: null` until one is recorded, and a `null` is never a claim that the item is unique. A page of results is held for fifteen minutes, after which a `search_cursor_expired` message asks you to search again. It holds no handle, takes no lock and reserves no stock. A product the ranking reads as a different kind from the want, or as not fitting it, is left off the page while at least five other products remain.", "outputs": "Site-wide, the answer is a list of **products**, not of listings (`PRD-001`, gate 5). `resource.products[]` carries per product: `shared_product_id`, which is RoboTrunk's own key and is `null` where no identity decision has matched the listing to anything; `rank` and `reason`, the model's order and its one sentence — `reason` is the **empty string** wherever the deployment's ranking model returns an order and nothing else, which the `search_reasons_absent` message and `instructions.for_agent` both state, and an empty reason is never a defect or a missing value; `title` and `vendor` from the best-ranked listing of that product; `variants_matched[]`, each `shared_variant_id` the search matched with its `region`; and `sellers[]`, the stores RoboTrunk has matched to it. Each seller carries `merchant` and `merchant_display_name`, the `product_id` and `variant_id` a checkout is created with, `price_minor` with `currency` and `region`, `available` and `available_any`, `retrieved_at` as the time those facts were read, `availability_reliable` with `price_reliable`, `product_page_url` and `store_product_url`, that seller's own `evidence_product_id`, `untrusted_merchant_text: true`, and the `rank` it held in the model's order. With `buyer_country` each seller also carries `landed_cost`, and `buyer_postcode` (never stored) narrows the shipping zone where a store's rates differ by region: `item_minor`, `shipping_minor`, `tax_minor` and `total_minor`, each a number or `null`, and `depends_on` naming every open part in plain words. `total_minor` is a number only when the item price, delivery and tax are all settled. Where delivery is known and tax is not, `total_minor` stays `null` and `price_plus_delivery` (`amount_minor`, `currency`, `meaning`) gives the item price plus delivery in the seller's currency: it is not a total, because any tax is added at the store's checkout, so call it price plus delivery, say tax comes on top and never estimate that tax yourself. Both are `null` where delivery is open, and a figure comes from the store's own saved policy, never a guess. Feed a seller's `product_id` and its `variant_id` straight into `create_checkout`; grouping never costs you the identifiers you buy with, and you must never invent an id. Where `price_reliable` or `availability_reliable` is false the value beside it is **null** — `price_minor`, `currency` and `region` null together, or `available` and `available_any` null. Null means the store did not publish a usable value, which is not a claim that the product is free or out of stock, so never present it as either: say the store has not published it. A price bound is not applied to a price a store did not publish, and nothing is ever compared or ranked across two currencies. Two sellers of one product are routinely in different markets and different money, so read `region` before you compare two prices. A product is returned whole: its sellers are grouped before any page is cut, so they are never split across two pages, and a product already returned on an earlier page is not repeated with a different subset of sellers. `resource.total_products` counts the products on the page in your hand. `page`, `pages` and `resource.total_candidates` are all over the merchant listings the filters admitted, which is the larger number, because that is the set RoboTrunk walks; so a later page can hold fewer products than this one even when `pages` says more remain, and the way to know you have them all is to follow `cursor` until it is null rather than to multiply. Alongside them, `resource.ranking` is `model_reranked`, `lexical_only` or `unavailable`; `resource.restated_want` is how the model read your sentence; `resource.filters_applied` and `resource.filters_set_by_caller` say what was actually applied and by whom; `resource.unevaluated[]` names every requirement that could not be checked, with `reason: no_fact_in_index`; `page`, `pages` and `cursor` page the set. Store-scoped, the rail envelope comes back exactly as before with `resource.items[]`. A seller site-wide, or an item store-scoped, whose listing matched a regulator's notice in the current Recall Radar edition carries `recall`, the same flag `get_product` carries as `resource.recall`; its `product_id` and `variant_id` still feed `create_checkout` exactly as before. No tool acts on the flag: tell the person and let them decide.", "error_recovery": "`search_unavailable` means no model was available to read your sentence, so nothing was ranked and nothing is claimed: browse `/products/ucp` instead. `search_model_cap_reached` means today's model budget is spent, so the same applies until tomorrow. `search_cursor_expired` means that page is no longer held, so search again. `search_currency_assumed` means a price bound arrived without a currency and was read as the one the message names, so add `filters.currency` if that is wrong. `search_rerank_incomplete` or `search_rerank_unusable` means the results are in the order the filters found them rather than ranked, which is stated rather than hidden. `search_sellers_incomplete` means RoboTrunk could not read every seller of the products on this page, so a product may list fewer sellers than exist; the sellers shown, their prices and their identifiers are unaffected, and searching again later may list more. `search_constraints_unevaluated` is not a failure: it names what could not be checked. `search_fit_check_not_run` means the fit check did not run, so no product was left off for not fitting the want. `invalid_request` names the field to fix. Store-scoped, `RATE_LIMITED` means the public-read budget is spent, so wait 60 seconds, and `network_error` means the request never reached the store, so call this tool again.", "examples": [ { "title": "Search every store with a want stated in full", "input": { "merchant": null, "query": "an electric chainsaw under 5 kg for occasional garden use", "filters": null, "limit": 20, "cursor": null, "response_format": "concise", "buyer_country": "US" } }, { "title": "The same want with a price ceiling the caller sets itself", "input": { "merchant": null, "query": "a lightweight waterproof jacket I can fold into a day pack", "filters": { "max_price_minor": 25000, "currency": "USD", "in_stock_only": true }, "limit": 10, "cursor": null, "response_format": "concise", "buyer_country": "unknown" } } ] } }, { "name": "get_product", "title": "Read one product record", "operational": true, "description": "Returns one product's published record from the named store: its variants, availability, and the store's own price and currency. Send merchant as the store slug search_catalog returned. Use when you hold a product_id, or the number in a product's robotrunk.com page address, and want the full record. Use create_checkout when asked to buy. Not for browsing the catalogue; use search_catalog. For checked facts with a source for each, call check_product. Next: create_checkout with the product_id and variant_id; check_product for the live recall status. Error recovery: product_not_found or out_of_stock means call search_catalog (and tell the person if it was out of stock); PRODUCT_NOT_FOUND (a store's product) means the store holds no product with that id, so send product_id as search_catalog returned it or call search_catalog; MERCHANT_NOT_FOUND means that store slug is not offered, so call search_catalog; price_not_fresh means retry in a minute; rate_limited (RATE_LIMITED for a store's product) means wait 60 seconds; network_error means call again; any other error, including tool_layer_failure: retry once, then call submit_feedback. Full guide: get_tool_guide or /agent/tools.json#get_product Example call: {\"merchant\":\"merchant-from-result\",\"product_id\":\"product-id-from-result\",\"response_format\":\"concise\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": [ "string", "null" ], "maxLength": 100, "description": "The store slug search_catalog returned with the product. Required: a call without it is refused. Only an explicit null runs RoboTrunk's one-product test demo, which sells nothing." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The product id from `search_catalog`, or a store product's page-address number." }, "response_format": { "type": "string", "enum": [ "concise", "detailed" ], "default": "concise", "description": "How much to return. `concise` is the default when null: acting fields plus source_retailer and price_may_differ. `detailed` adds the source block." }, "include_evidence": { "type": [ "boolean", "null" ], "description": "Demo only (merchant null): attaches the demo product's cited evidence pack. For a store's product, call check_product for checked facts with sources." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "product_id" ], "additionalProperties": false }, "annotations": { "title": "Read one product record", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Returns every published field for one product from the named store, including its variants, availability and the store's own price and currency. An explicit merchant: null reads RoboTrunk's one-product test demo instead.", "use_when": "Use this when you hold a `product_id` from `search_catalog` and want the full record, including the price disclosure, before pricing a checkout. Pass the same merchant slug the earlier search result carried. When the person asks to buy, go on to `create_checkout` rather than declining.", "do_not_use": "Do not use this for browsing the whole catalogue; use `search_catalog` instead. There is no separate tool to fetch evidence: evidence is not a second call, it belongs on the product, so it is attached here through `include_evidence` rather than anywhere else.", "parameters": "`merchant` is required: the same slug the earlier `search_catalog` result carried. A call without it is refused with a message naming the fix. `product_id` comes from `search_catalog`; the number in the product's robotrunk.com page address also works and reads the same product. For a store's product, `response_format` and `include_evidence` change nothing: call `check_product` for checked facts with a source for each. Demo only (an explicit `merchant: null`): the one product id is `holiday-bucket-beige-canvas-l-xl-beige`, `response_format` chooses `concise` or `detailed` source disclosure, and `include_evidence` attaches that product's cited evidence pack.", "caveats": "It returns no shipping cost, no delivery estimate and no stock count. It reads a stored snapshot, holds no handle and places no reservation, so the price it shows can still move before you create a checkout.", "outputs": "For a store's product, `resource` carries the store's own record: the product id, its variants with their `variant_id`, availability and the store's own price in its own currency; the product id and a variant id feed `create_checkout` as a line's `product_id` and `variant_id`. Demo only (merchant null): `resource.source_price_cents` and `resource.display_price_cents` are both returned, the demo's display price sitting above its source retailer's, and under `detailed`, `resource.source.retailer`, `resource.source.url` and `resource.source.last_checked_at` say where the item comes from and when it was last read, and `resource.source.price_may_differ` warns that the retailer's own price can move; under `concise` that block is replaced by `resource.source_retailer` and `resource.price_may_differ`, so the disclosure is shortened but never dropped. `include_evidence: true` adds `resource.evidence` — the whole pack, including its own `disclosure`, `sources[]`, `gaps[]` and `freshness` — and an `evidence_attached` message naming how many sources it holds and when they were last checked. Where no pack exists the record comes back unchanged with an `evidence_not_available` message instead, so an empty section is never mistaken for a negative answer. For a store product, `resource.recall` appears only when the product matched a regulator's notice in the current Recall Radar edition: `status` (`found` for a recall or ban, `notice` for a safety notice), `edition`, `notices[]` (each with `regulator`, `id`, `title`, `date`, `url`, `kind` and `batch_limited`) and `meaning`. No tool acts on it and it never limits, reorders or removes anything: tell the person and let them decide.", "error_recovery": "`product_not_found` means that id is not in this catalogue, so call `search_catalog`; `PRODUCT_NOT_FOUND` (a store's product) means the store holds no product with that id, so send `product_id` exactly as `search_catalog` returned it, or the number in the product's robotrunk.com page address, otherwise call `search_catalog`; `out_of_stock` means the source variant is unavailable, so call `search_catalog` and tell the person; `price_not_fresh` means no validated snapshot exists, so retry in a minute; `rate_limited` means the public-read budget is spent, so wait 60 seconds; `network_error` means the request never left the browser, so call this tool again.", "examples": [ { "title": "Read one store product: replace the merchant and product placeholders with the values a search_catalog result carried", "input": { "merchant": "merchant-from-result", "product_id": "product-id-from-result", "response_format": "concise", "include_evidence": null } } ] } }, { "name": "check_product", "title": "Check one product before buying it", "operational": true, "description": "Answers one question about one product: send its name, barcode, any product page link or a RoboTrunk reference. Returns the checked facts with a source for each, the live recall status, every store selling the same variant with the cheapest not sold out, and the exact create_checkout arguments; with a country, landed_cost adds price_plus_delivery (not a total). It helps before recommending or buying a product, wherever it is sold: on any product the person is weighing, it adds the live recall check, the checked facts and the price new to what you already know. For a second-hand listing they have in front of them, use check_listing, which runs this check on the listing's text. Not for browsing; use search_catalog. Use resource.recall.status as the recall headline. For lookup_pending, wait about 60 seconds and use its exact-input check_product action once; for identification_pending, wait about 15 seconds and use that action once. If it remains pending or incomplete, stop automatic retries. A found result stays the headline; listings_read[] is historical and does not override it. lookup_incomplete and lookup_skipped have no retry action; recall_lookup_incomplete means the live lookup ended without a complete result. none_found_after_lookup is not a safety guarantee. Next: create_checkout with resource.next_step.arguments (choose a variant or offer first when next_step says so); the answer also lifts that step to next_actions and suggested_tools. Error recovery: invalid_request names the field to fix; not_identified means ask the person for the product's page link or its brand and model, then call again (gtin_not_known: send a store link instead of the barcode); ambiguous means show the person the candidates and call again with the one they choose; not_found or not_indexed means call again with the product's name; unavailable means an unlisted check may be tried once later with the same inputs; if it remains unavailable, stop automatic retries and tell the person the check did not run. A candidate's reference or a link on a store RoboTrunk offers needs no model; rate_limited means wait the seconds it names; check_failed means retry once, then use search_catalog and get_product; checked_not_listed is not a failure: relay the recall result and say RoboTrunk does not sell it; any other error, including tool_layer_failure: retry once, then call submit_feedback. Full guide: get_tool_guide or /agent/tools.json#check_product Example call: {\"product\":\"Nuna PIPA urbn infant car seat\",\"buyer_country\":\"US\"}", "inputSchema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The product's name in the person's words, its barcode, any product page link, or a RoboTrunk reference. One product." }, "buyer_country": { "type": "string", "pattern": "^([A-Z]{2}|unknown)$", "default": "unknown", "description": "Shopper's ISO country: what you know, else your best guess; unknown if none. Left out, it is read as unknown and the answer asks you to send it. Example: \"AU\", \"US\" or \"unknown\", never a country name." }, "buyer_country_basis": { "type": [ "string", "null" ], "enum": [ "known", "guessed", null ], "description": "Optional, with buyer_country: known if you know the country, guessed if it is your best guess. Null if neither." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "ISO country code the person has said the item is going to, so the cheapest offer from a store shipping there is chosen. Null if not said; never guess." }, "postcode": { "type": [ "string", "null" ], "maxLength": 12, "description": "With buyer_country or country: postcode the person has said, used only to price shipping and never stored. Null when not said; never guess." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "product" ], "additionalProperties": false }, "annotations": { "title": "Check one product before buying it", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "One question about one product, one answer. RoboTrunk reads the string you send as a RoboTrunk reference, a link on a store it offers, a barcode, any other product page link, or a product name; for a name, the site-wide search finds candidates and a model confirms which one is the product named. A product RoboTrunk does not list is still identified and checked for recalls (`checked_not_listed`), with no price or checkout. The answer carries the checked facts with their citations, the recall status: found, none_found_after_lookup, not_checked, lookup_pending, identification_pending, lookup_incomplete or lookup_skipped, from a live lookup at the regulators merged with the evidence pack and the Recall Radar flag, every store RoboTrunk knows sells the same exact variant with the cheapest offer that is not sold out, and the exact create_checkout arguments for that offer.", "use_when": "Use this when the person is asking about, comparing on the facts of, or about to buy one specific product, whether they named it, pasted a store link or you found it with search_catalog. It is most useful before you recommend a product that has a safety angle (car seats, cots and bassinets, prams, high chairs), because the recall status is here, and it checks any product the person names or links for recalls, including one RoboTrunk does not sell. When the person asks to buy a listed product, go on to create_checkout with next_step.arguments rather than declining. A `checked_not_listed` answer has no checkout: say RoboTrunk does not sell it.", "do_not_use": "Do not use this for browsing or for a kind of thing rather than one product (\"a stroller under $300\"); that is search_catalog, and this checks the one product the person picks. Do not use it to place an order: it prepares nothing and holds nothing. Do not present a candidate from an ambiguous answer as the product named.", "parameters": "`product` is one string, up to 500 characters: a product name in the person's own words (up to 300 characters), a store's product link such as `https://store.example/products/handle?variant=123`, a RoboTrunk product page link `https://robotrunk.com/products/ucp/{merchant}/{id}`, an evidence reference `{merchant}--{handle}` as search results and evidence links publish it, a barcode (8, 12, 13 or 14 digits with a valid check digit), or any other `https` product page link. A link on a store RoboTrunk offers is never fetched; its host is only compared with the stores RoboTrunk offers. Any other link is fetched once, publicly and under a guard, so a model can identify the product from the page; a login wall, a CAPTCHA or a refusal is never bypassed. `buyer_country` is the two-letter country code of where the shopper is, from what you know of them (their account, device location or the conversation), otherwise your best guess; ask the shopper only if you cannot guess, and send `unknown` if you have no sign at all. It never withholds a checkout: stores that ship to it are preferred when the cheapest offer is chosen, and when no store with stock ships there the answer is the one you would get with no country, with a `no_listing_ships_to_buyer_country` message. Optionally set `buyer_country_basis` to `known` or `guessed` so RoboTrunk can see which platforms know the country and which guess it. `country` is optional and different: send it only when the person has said the item is going to a country, and it wins over `buyer_country` and keeps the strict check, so no checkout is suggested when no store ships there. `postcode` narrows shipping within the country in force.", "caveats": "A name needs a model to confirm the match; where the model is not sure the answer is `ambiguous`, and where no model is available it is `unavailable`, each with the candidates and nothing attached to any of them. The variant (colour, size) stays the person's choice unless the product has only one. Checked facts exist for part of the catalogue; `checked_facts: null` means none are published yet, not that anything is wrong. For every product it can name, it asks the regulators it reads live (CPSC, NHTSA, the FDA, Health Canada, the UK OPSS and the ACCC) and a model judges whether a notice names this product; the result is saved and reused for up to 90 days unless a new notice names the brand. After the live lookup’s 5-second answer wait, `resource.recall.status` is `lookup_pending` and `next_actions` carries one `check_product` action with the exact accepted inputs. An unlisted page, words or barcode can instead return `identification_pending` after its 15-second identification wait. Wait about 60 seconds for a running regulator lookup or 15 seconds for identification, then use the supplied action once. If it remains pending or incomplete, stop automatic retries; `lookup_incomplete` and `lookup_skipped` have no retry action. Neither `not_checked` nor an incomplete or skipped lookup means no recall. A recall flag never changes `next_step`: RoboTrunk never limits or blocks a purchase over a notice, and no tool acts on one; tell the person and let them decide. Stock a store does not publish counts as available and says `not_published`; the store confirms it at checkout. Prices are never compared across currencies. It returns no delivery time. Delivery cost and tax are the store's to state at its checkout; with a country in force, the chosen offer carries the delivery the store's saved policy states in `landed_cost` where it settles one, as `price_plus_delivery` (not a total: any tax is added at the store's checkout) unless tax is settled too, and never an estimated tax.", "outputs": "`status` is `checked`, `checked_not_listed`, `not_identified`, `ambiguous`, `not_found`, `not_indexed` or `unavailable`. `checked_not_listed` means RoboTrunk does not list the product, so there is no price, offer or checkout and `next_step` is `null`; a `not_sold_by_robotrunk` message says so. `resource.identified` names what it was identified as (`brand`, `model`, `gtin`, `identity_key`, `decided_by`, `reason`, in the source's own words) beside `resource.recall`; while identification is still running, `resource.identified` is `null` and `resource.recall.live.pending` is `true`, so call again shortly before reporting any recall result. `not_identified` means nothing could be identified, and its code says why: `product_not_identified`, `page_refused`, `page_not_fetchable` or `gtin_not_known`. `resource.asked` echoes the string and how it was read, and the country in force when there was one (`country`), with `country_source` `buyer_country` or `inferred` when it was your `buyer_country` or a location the platform sent rather than a `country` the person stated. `resource.resolution` says how the product was decided: `decided_by: fixed_code` for a reference or link, `decided_by: model` with `judgement.outcome`, `confidence` and `reason` for a name, and `candidates[]` with a `reference` for each when unresolved. `resource.product` names the listing (`merchant`, `product_id`, `title`, `vendor`, `store_product_url`, `robotrunk_page_url`, `evidence_product_id`, `retrieved_at`). `resource.checked_facts.facts[]` carries `field`, `value`, `stated_as`, `source_url`, `source_type` and `source_read_at` for every fact, with `evidence_url` for the whole pack and `from_listing` naming whose pack it is. `resource.recall.status` is `found`, `none_found_after_lookup`, `not_checked`, `lookup_pending`, `identification_pending`, `lookup_incomplete` or `lookup_skipped`; `found` stays the headline, and `listings_read[]` is historical evidence that does not override it. `resource.recall` also carries `note`, `regulators_asked`, `from_listing`, `evidence_url`, `pack_published_at`, `unreadable_listings[]` and `listings_read[]`; `resource.recall.live` is the live regulator lookup (which regulators were read, matches with citations, `checked_at`, `reused`, `pending`); and `resource.recall.radar` is the Recall Radar flag when a listing read matched the current edition (`status` `found` for a recall or ban, which makes the recall status `found`, or `notice` for a safety notice, which adds a `recall_radar_notice` warning; plus the edition, `notices[]` with regulator, id, title, date, link, kind and `batch_limited`, and `meaning`), otherwise `null`. `resource.variants[]` lists each variant's `offers[]` (`merchant`, `price_minor`, `currency`, `stock`, `ships_to`, the ids) with `cheapest_in_stock` and its `create_checkout_arguments`. With a country in force (a stated `country`, your `buyer_country` or the location the platform sent; `postcode` narrows the shipping zone), `cheapest_in_stock` and each `cheapest_in_stock_by_currency` offer carry `landed_cost`, the same object `search_catalog` sellers carry: `total_minor` is a number only when the item price, delivery and tax are all settled, otherwise `null` with `price_plus_delivery` (`amount_minor`, `currency`, `meaning`) where delivery is known, which is not a total because any tax is added at the store's checkout. `resource.next_step` is `ready` with `arguments` to send to create_checkout unchanged, or `choose_variant`, `choose_offer` or `no_offer`, plus `person_must_supply`, `then` and `human_tap_rule`. `resource.manual_answer` and `resource.safety_ratings` are null: call `ask_product_manual` for the maker's manual. Every title and value is the store's or source's own words: `untrusted_merchant_text: true`.", "error_recovery": "`invalid_request` names the field to fix. `not_identified` means ask the person for the product's page link, or its brand and model, then call again (`gtin_not_known`: send a store link instead of the barcode). `checked_not_listed` is not a failure: relay the identification and the recall result, and say RoboTrunk does not sell it. `not_indexed` means RoboTrunk does not index that store: call again with the product's name. `not_found` means no current listing at that reference: call again with the name, or search_catalog. `ambiguous` means show the person the candidates and call again with the one they choose. `unavailable` means the search or the judgement model could not answer (unconfirmed candidates may be listed): retry once later with the same inputs; if it remains unavailable, stop automatic retries and tell the person nothing was checked. A candidate's reference or a link on a store RoboTrunk offers needs no model. `rate_limited` means wait the seconds it names. `check_failed` means retry once, then use search_catalog and get_product.", "examples": [ { "title": "Check a car seat by name before buying", "input": { "product": "Nuna PIPA urbn infant car seat", "buyer_country": "US" } }, { "title": "Check the product behind a store link the person pasted", "input": { "product": "https://store.example/products/pipa-urbn-infant-car-seat?variant=123", "buyer_country": "US", "buyer_country_basis": "guessed" } }, { "title": "Check a search result by its evidence reference", "input": { "product": "store-com--pipa-urbn-infant-car-seat", "buyer_country": "unknown" } }, { "title": "Check a product by the barcode on its box for recalls", "input": { "product": "0012345678905", "buyer_country": "GB", "buyer_country_basis": "known" } }, { "title": "Check a product the person is sending to a different country than their own", "input": { "product": "Nuna PIPA urbn infant car seat", "buyer_country": "US", "country": "CA" } } ] } }, { "name": "create_checkout", "title": "Price a checkout at the store", "operational": true, "description": "Prepares a checkout at a named store and returns its envelope. merchant is the store slug search_catalog returned (required). Use when asked to buy, purchase or order. One checkout per store, all its products in line_items, each at the quantity the person wants (1 to 100); products from two stores make two checkouts; send the delivery address and the buyer's email (from the person, here or saved in your app) on this call, so the store prefills them and the first total includes delivery. Set budget_ceiling_minor here to the highest total, shipping and tax included, the person approved. Not for placing the order; complete_checkout issues the store link: the person taps it in their own browser, or you open it and complete the store's checkout. Next: if the store still asks for a detail, send what the person gives with update_checkout; read progress any time with get_checkout; when the status is ready_for_complete call complete_checkout. Error recovery: buyer_identity_contact_method_required means send buyer.email from the person with update_checkout; BUDGET_EXCEEDED means the store's total, shipping and tax included, is over budget_ceiling_minor: tell the person the total, then raise the ceiling with update_checkout once they approve, or call cancel_checkout (the checkout still exists); MERCHANT_REJECTED_INPUT names the field the store refused, so fix it and retry with a new idempotency_key; invalid_request names the field to fix; address_not_accepted means you left out merchant or sent null, so this ran RoboTrunk's test demo: add the store's merchant slug and call again; MERCHANT_NOT_FOUND means that store is not offered, so call search_catalog; out_of_stock means tell the person and call search_catalog; quote_expired or checkout_expired_or_invalid_state means call create_checkout again; idempotency_conflict means retry with a new idempotency_key or null; rate_limited means wait 60 seconds; price_not_fresh means retry in a minute; network_error means call again; UCP_MERCHANT_BUSY, UCP_MERCHANT_UNAVAILABLE or UCP_MERCHANT_REFUSED means try again shortly; payment_unavailable means call submit_feedback; any other error, including tool_layer_failure: retry once, then call submit_feedback. An explicit merchant: null runs RoboTrunk's test demo instead (one item, one test address, nothing charged). Full guide: get_tool_guide or /agent/tools.json#create_checkout Example call: {\"merchant\":\"merchant-from-result\",\"line_items\":[{\"product_id\":\"product-id-from-result\",\"variant_id\":\"variant-id-from-result\",\"quantity\":2},{\"product_id\":\"product-id-2-from-result\",\"variant_id\":\"variant-id-2-from-result\",\"quantity\":1}],\"buyer_country\":\"US\",\"shipping_address\":{\"first_name\":\"first-name-from-person\",\"last_name\":\"last-name-from-person\",\"street_address\":\"street-from-person\",\"address_locality\":\"city-from-person\",\"address_region\":\"state-from-person\",\"postal_code\":\"zip-code-from-person\",\"address_country\":\"US\"},\"buyer\":{\"email\":\"email-from-person@example.com\"}}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": [ "string", "null" ], "maxLength": 100, "description": "The store slug search_catalog returned with the product. Required: a call without it is refused. Only an explicit null runs RoboTrunk's one-product test demo, which sells nothing." }, "line_items": { "type": "array", "minItems": 1, "maxItems": 50, "description": "For a store: one line per product, up to 50, quantity 1 to 100 each; the store has the final say on stock. For the RoboTrunk demo (merchant null): exactly one line at quantity 1. Example: [{\"product_id\": \"\", \"variant_id\": \"\", \"quantity\": 2}], the ids exactly as returned, never a page link.", "items": { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The product id from `search_catalog` or `get_product`." }, "variant_id": { "type": [ "string", "null" ], "maxLength": 300, "description": "Required for a store: the variant_id search_catalog or get_product returned. Null only in the demo (merchant null)." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many of this product: 1 to 100 at a store; must be 1 for the RoboTrunk demo (merchant null)." } }, "required": [ "product_id", "quantity" ], "additionalProperties": false } }, "buyer_country": { "type": "string", "pattern": "^([A-Z]{2}|unknown)$", "default": "unknown", "description": "Shopper's ISO country: what you know, else your best guess; unknown if none. Left out, it is read as unknown and the answer asks you to send it. Example: \"AU\", \"US\" or \"unknown\", never a country name." }, "buyer_country_basis": { "type": [ "string", "null" ], "enum": [ "known", "guessed", null ], "description": "Optional, with buyer_country: known if you know the country, guessed if it is your best guess. Null if neither." }, "shipping_address": { "type": [ "object", "null" ], "description": "The person's shipping address, or null. Example: {\"first_name\": \"\", \"last_name\": \"\", \"street_address\": \"\", \"extended_address\": \"\", \"address_locality\": \"\", \"address_region\": \"\", \"postal_code\": \"\", \"address_country\": \"US\"}: every <...> is the person's own value, never invented.", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The recipient first name." }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The recipient last name." }, "street_address": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The street address." }, "extended_address": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "description": "Apartment or suite (optional)." }, "address_locality": { "type": "string", "minLength": 1, "maxLength": 100, "description": "City (town or locality outside the US)." }, "address_region": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Two-letter state code, such as CA (state, province or region outside the US)." }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 100, "description": "ZIP code (postcode outside the US)." }, "address_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "The two-letter uppercase country code. Example: \"US\", not \"United States\"." }, "phone_number": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The delivery contact phone number." } }, "required": [ "first_name", "last_name", "street_address", "address_locality", "address_region", "postal_code", "address_country" ], "additionalProperties": false }, "budget_ceiling_cents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Demo only (merchant null); ignored at a store, so use budget_ceiling_minor there. Null otherwise." }, "idempotency_key": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 128, "description": "16 to 128 printable ASCII characters, or null to have the tool generate one. Each internal step gets its own suffixed key, so a repeat is safe." }, "buyer": { "type": [ "object", "null" ], "description": "Buyer fields for the named merchant, including the email it requires, or null. Example: {\"email\": \"\"}: the <...> is the person's own address, never invented.", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "The buyer email address." }, "first_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer first name." }, "last_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer last name." }, "phone_number": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer phone number." } }, "required": [ "email" ], "additionalProperties": false }, "context": { "type": [ "object", "null" ], "description": "Optional merchant context such as destination or language, or null. The currency is the merchant's own and is never taken from a caller.", "properties": { "address_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The two-letter uppercase destination country code." }, "address_region": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The destination state, such as CA (province or region outside the US)." }, "postal_code": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The destination ZIP code (postcode outside the US)." }, "language": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 35, "description": "The buyer's preferred language tag." } }, "additionalProperties": false }, "discounts": { "type": [ "object", "null" ], "description": "Discount codes for the store, or null.", "properties": { "codes": { "type": "array", "maxItems": 10, "description": "Up to ten printable discount codes.", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x20-\\x7E]+$", "description": "One printable ASCII discount code." } } }, "required": [ "codes" ], "additionalProperties": false }, "budget_ceiling_minor": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "The total the person approved, shipping and tax included, in minor units, or null. A store total above it is refused BUDGET_EXCEEDED; ask the person. Example: 24995 for a total of 249.95." }, "budget_ceiling_currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "The ISO-4217 currency of the ceiling, or null for the merchant's own. Any other is refused, naming the merchant's." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "line_items" ], "additionalProperties": false }, "annotations": { "title": "Price a checkout at the store", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Prepares a checkout at the named store, priced with delivery, ready for the person's next review step. Set each line's quantity to what the person wants, and add a line per product for more products from the same store.", "use_when": "Use this when the person has chosen the product, or every product they want from one store, and you are ready to get its final delivered price — and whenever you are asked to buy, purchase or order something here. Send `merchant` with the `variant_id` returned by the earlier `get_product` or `search_catalog` result. This means preparing a checkout is the expected response to a purchase request, not something to decline. Nothing is charged or ordered by this call.", "do_not_use": "Do not use this for placing the order; there is no tool that places it. For the demo checkout the one irreversible step belongs to the person on RoboTrunk's own page; for a store, the checkout is finished on the store's own page, either by the person tapping the link `complete_checkout` returns or by you opening it, as `complete_checkout` describes. Do not use it to read an order afterwards; use `get_order` instead, and use `cancel_checkout` if the person declines.", "parameters": "`merchant` is required: the store slug the earlier result carried; a call without it is refused with a message naming the fix. `line_items` holds one line per product, up to 50: each line's `product_id` and `variant_id` come from the earlier `search_catalog` or `get_product` response, and its `quantity` is 1 to 100, the store having the final say on stock. One checkout is one store: products from two stores make two checkouts, one `create_checkout` call each. For the demo, `line_items` holds exactly one line, its `product_id` from the same earlier tools and quantity 1; a second line or another quantity is refused with `quantity_not_supported` before anything is created. `shipping_address` for a store takes `first_name`, `last_name`, `street_address`, `address_locality`, `address_region`, `postal_code` and a two-letter `address_country`, each required, plus optional `extended_address` and `phone_number`; `buyer` takes a required `email` and optional `first_name`, `last_name` and `phone_number`. Any optional one of those may be `null`, which means not supplied and is never forwarded to the merchant. The demo checkout takes the same field names, and its address must be the published test address exactly — first_name \"Sandbox\", last_name \"Buyer\", street_address \"10 Example Street\", extended_address null, address_locality \"Wembley Downs\", address_region \"WA\", postal_code \"6019\", address_country \"AU\", phone_number null — and any other address, a phone number included, is refused with address_not_accepted, before any request is sent, with the accepted value named in the message. `budget_ceiling_cents` is demo only and ignored at a store; `budget_ceiling_minor` is the ceiling for a store, in that merchant's minor units, with `budget_ceiling_currency` optional and, where given, that merchant's own currency. At a store the ceiling is the total the person approved and is compared with the store's own total, shipping and tax included; a store total over it is refused with `BUDGET_EXCEEDED`, whose message names the store's total and the approved amount with the currency and tells you to ask the person before going further — read it to them. The checkout still exists after that refusal: if the person then approves the higher total, call `update_checkout` with `budget_ceiling_minor` set to it, or call this tool again with `budget_ceiling_minor: null` for no ceiling at all. Searching never needs a budget. `buyer_country` is the two-letter country code of where the shopper is, from what you know of them (their account, device location or the conversation), otherwise your best guess; ask the shopper only if you cannot guess, and send `unknown` if you have no sign at all. `unknown` never fails a checkout. It does not choose the store, the destination, the price or the shipping: the `shipping_address` does, so a checkout whose address is in another country than `buyer_country` is prepared for that address exactly as it would be otherwise. RoboTrunk records it only to see which platforms know the shopper's country and which guess it; optionally set `buyer_country_basis` to `known` or `guessed`. Every other argument is optional in substance: `null` means not supplied. `idempotency_key` and `budget_ceiling_cents` are arguments to this tool rather than fields of a rail request — the first becomes the `Idempotency-Key` header, the second belongs to the demo — so neither appears in the body sent to a store. `idempotency_key` may be null, in which case the tool generates one; supplied keys must be 16 to 128 printable ASCII characters and are reused safely for the same request.", "caveats": "Use the store's returned `expires_at`, currency, totals and `next_actions`. A store checkout can be created up to 10 times a minute from one calling address. This tool returns no payment details, cookie value or full secret, and complete_checkout issues the store link. Demo only (merchant null): the checkout expires 15 minutes after creation, the run authority is a browser cookie that lives 24 hours, shipping is a flat sandbox rate and the payment is Stripe test mode, so nothing is charged, ordered or shipped.", "outputs": "For a named merchant, `resource.id` is the opaque checkout handle and `next_actions` normally points to `complete_checkout`; that tool returns `human_tap.url`; the checkout can be finished in either of two ways: the person taps the link in their own browser, or you open it and complete the store's own checkout. `human_tap.budget_ceiling_minor` is the highest total, shipping and tax included, that RoboTrunk checked the store's total against, and RoboTrunk refuses the handoff with `BUDGET_EXCEEDED` when the store's total is above it. `human_tap.affiliate.disclosure` is present when an affiliate link applies. For the demo, `resource.checkout_id` feeds `cancel_checkout` and `get_order`, while `resource.confirmation_url` is the link to hand the person: RoboTrunk's approval page, which shows the item, variant, delivery region and total and takes one biometric touch — a fingerprint, face unlock or device passkey prompt — where the browser has one, and a plain single button where it does not. That gesture is checked by the browser and never reaches RoboTrunk; it adds no server-side authority, and the server still verifies the same run cookie, confirmation cookie, single-use CSRF value, server-issued single-use idempotency key, same-origin submission and five-minute session it always has. No tool can submit either page. `links[]` carries that link as `approval_page` and the plain confirmation page as `confirmation_page`, for a person who would rather use the button alone. `resource.totals` carries `items_cents`, `shipping_cents`, `total_cents`, `currency` and `formatted_total`; `resource.expires_at` is when the checkout dies; `resource.delivery_region`, `resource.source_retailer` and `resource.price_may_differ` are the disclosures to relay. `instructions.for_human` is ready-made wording to pass on and `instructions.for_agent` is your own next step. Do not open `confirmation_url` yourself and do not put it somewhere the person opens it from another app: the run cookie is `SameSite=Strict`, so a navigation that starts in a chat window or a different origin arrives without it and the page can only refuse. The person approves in the panel on the RoboTrunk page they already have open; the link is the fallback for when that page is in front of them and something has gone wrong with the panel.", "error_recovery": "`BUDGET_EXCEEDED` means the store's total, shipping and tax included, is over the `budget_ceiling_minor` the person approved; the message says so in words to read to the person, `errors[0]` names the ceiling, `total_minor` and the goods, shipping and tax lines the store shows, and `resource.id` is the checkout to act on — it still exists — so ask the person, then raise the ceiling with `update_checkout` once they approve, create it again without a ceiling, or `cancel_checkout`. `invalid_request` names the field to fix, then call this tool again; `quantity_not_supported` answers only the demo checkout (merchant null), which takes one line at quantity 1, so send that, or name the store for several products; `run_authority_missing` means this browser lost its run cookie, so call this tool again to get a new one; `checkout_expired_or_invalid_state` means the 15 minutes ran out, so call this tool again; `quote_expired` means the shipping quote went stale, so call this tool again; `out_of_stock` means the source variant went unavailable, so tell the person and call `search_catalog`; `idempotency_conflict` means the key is already bound elsewhere, so retry with a new `idempotency_key` or null; `rate_limited` means the cart budget is spent, so wait 60 seconds; `price_not_fresh` means no validated snapshot exists, so retry in a minute; `payment_unavailable` cannot be retried into a success, so call `submit_feedback`; `network_error` means the step never reached the store, so call this tool again. For a named merchant, `MERCHANT_REJECTED_INPUT` means the merchant took the call and refused one named field, and `errors[]` names it, so fix the named field and retry with a new key. Every error names the step that failed.", "examples": [ { "title": "Prepare one store checkout for two products, two of the first and one of the second, with the person's delivery address and email, so the store's first total includes delivery: replace the merchant, product and variant placeholders with values from the same store's search_catalog or get_product results, and every from-person value with what the person gave you (in this conversation or saved in your app); never invent one, and ask the person when you do not have it", "input": { "merchant": "merchant-from-result", "line_items": [ { "product_id": "product-id-from-result", "variant_id": "variant-id-from-result", "quantity": 2 }, { "product_id": "product-id-2-from-result", "variant_id": "variant-id-2-from-result", "quantity": 1 } ], "buyer_country": "US", "shipping_address": { "first_name": "first-name-from-person", "last_name": "last-name-from-person", "street_address": "street-from-person", "extended_address": null, "address_locality": "city-from-person", "address_region": "state-from-person", "postal_code": "zip-code-from-person", "address_country": "US", "phone_number": null }, "buyer": { "email": "email-from-person@example.com", "first_name": null, "last_name": null, "phone_number": null }, "context": null, "discounts": null, "budget_ceiling_cents": null, "budget_ceiling_minor": null, "budget_ceiling_currency": null, "idempotency_key": null } } ] } }, { "name": "get_checkout", "title": "Read a checkout at the store", "operational": true, "description": "Reads the current state of a checkout at a store, by checkout_id. Use this when you need the latest merchant status after creation, update or payment at the store. Not for the demo checkout's id (merchant null); read that one with get_order. Outputs: resource, status, next_actions and suggested_tools. A status of requires_escalation, or the message store_checkout_step, means the store needs a step finished on its own checkout page: call complete_checkout; its link opens that page, and the step is finished there before paying, by the person or by you. With click_and_collect_on_store_page, keep this checkout's link to collect: the choice is on that page; send the person there, not to the store's website separately. Error recovery: buyer_identity_contact_method_required means send buyer.email from the person with update_checkout; NOT_A_RAIL_CHECKOUT means the id is not a ucp_ checkout, so call create_checkout with a merchant; continuation_not_found means that reference is unknown, expired (they last up to 24 hours) or from another environment, so call create_checkout again; RUN_AUTH_REQUIRED means checkout_id was not the reference an earlier answer returned, or the 24-hour run behind it has ended, so send it back exactly as given and, if you did, call create_checkout again; CHECKOUT_NOT_FOUND means that checkout cannot be read, so never guess an id; RATE_LIMITED means wait and retry; SERVICE_UNAVAILABLE or a store error (UCP_MERCHANT_BUSY, UCP_MERCHANT_UNAVAILABLE) means retry shortly; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: update_checkout while the status asks for details, complete_checkout when it is ready_for_complete. Full guide: get_tool_guide or /agent/tools.json#get_checkout Example call: {\"checkout_id\":\"ucp_transcend-dev-lab_abc123\"}", "inputSchema": { "type": "object", "properties": { "checkout_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The checkout handle an earlier UCP checkout tool returned as resource.id. Pass it back exactly as given." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "checkout_id" ], "additionalProperties": false }, "annotations": { "title": "Read a checkout at the store", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Reads the current merchant-rail checkout and returns its status, public line items, totals, messages and next actions.", "use_when": "Use this when you have a `checkout_id` from `create_checkout`, `update_checkout` or `complete_checkout` and need a fresh merchant read, especially after payment at the store.", "do_not_use": "Do not use this for the test-mode demo checkout's id (merchant null); read that one with `get_order`. Do not use it to approve, pay or submit a handoff; use `complete_checkout` to issue the store checkout link.", "parameters": "`checkout_id` is whatever the earlier checkout tools handed back as `resource.id`, and the same value is prefilled in their `suggested_tools`. Over a transport that replaces RoboTrunk's own identifiers with references — the MCP server does — that is the reference, not a raw `ucp_` id, and passing it back unchanged is always right. The browser's same-origin run cookie is sent automatically; no cookie value belongs in the input.", "caveats": "The checkout handle is opaque and belongs to the browser run that created it. The rail returns public merchant data only, never payment details or a full secret. Reads are idempotent and a handle can expire or become terminal.", "outputs": "Outputs: `resource.id`, `resource.merchant`, `resource.line_items`, `resource.totals`, `status`, `next_actions` and `suggested_tools[]`. Feed `resource.id` to `update_checkout`, `complete_checkout`, `cancel_checkout` or this tool again; feed `resource.order.local_order_id` to `get_order` after the merchant reports an order.", "error_recovery": "Error recovery: `NOT_A_RAIL_CHECKOUT` means the id is not a `ucp_` checkout, so call `create_checkout` with a merchant, `RUN_AUTH_REQUIRED` means `checkout_id` was not the handle an earlier answer returned or the 24-hour run behind it has ended, so send it back exactly as given and, if you did, call `create_checkout` again, over MCP `continuation_not_found` means the reference is unknown, expired (at most 24 hours) or from another environment, `CHECKOUT_NOT_FOUND` means the handle cannot be read, `RATE_LIMITED` means wait and retry, and `SERVICE_UNAVAILABLE` or a store error means retry only as suggested. Never replace a missing handle by guessing an id.", "examples": [ { "title": "Read after payment at the store", "input": { "checkout_id": "ucp_transcend-dev-lab_abc123" } } ] }, "input_examples": [ { "checkout_id": "ucp_transcend-dev-lab_abc123" } ], "output": { "highlights": [ "status", "resource.id", "resource.totals", "suggested_tools" ] }, "agent_guidance": { "when_to_use": "Use after a checkout-changing call or after payment at the store.", "workflow": "Read the status and merchant messages before choosing the next action.", "follow_ups": [ "update_checkout", "complete_checkout", "get_order" ] }, "errors": [ { "code": "RAIL_NOT_AVAILABLE", "description": "The UCP rail is disabled.", "agent_actions": [ "search_catalog" ] }, { "code": "MERCHANT_NOT_FOUND", "description": "The named merchant is not configured.", "agent_actions": [ "search_catalog" ] }, { "code": "PAYMENT_INSTRUMENT_NOT_ACCEPTED", "description": "Payment details must never be sent to this rail.", "agent_actions": [ "complete_checkout" ] }, { "code": "RATE_LIMITED", "description": "The public read or mutation budget was reached.", "agent_actions": [ "retry" ] }, { "code": "HANDOFF_SESSION_INVALID", "description": "The checkout link is invalid or expired.", "agent_actions": [ "complete_checkout" ] }, { "code": "UCP_TOKEN_NOT_CONFIGURED", "description": "Merchant order readback is not configured.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_TOKEN_REJECTED", "description": "The merchant rejected the order readback token.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_MERCHANT_BUSY", "description": "The merchant is temporarily busy.", "agent_actions": [ "retry" ] }, { "code": "UCP_MERCHANT_REFUSED", "description": "The merchant refused the request.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "UCP_MERCHANT_UNAVAILABLE", "description": "The merchant is temporarily unavailable.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "MERCHANT_REJECTED_INPUT", "description": "The merchant refused a named field in the request.", "agent_actions": [ "update_checkout", "create_checkout" ] }, { "code": "BUDGET_EXCEEDED", "description": "The store's total, shipping and tax included, is more than the total the person approved. Read the message to the person and ask before going further. The checkout still exists.", "agent_actions": [ "update_checkout", "cancel_checkout" ] }, { "code": "CHECKOUT_NOT_FOUND", "description": "The checkout does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "ORDER_NOT_FOUND", "description": "The order does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "RUN_AUTH_REQUIRED", "description": "The run cookie is missing or invalid.", "agent_actions": [ "create_checkout" ] }, { "code": "INVALID_REQUEST", "description": "The request body or header is invalid.", "agent_actions": [ "self" ] }, { "code": "INVALID_STATE", "description": "The checkout cannot take that action in its current state.", "agent_actions": [ "get_checkout", "create_checkout" ] }, { "code": "HANDOFF_NOT_AVAILABLE", "description": "The merchant has not supplied a validated payment handoff.", "agent_actions": [ "get_checkout", "retry" ] }, { "code": "NOT_FOUND", "description": "The requested rail resource is not available.", "agent_actions": [ "search_catalog" ] }, { "code": "SERVICE_UNAVAILABLE", "description": "The rail could not complete the request.", "agent_actions": [ "retry" ] }, { "code": "IDEMPOTENCY_CONFLICT", "description": "The key was reused with a different request.", "agent_actions": [ "self" ] }, { "code": "IDEMPOTENCY_SCOPE_CONFLICT", "description": "The key belongs to another route or run.", "agent_actions": [ "self" ] }, { "code": "REQUEST_TOO_LARGE", "description": "The request body exceeded the rail limit.", "agent_actions": [ "self" ] }, { "code": "NOT_A_RAIL_CHECKOUT", "description": "The id is not a UCP rail checkout handle.", "agent_actions": [ "create_checkout" ] } ], "aliases": [ "read_checkout", "get_merchant_checkout", "checkout_read" ] }, { "name": "update_checkout", "title": "Update a checkout at the store", "operational": true, "description": "Sends permitted buyer, address, line-item, context, discount or fulfilment changes to a checkout at a store. Use this when a checkout from create_checkout needs correction before handoff, and to send the buyer's email and full delivery address (from the person, in this conversation or saved in your app) if you did not send them on create_checkout, so the store prefills them and the total includes delivery. Not for paying or sending payment details. Outputs: the updated rail envelope and suggested_tools. Error recovery: buyer_identity_contact_method_required means the store needs the buyer's email, so send buyer.email from the person; BUDGET_EXCEEDED means the store's total, shipping and tax included, is over the ceiling the person approved: tell the person, then raise budget_ceiling_minor once they approve or call cancel_checkout; MERCHANT_REJECTED_INPUT means the store refused one field that errors[] names, so fix it and retry with a new key; IDEMPOTENCY_CONFLICT means use a fresh key for a changed request; INVALID_REQUEST names a body or header problem; INVALID_STATE means the checkout cannot change now, so call get_checkout, then create_checkout again if it ended; CHECKOUT_NOT_FOUND means the handle is unavailable, so call create_checkout again; continuation_not_found or RUN_AUTH_REQUIRED means send checkout_id exactly as an earlier answer returned it and, if you did, call create_checkout again; PAYMENT_INSTRUMENT_NOT_ACCEPTED means remove payment data and retry; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: get_checkout to read the new status, complete_checkout when it is ready_for_complete. Full guide: get_tool_guide or /agent/tools.json#update_checkout Example call: {\"checkout_id\":\"ucp_transcend-dev-lab_abc123\",\"buyer\":{\"email\":\"buyer@example.test\"}}", "inputSchema": { "type": "object", "properties": { "checkout_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The UCP checkout id from create_checkout or get_checkout." }, "buyer": { "type": [ "object", "null" ], "description": "Buyer details for the merchant, or null to leave them unchanged. Example: {\"email\": \"\"}: the <...> is the person's own address, never invented.", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "The buyer email address." }, "first_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer first name." }, "last_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer last name." }, "phone_number": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The buyer phone number." } }, "required": [ "email" ], "additionalProperties": false }, "shipping_address": { "type": [ "object", "null" ], "description": "The merchant shipping address, or null to leave it unchanged. Example: {\"first_name\": \"\", \"last_name\": \"\", \"street_address\": \"\", \"extended_address\": \"\", \"address_locality\": \"\", \"address_region\": \"\", \"postal_code\": \"\", \"address_country\": \"US\"}: every <...> is the person's own value, never invented.", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The recipient first name." }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The recipient last name." }, "street_address": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The street address." }, "extended_address": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "description": "Apartment or suite (optional)." }, "address_locality": { "type": "string", "minLength": 1, "maxLength": 100, "description": "City (town or locality outside the US)." }, "address_region": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Two-letter state code, such as CA (state, province or region outside the US)." }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 100, "description": "ZIP code (postcode outside the US)." }, "address_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "The two-letter uppercase country code. Example: \"US\", not \"United States\"." }, "phone_number": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The delivery contact phone number." } }, "required": [ "first_name", "last_name", "street_address", "address_locality", "address_region", "postal_code", "address_country" ], "additionalProperties": false }, "context": { "type": [ "object", "null" ], "description": "Optional merchant context, or null to leave it unchanged.", "properties": { "address_country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The two-letter uppercase destination country code." }, "address_region": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The destination state, such as CA (province or region outside the US)." }, "postal_code": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The destination ZIP code (postcode outside the US)." }, "language": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 35, "description": "The buyer's preferred language tag." } }, "additionalProperties": false }, "discounts": { "type": [ "object", "null" ], "description": "Discount codes for the merchant, or null to leave them unchanged.", "properties": { "codes": { "type": "array", "maxItems": 10, "description": "Up to ten printable discount codes.", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x20-\\x7E]+$", "description": "One printable ASCII discount code." } } }, "required": [ "codes" ], "additionalProperties": false }, "line_items": { "type": [ "array", "null" ], "description": "Replacement line items: the whole basket, every line the checkout should hold, up to 50 at a quantity of 1 to 100 each, all from this checkout's store; or null to leave the current set unchanged. Example: [{\"product_id\": \"\", \"variant_id\": \"\", \"quantity\": 1}], the ids exactly as returned, never a page link.", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The product id from the merchant catalogue." }, "variant_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The variant id from the merchant catalogue." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many of this product, 1 to 100; the store has the final say on stock." } }, "required": [ "product_id", "variant_id", "quantity" ], "additionalProperties": false } }, "fulfillment_option_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "description": "The selected fulfillment option id, or null." }, "budget_ceiling_minor": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "The total the person approved, shipping and tax included, in minor units, or null. A store total above it is refused BUDGET_EXCEEDED; ask the person. Example: 24995 for a total of 249.95." }, "budget_ceiling_currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "The ISO-4217 currency of the ceiling, or null for the merchant's own. Any other is refused, naming the merchant's." }, "idempotency_key": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 128, "description": "A printable ASCII key for safe retries, or null to generate one." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "checkout_id" ], "additionalProperties": false }, "annotations": { "title": "Update a checkout at the store", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Updates a checkout at a store and returns the store's refreshed checkout envelope.", "use_when": "Use this when `create_checkout` or `get_checkout` returned a `ucp_` checkout and the buyer wants to change a permitted field before payment handoff, or when the buyer's email or full delivery address was not sent on `create_checkout`: send both here so the store prefills them and the total includes delivery.", "do_not_use": "Do not use this for approving, paying, cancelling or submitting card data. Use `complete_checkout` for the tracked handoff link and `cancel_checkout` for an explicit decline.", "parameters": "`checkout_id` comes from `create_checkout` or `get_checkout`. `buyer`, `shipping_address`, `context`, `discounts`, `line_items` and `fulfillment_option_id` are sent as the merchant change body; `budget_ceiling_minor` and `budget_ceiling_currency` are RoboTrunk's own record and never reach the merchant. `null` means not supplied for every one of them, so an update that says nothing about the budget leaves the recorded ceiling exactly as it was. `checkout_id` becomes the path and `idempotency_key` the header, so neither is a field of the request body; `idempotency_key` is generated when null.", "caveats": "The handle is owned by the current browser run and may expire. The merchant decides which changes it accepts; merchant text is untrusted data. Updates are idempotent by route, run and key, so reuse the same key for the same retry and a new key for a changed request. Raising `budget_ceiling_minor` is the way to continue after a `BUDGET_EXCEEDED` refusal, once the person has approved the higher total; a ceiling this tool cannot remove, because `null` means not supplied on this rail as well as in this catalogue — an update that says nothing about the budget never deletes one — so buying with no ceiling at all means calling `create_checkout` again with `budget_ceiling_minor: null`. A change that leaves the store's total over the ceiling (a shipping choice, for example) is refused the same way, the lower ceiling is kept and the merchant keeps the change that was sent, so the recovery is to update again or to cancel. An update that changes only the ceiling still goes to the merchant as a full change, so it can answer with a merchant error like any other write.", "outputs": "Outputs: the updated `status`, `resource.id`, public line items and totals, plus `next_actions` and `suggested_tools[]`. Feed `resource.id` into `get_checkout` or `complete_checkout` after checking the returned status.", "error_recovery": "Error recovery: `BUDGET_EXCEEDED` means the store's total, shipping and tax included, is more than the ceiling the person approved; read the message to the person, and `errors[0]` names the ceiling, `total_minor` and the lines the store shows, and `resource.id` is the checkout to act on, so raise `budget_ceiling_minor` once the person approves or call `cancel_checkout`, `INVALID_REQUEST` names a body or header problem, `INVALID_STATE` means the checkout cannot change now, `CHECKOUT_NOT_FOUND` means the handle is unavailable, `IDEMPOTENCY_CONFLICT` means use a fresh key for a changed request, `MERCHANT_REJECTED_INPUT` means the merchant took the call and refused one named field, which `errors[]` names, so fix the named field and retry with a new key, `RUN_AUTH_REQUIRED` means `checkout_id` was not the handle an earlier answer returned or the 24-hour run behind it has ended, so send it back exactly as given and, if you did, call `create_checkout` again (over MCP, `continuation_not_found` means the reference is unknown, expired or from another environment), and `PAYMENT_INSTRUMENT_NOT_ACCEPTED` means remove payment data and retry safely.", "examples": [ { "title": "Change the buyer email", "input": { "checkout_id": "ucp_transcend-dev-lab_abc123", "buyer": { "email": "buyer@example.test" }, "shipping_address": null, "context": null, "discounts": null, "line_items": null, "fulfillment_option_id": null, "budget_ceiling_minor": null, "budget_ceiling_currency": null, "idempotency_key": null } }, { "title": "Raise the ceiling after the person approved a higher price", "input": { "checkout_id": "ucp_transcend-dev-lab_abc123", "buyer": null, "shipping_address": null, "context": null, "discounts": null, "line_items": null, "fulfillment_option_id": null, "budget_ceiling_minor": 9000, "budget_ceiling_currency": null, "idempotency_key": null } } ] }, "input_examples": [ { "checkout_id": "ucp_transcend-dev-lab_abc123", "buyer": { "email": "buyer@example.test" }, "shipping_address": null, "context": null, "discounts": null, "line_items": null, "fulfillment_option_id": null, "budget_ceiling_minor": null, "budget_ceiling_currency": null, "idempotency_key": null } ], "output": { "highlights": [ "status", "resource.id", "resource.totals", "suggested_tools" ] }, "agent_guidance": { "when_to_use": "Use before the handoff link when the buyer changes a field the merchant rail accepts, or when the buyer's email or delivery address is still missing.", "workflow": "Send only the changed fields (and, if the buyer's email or full delivery address was not sent on create_checkout, send them now so the store prefills them and the total includes delivery), inspect the refreshed status, then complete or read again.", "follow_ups": [ "get_checkout", "complete_checkout", "cancel_checkout" ] }, "errors": [ { "code": "RAIL_NOT_AVAILABLE", "description": "The UCP rail is disabled.", "agent_actions": [ "search_catalog" ] }, { "code": "MERCHANT_NOT_FOUND", "description": "The named merchant is not configured.", "agent_actions": [ "search_catalog" ] }, { "code": "PAYMENT_INSTRUMENT_NOT_ACCEPTED", "description": "Payment details must never be sent to this rail.", "agent_actions": [ "complete_checkout" ] }, { "code": "RATE_LIMITED", "description": "The public read or mutation budget was reached.", "agent_actions": [ "retry" ] }, { "code": "HANDOFF_SESSION_INVALID", "description": "The checkout link is invalid or expired.", "agent_actions": [ "complete_checkout" ] }, { "code": "UCP_TOKEN_NOT_CONFIGURED", "description": "Merchant order readback is not configured.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_TOKEN_REJECTED", "description": "The merchant rejected the order readback token.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_MERCHANT_BUSY", "description": "The merchant is temporarily busy.", "agent_actions": [ "retry" ] }, { "code": "UCP_MERCHANT_REFUSED", "description": "The merchant refused the request.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "UCP_MERCHANT_UNAVAILABLE", "description": "The merchant is temporarily unavailable.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "MERCHANT_REJECTED_INPUT", "description": "The merchant refused a named field in the request.", "agent_actions": [ "update_checkout", "create_checkout" ] }, { "code": "BUDGET_EXCEEDED", "description": "The store's total, shipping and tax included, is more than the total the person approved. Read the message to the person and ask before going further. The checkout still exists.", "agent_actions": [ "update_checkout", "cancel_checkout" ] }, { "code": "CHECKOUT_NOT_FOUND", "description": "The checkout does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "ORDER_NOT_FOUND", "description": "The order does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "RUN_AUTH_REQUIRED", "description": "The run cookie is missing or invalid.", "agent_actions": [ "create_checkout" ] }, { "code": "INVALID_REQUEST", "description": "The request body or header is invalid.", "agent_actions": [ "self" ] }, { "code": "INVALID_STATE", "description": "The checkout cannot take that action in its current state.", "agent_actions": [ "get_checkout", "create_checkout" ] }, { "code": "HANDOFF_NOT_AVAILABLE", "description": "The merchant has not supplied a validated payment handoff.", "agent_actions": [ "get_checkout", "retry" ] }, { "code": "NOT_FOUND", "description": "The requested rail resource is not available.", "agent_actions": [ "search_catalog" ] }, { "code": "SERVICE_UNAVAILABLE", "description": "The rail could not complete the request.", "agent_actions": [ "retry" ] }, { "code": "IDEMPOTENCY_CONFLICT", "description": "The key was reused with a different request.", "agent_actions": [ "self" ] }, { "code": "IDEMPOTENCY_SCOPE_CONFLICT", "description": "The key belongs to another route or run.", "agent_actions": [ "self" ] }, { "code": "REQUEST_TOO_LARGE", "description": "The request body exceeded the rail limit.", "agent_actions": [ "self" ] }, { "code": "NOT_A_RAIL_CHECKOUT", "description": "The id is not a UCP rail checkout handle.", "agent_actions": [ "create_checkout" ] } ], "aliases": [ "edit_checkout", "change_checkout", "update_merchant_checkout" ] }, { "name": "complete_checkout", "title": "Hand off to the store's checkout to pay", "operational": true, "description": "Creates a short-lived tracked payment handoff for a checkout at a store and returns its link. Use this when the checkout is ready to pay. The checkout can be finished in either of two ways: the person taps the link in their own browser, or you open it and complete the store's own checkout. human_tap.budget_ceiling_minor is the highest total, shipping and tax included, that RoboTrunk checked the store's total against, and RoboTrunk refuses the handoff with BUDGET_EXCEEDED when the store's total is above it. human_tap.affiliate.disclosure is present when an affiliate link applies. RoboTrunk never takes the payment or sees the card. The link goes through RoboTrunk straight to the store's own checkout, with no approval page, and can be opened again within its 30 minutes, each time landing on the same store checkout; a HEAD request or a request with a Purpose header gets an empty 204 and goes nowhere. Not for claiming an order was placed. Outputs: human_tap.url and the envelope. If the status is requires_escalation or the answer carries store_checkout_step, the store needs a step finished on its own checkout page: the link opens that page, and the step is finished there before paying, by the person or by you. With click_and_collect_on_store_page, keep this checkout's link to collect: the choice is on that page; send the person there, not to the store's website separately. Error recovery: buyer_identity_contact_method_required means send buyer.email from the person with update_checkout, then call this again; HANDOFF_NOT_AVAILABLE means the store has not supplied a handoff yet, so call get_checkout and try again later; CHECKOUT_NOT_FOUND, continuation_not_found or RUN_AUTH_REQUIRED means the handle cannot be used, so send checkout_id exactly as an earlier answer returned it and, if you did, call create_checkout again; HANDOFF_SESSION_INVALID means the link cannot be used, so call complete_checkout again for a new one; BUDGET_EXCEEDED means the store's total is now over the ceiling, so tell the person the new total and raise budget_ceiling_minor with update_checkout only on their new approval; IDEMPOTENCY_CONFLICT means use a new key only for a different request; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: read the result with get_checkout once the payment is made at the store; watch_recalls then watches the products for a recall. Full guide: get_tool_guide or /agent/tools.json#complete_checkout Example call: {\"checkout_id\":\"ucp_transcend-dev-lab_abc123\"}", "inputSchema": { "type": "object", "properties": { "checkout_id": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The UCP checkout id returned by an earlier checkout tool." }, "idempotency_key": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 128, "description": "A printable ASCII key for safe retries, or null to generate one." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "checkout_id" ], "additionalProperties": false }, "annotations": { "title": "Hand off to the store's checkout to pay", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Issues a short-lived link to the store's own checkout for a ready checkout at a store; the person taps it to finish there, or the agent opens it and completes the store's checkout; the link itself does not place the order.", "use_when": "Use this when `create_checkout`, `get_checkout` or `update_checkout` reports a checkout ready for payment.", "do_not_use": "Do not use this for claiming an order is complete or for sending card details to RoboTrunk. It only issues the link. The checkout can be finished in either of two ways: the person taps `human_tap.url` in their own browser, or you open it and complete the store's own checkout. `human_tap.budget_ceiling_minor` is the highest total, shipping and tax included, that RoboTrunk checked the store's total against, and `human_tap.affiliate.disclosure` is present when an affiliate link applies. The link goes through RoboTrunk straight to the store, without an approval page. Either way, call `get_checkout` after payment.", "parameters": "`checkout_id` is the handle the earlier checkout tools returned as `resource.id`; pass it back exactly as given, whatever form it takes on the transport you are using. `idempotency_key` is for safe repeat requests and may be null so the page generates one.", "caveats": "The link lives for 30 minutes. Every valid GET of it redirects to the store's checkout and it can be opened again within that time, each open landing on the same store checkout; the first open records the link as used, and a HEAD request or a request with a Purpose header gets an empty 204 and goes nowhere. The merchant checkout is the payment surface and RoboTrunk never sees the card. The ceiling counts the store's whole total, shipping and tax included, and it is checked when the link is issued and again when the link is first opened, after refreshing a stale store total: a store total the rail last recorded above it is refused with `BUDGET_EXCEEDED` and the link stays unused. A successful response is `handoff_issued`, not `completed`; only a later checkout read can show the merchant's order state.", "outputs": "Outputs: `human_tap.url` is the handoff link, `human_tap.expires_at` is its lifetime, `human_tap.budget_ceiling_minor` and `human_tap.budget_ceiling_currency` are the ceiling the store's total was checked against (both `null` when none is recorded or nothing current could be compared, and then the link is the person's to open), and `resource.id` is the checkout to read afterwards. `suggested_tools[]` is derived from the rail's `next_actions[]` and pre-fills that id.", "error_recovery": "Error recovery: `HANDOFF_NOT_AVAILABLE` means the merchant has not supplied a validated handoff, `CHECKOUT_NOT_FOUND` or `RUN_AUTH_REQUIRED` means the handle cannot be used (`RUN_AUTH_REQUIRED`: it was not the handle an earlier answer returned or the 24-hour run behind it has ended, so send it back exactly as given and, if you did, call `create_checkout` again; over MCP, `continuation_not_found` means the reference is unknown, expired or from another environment), `HANDOFF_SESSION_INVALID` means the link cannot be used, `BUDGET_EXCEEDED` means the store's total is now more than the ceiling, so tell the person the new total and raise `budget_ceiling_minor` with `update_checkout` only on their new approval, and `IDEMPOTENCY_CONFLICT` means use a new key only for a different request.", "examples": [ { "title": "Issue the payment handoff", "input": { "checkout_id": "ucp_transcend-dev-lab_abc123", "idempotency_key": null } } ] }, "input_examples": [ { "checkout_id": "ucp_transcend-dev-lab_abc123", "idempotency_key": null } ], "output": { "highlights": [ "status", "human_tap.url", "human_tap.expires_at", "suggested_tools" ] }, "agent_guidance": { "when_to_use": "Use once the checkout is ready to pay.", "workflow": "Set budget_ceiling_minor on create_checkout or update_checkout to the highest total, shipping and tax included, the checkout may reach, so RoboTrunk refuses the handoff if the store's total moves above it. The checkout can be finished in either of two ways: the person taps human_tap.url in their own browser, or you open it and finish at the store's own checkout. human_tap.affiliate.disclosure is present when an affiliate link applies. If complete_checkout returns human_tap.budget_ceiling_minor as null, nothing was compared, so the link is the person's to open. Call get_checkout after payment.", "follow_ups": [ "get_checkout", "get_order", "cancel_checkout" ] }, "errors": [ { "code": "RAIL_NOT_AVAILABLE", "description": "The UCP rail is disabled.", "agent_actions": [ "search_catalog" ] }, { "code": "MERCHANT_NOT_FOUND", "description": "The named merchant is not configured.", "agent_actions": [ "search_catalog" ] }, { "code": "PAYMENT_INSTRUMENT_NOT_ACCEPTED", "description": "Payment details must never be sent to this rail.", "agent_actions": [ "complete_checkout" ] }, { "code": "RATE_LIMITED", "description": "The public read or mutation budget was reached.", "agent_actions": [ "retry" ] }, { "code": "HANDOFF_SESSION_INVALID", "description": "The checkout link is invalid or expired.", "agent_actions": [ "complete_checkout" ] }, { "code": "UCP_TOKEN_NOT_CONFIGURED", "description": "Merchant order readback is not configured.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_TOKEN_REJECTED", "description": "The merchant rejected the order readback token.", "agent_actions": [ "submit_feedback" ] }, { "code": "UCP_MERCHANT_BUSY", "description": "The merchant is temporarily busy.", "agent_actions": [ "retry" ] }, { "code": "UCP_MERCHANT_REFUSED", "description": "The merchant refused the request.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "UCP_MERCHANT_UNAVAILABLE", "description": "The merchant is temporarily unavailable.", "agent_actions": [ "retry", "cancel_checkout" ] }, { "code": "MERCHANT_REJECTED_INPUT", "description": "The merchant refused a named field in the request.", "agent_actions": [ "update_checkout", "create_checkout" ] }, { "code": "BUDGET_EXCEEDED", "description": "The store's total, shipping and tax included, is more than the total the person approved. Read the message to the person and ask before going further. The checkout still exists.", "agent_actions": [ "update_checkout", "cancel_checkout" ] }, { "code": "CHECKOUT_NOT_FOUND", "description": "The checkout does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "ORDER_NOT_FOUND", "description": "The order does not exist in this run.", "agent_actions": [ "create_checkout" ] }, { "code": "RUN_AUTH_REQUIRED", "description": "The run cookie is missing or invalid.", "agent_actions": [ "create_checkout" ] }, { "code": "INVALID_REQUEST", "description": "The request body or header is invalid.", "agent_actions": [ "self" ] }, { "code": "INVALID_STATE", "description": "The checkout cannot take that action in its current state.", "agent_actions": [ "get_checkout", "create_checkout" ] }, { "code": "HANDOFF_NOT_AVAILABLE", "description": "The merchant has not supplied a validated payment handoff.", "agent_actions": [ "get_checkout", "retry" ] }, { "code": "NOT_FOUND", "description": "The requested rail resource is not available.", "agent_actions": [ "search_catalog" ] }, { "code": "SERVICE_UNAVAILABLE", "description": "The rail could not complete the request.", "agent_actions": [ "retry" ] }, { "code": "IDEMPOTENCY_CONFLICT", "description": "The key was reused with a different request.", "agent_actions": [ "self" ] }, { "code": "IDEMPOTENCY_SCOPE_CONFLICT", "description": "The key belongs to another route or run.", "agent_actions": [ "self" ] }, { "code": "REQUEST_TOO_LARGE", "description": "The request body exceeded the rail limit.", "agent_actions": [ "self" ] }, { "code": "NOT_A_RAIL_CHECKOUT", "description": "The id is not a UCP rail checkout handle.", "agent_actions": [ "create_checkout" ] } ], "aliases": [ "human_payment_handoff", "start_payment_handoff", "complete_merchant_checkout" ] }, { "name": "cancel_checkout", "title": "Cancel a prepared checkout", "operational": true, "description": "Declines a prepared checkout, returning status canceled: it asks the store to cancel that checkout. Use when the person declines, so a refusal is a recorded outcome rather than an inferred one. Not for reversing a payment: RoboTrunk holds no stock and charges nothing. Not for after approval; use get_order. Next: search_catalog for something else, or submit_feedback to say why. Error recovery: not_found (the demo) or CHECKOUT_NOT_FOUND (a store's checkout) means that checkout was never prepared here, so call create_checkout; continuation_not_found or RUN_AUTH_REQUIRED means send checkout_id exactly as an earlier answer returned it and, if you did, the checkout can no longer be read from here, so call create_checkout again; UCP_MERCHANT_BUSY, UCP_MERCHANT_REFUSED or UCP_MERCHANT_UNAVAILABLE means the store did not take the cancel, so try again shortly; on the demo a failed decline record is only a warning and the cancel still stands; any other error, including tool_layer_failure: retry once, then call submit_feedback. For RoboTrunk's test demo checkout (merchant null) it closes the checkout here and records the decline. Full guide: get_tool_guide or /agent/tools.json#cancel_checkout Example call: {\"checkout_id\":\"the checkout_id create_checkout returned\",\"reason\":\"Above the person's ceiling\"}", "inputSchema": { "type": "object", "properties": { "checkout_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The `checkout_id` returned by `create_checkout` in this browser." }, "reason": { "type": [ "string", "null" ], "maxLength": 300, "description": "Why the checkout was declined, or null. Free text up to 300 characters; do not put personal data here." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "checkout_id" ], "additionalProperties": false }, "annotations": { "title": "Cancel a prepared checkout", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Cancels a checkout you prepared: it asks the store to cancel it (for RoboTrunk's test demo checkout, merchant null, it closes it here and records the decline). It returns `status: \"canceled\"` so a refusal is a recorded outcome rather than something inferred from silence.", "use_when": "Use this when the person decides not to buy, or when you decide the checkout should not proceed — a price above their ceiling, a wrong item, a change of mind.", "do_not_use": "Do not use this for releasing stock or reversing a payment; nothing is held and nothing is charged. Do not use it after the person has confirmed; at that point call `get_order` instead, and use `submit_feedback` to say what went wrong.", "parameters": "`checkout_id` is the value `create_checkout` returned. `reason` is optional free text of up to 300 characters and should carry no personal data.", "caveats": "It asks the store to cancel the checkout and returns the store's checkout envelope with status `canceled`; it records no decline of its own. Demo only (merchant null): there is no server-side cancel, so it closes the checkout in this page's registry and records the decline; the demo checkout expires within 15 minutes anyway. Safe to call more than once.", "outputs": "For a store's checkout, the store's checkout envelope with `status: \"canceled\"`. For the demo, `resource.checkout_id` and `resource.state` confirm which checkout was closed, `resource.declined_at` is when, and `resource.feedback_recorded` says whether the decline was recorded; when it was not, a warning explains and the cancel still stands. `next_actions` points you back at `search_catalog` and `submit_feedback`.", "error_recovery": "`CHECKOUT_NOT_FOUND` means that checkout was never prepared here, so call `create_checkout`; `RUN_AUTH_REQUIRED` or, over MCP, `continuation_not_found` means send `checkout_id` exactly as an earlier answer returned it and, if you did, call `create_checkout` again; `UCP_MERCHANT_BUSY`, `UCP_MERCHANT_REFUSED` or `UCP_MERCHANT_UNAVAILABLE` means the store did not take the cancel, so try again shortly. On the demo, `not_found` means this page never prepared that checkout, so call `create_checkout`, and `network_error` on the decline record is only a warning: the cancel stands.", "examples": [ { "title": "Decline on the record", "input": { "checkout_id": "the checkout_id create_checkout returned", "reason": "Above the person's ceiling" } } ] } }, { "name": "get_order", "title": "Read back an order", "operational": true, "description": "Reads back a store's order: the status and the totals as the store recorded them, in the store's own currency, and whether the store's own record is behind them (order_source, merchant_read). Use after the person has paid at the store and you want to check the order exists and read it back. Pass order_id or checkout_id. A store checkout_id reads that checkout's state while it has no order: a cancelled or expired checkout answers with its status and the message no_order_placed, saying no order was placed, and one still waiting on the person says no order has been confirmed yet, so call again in a moment; once the person has paid at the store's page, the store reports the order on a read of its checkout: the answer is status completed with the message order_confirmed (\"The store confirmed order #1019.\") and the store's order number in resource.order.label (resource.label on the order), shown only when the store reports one; resource.order.local_order_id is the order_id to read the order itself with (order_source, merchant_read, and order_from_checkout when the store's own order record was not read for it). Shipping, cancellation and refund after that are not shown. Not for placing or approving an order. Error recovery: identifier_required means pass order_id or checkout_id; not_found means no order can be read with that id, because over /mcp an order is read only with the order_id or checkout_id exactly as an earlier answer returned it, so call submit_feedback if the person did confirm, then start again with search_catalog; run_authority_missing or RUN_AUTH_REQUIRED on an id you were given means the run that owns the order has ended and no retry reaches it, so call submit_feedback; continuation_not_found means that reference is unknown, expired (references last up to 24 hours) or from another environment, so call search_catalog; rate_limited means wait 60 seconds; network_error means call again; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: submit_feedback to say what was unclear. It also reads RoboTrunk's test demo order (merchant null): pass that checkout_id while the person decides. Full guide: get_tool_guide or /agent/tools.json#get_order Example call: {\"checkout_id\":\"the checkout_id create_checkout returned\"}", "inputSchema": { "type": "object", "properties": { "order_id": { "type": [ "string", "null" ], "maxLength": 200, "description": "The order id from `/orders/{order_id}` after the person confirms, or null to look it up from `checkout_id`." }, "checkout_id": { "type": [ "string", "null" ], "maxLength": 200, "description": "The `checkout_id` from `create_checkout`, or null when you already hold `order_id`. At least one of the two must be non-null." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [], "additionalProperties": false }, "annotations": { "title": "Read back an order", "readOnlyHint": true, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Reads back a store's order with the status and totals as the store recorded them, in the store's own currency. It also reads RoboTrunk's test demo order (merchant null).", "use_when": "Use this when the person has paid at the store (or, for the demo checkout, pressed confirm on RoboTrunk's confirmation page) and you want to check the order really exists and read it back to them.", "do_not_use": "Do not use this for placing or approving an order; it only reads one back. For a store it reports the order the store itself reported once the person has paid at its page (the message `order_confirmed`); for the v1 demo the person's confirmation on RoboTrunk's page is what places it. To price something use `create_checkout` instead.", "parameters": "Supply at least one of `order_id` or `checkout_id`; both may not be null. `order_id` for a store's order is the id `get_checkout` returns as `resource.order.local_order_id`. `checkout_id` comes from `create_checkout` and reads a store checkout's own state while it has no order (see Outputs). Demo only: `order_id` comes from the order page the person lands on after confirming, at `/orders/{order_id}`, and when you pass the demo's `checkout_id`, this tool checks whether the window this page opened has reached an order page — either the approval page or the plain confirmation page redirects there — so you can poll politely while the person decides.", "caveats": "It returns no payment details and no full address: a store's order carries only the public data the store returns, and the demo order only its delivery region. An order is read only with the `order_id` or `checkout_id` exactly as an earlier answer returned it. For the demo checkout, if the person has not confirmed yet, this is not an error: you get `status: \"awaiting_human_confirmation\"` and the confirmation link to hand them again. `order_source` and `merchant_read` describe a store's order, so a checkout that was cancelled, expired or not yet paid has no order and carries neither. A store reports an order on a read of its checkout once the person has paid at its page; the number and link are what it reported when the checkout completed, and shipping, cancellation and refund after that are not read.", "outputs": "For the demo order, `resource.order_id`, `resource.status`, `resource.item` (product_id, title, variant, quantity, unit_price_cents), `resource.shipping_cents`, `resource.total_cents` with `formatted_total`, `resource.delivery_region` and `resource.created_at`. `links[]` carries `order_page`, RoboTrunk's readable order page, and `order_record`, the store's own record of the same order. `instructions.for_human` is wording you can read out. For a store's order, the totals are the store's own, in its own currency, and `order_source` says where the order came from: `merchant_order` when the merchant's own order read is behind it, and `checkout_completion` when it is what the completed checkout itself recorded. `merchant_read` says how current that is: `{\"status\": \"fresh\", \"read_at\": ...}` for a merchant answer inside its window, or `{\"status\": \"unavailable\", \"reason\": ...}` when the store could not be read again, in which case the order exists and the totals are the ones recorded at completion, so say nothing about fulfilment. A store checkout that has no order answers with the checkout's own `status` (`canceled`, `expired`, `handoff_issued`, `requires_escalation`, `ready_for_complete` or `incomplete`), one `no_order_placed` message and the same sentence in `instructions.for_human`: a cancelled or expired checkout says no order was placed; any other says no order has been confirmed yet, because the person may be paying right now, so call this tool again in a moment. Once the store has completed the checkout the answer is status `completed` with the message `order_confirmed` (\"The store confirmed order #1019.\" when the store's order number has the shape of one, otherwise \"The store confirmed this order.\") and the same sentence in `instructions.for_human`; the store's order number is `resource.order.label` on the checkout answer and `resource.label` on the order answer, shown only when the store reports one, and `resource.order.local_order_id` is the `order_id` to read the order with. `order_from_checkout` says the answer is built from what the store reported when the checkout completed and that its own order record was not read for it, so shipping, cancellation and refund are not shown.", "error_recovery": "`not_found` means no order can be read with that id, and creating another checkout will not surface it — report it with `submit_feedback` if the person did confirm, then start again from `search_catalog`; `run_authority_missing` means this browser lost the run authority that owns the order, and a new checkout issues a new run rather than recovering the old one, so no retry reaches it and `submit_feedback` is the honest next step; `rate_limited` means the run read budget is spent, so wait 60 seconds and call this tool again; `network_error` means the request never reached the store, so call this tool again. Over MCP an order is readable only with the `order_id` or `checkout_id` exactly as an earlier answer returned it, so a typed, retyped or made-up id answers `not_found`; `run_authority_missing` or `RUN_AUTH_REQUIRED` on an id you were given means the run behind it has ended; `continuation_not_found` means the reference is unknown, expired (at most 24 hours) or from another environment, so call `search_catalog`; and `identifier_required` means pass `order_id` or `checkout_id`.", "examples": [ { "title": "Poll while the person decides", "input": { "order_id": null, "checkout_id": "the checkout_id create_checkout returned" } }, { "title": "Read back a confirmed order", "input": { "order_id": "the id in /orders/{order_id}", "checkout_id": null } } ] } }, { "name": "get_trust_manifest", "title": "Read RoboTrunk's trust manifest", "operational": true, "description": "Returns RoboTrunk's trust manifest whole: what the service is, and that checkout at a listed store is real: the store is the seller, charges and ships, and RoboTrunk never sees the card. It also holds RoboTrunk's published statistics and, last, the contract of its one test demo checkout (no real charge, no order, no shipping). Use when you want to check what RoboTrunk claims about itself. Takes no parameters. Error recovery: rate_limited means wait 60 seconds; service_unavailable means retry later; network_error means call again; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: search_catalog to shop. Full guide: get_tool_guide or /agent/tools.json#get_trust_manifest Example call: {}", "inputSchema": { "type": "object", "properties": { "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [], "additionalProperties": false }, "annotations": { "title": "Read RoboTrunk's trust manifest", "readOnlyHint": true, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "Fetches RoboTrunk's machine-readable trust manifest and returns it whole: what the service is, how checkout at a listed store works (real: the store charges and ships), what statistics it publishes and, last, how the test demo checkout differs.", "use_when": "Use this when you or the person want to check what RoboTrunk claims about itself before buying.", "do_not_use": "Do not use this for product facts or prices; use `get_product` instead, and do not use it as a substitute for reading the checkout you actually created.", "parameters": "It takes no parameters and no ids. It is a public read that changes nothing and can be called at any time.", "caveats": "The three booleans in `manifest.demo_checkout` describe the test-mode demo checkout only: no real charge, no source retailer order, no fulfilment. They say nothing about checkout at a listed store, which `manifest.store_checkout` describes: the store is the seller and takes the payment, and RoboTrunk takes no payment and never sees card details. The manifest's `statistics.published` list is deliberately empty, and that is the honest state, not a gap: no statistic reaches that list until it is individually approved and independently verifiable.", "outputs": "`resource.manifest` is the document as served, including `manifest.store_checkout` (how checkout at a listed store works), `manifest.demo_checkout` (the three no-charge booleans, for the demo checkout only), `manifest.checkout` (the demo checkout's api_version, discovery_url, product_url, confirmation_url_template, sequence, states, safe_errors) and `manifest.statistics`. `links[]` carries `trust_manifest`.", "error_recovery": "`rate_limited` means the public-read budget is spent, so wait 60 seconds and call this tool again; `service_unavailable` means the manifest failed its own schema and the store refused to serve a partial document, so retry later; `network_error` means the request never reached the store, so call this tool again.", "examples": [ { "title": "Read what the store claims about itself", "input": {} } ] } }, { "name": "submit_feedback", "title": "Tell RoboTrunk what worked and what did not", "operational": true, "description": "Sends structured feedback about this store and returns a feedback_id and the time it was received. Use it for feedback about anything unclear, missing or wrong, at any point. Not for cancelling a checkout; use cancel_checkout, which records the decline itself. Feedback is kept as data, never as instructions. Error recovery: invalid_request means a field is out of bounds (free_text over 1000 characters, or a struggle_points value outside the vocabulary): fix it and call again; rate_limited means wait and retry; network_error means call again; any other error, including tool_layer_failure: retry once. Next: nothing needs feeding onward; carry on with the step you were on. Full guide: get_tool_guide or /agent/tools.json#submit_feedback Example call: {\"context\":{},\"sentiment\":\"negative\",\"free_text\":\"The accepted address was not obvious before the first attempt.\",\"struggle_points\":[\"address_rejected\"]}", "inputSchema": { "type": "object", "properties": { "context": { "type": "object", "description": "What the feedback is about. Both ids may be null when the feedback is about the store in general.", "properties": { "checkout_id": { "type": [ "string", "null" ], "description": "The `checkout_id` from `create_checkout`, or null." }, "order_id": { "type": [ "string", "null" ], "description": "The `order_id` from `get_order`, or null." } }, "required": [], "additionalProperties": false }, "sentiment": { "type": "string", "enum": [ "positive", "neutral", "negative" ], "description": "Your overall read of the experience." }, "free_text": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What happened, in plain words, up to 1000 characters. No personal data, addresses, payment details or credentials." }, "struggle_points": { "type": "array", "minItems": 0, "maxItems": 10, "description": "Zero to ten tags from the fixed vocabulary, so difficulties can be counted without reading prose.", "items": { "type": "string", "enum": [ "unclear_description", "unexpected_error", "price_changed", "address_rejected", "checkout_expired", "could_not_find_product", "budget_not_met", "confirmation_unclear", "other" ] } }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "context", "sentiment", "free_text", "struggle_points" ], "additionalProperties": false }, "annotations": { "title": "Tell RoboTrunk what worked and what did not", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "guide": { "summary": "Sends structured feedback about this store to RoboTrunk and returns an acknowledgement with a `feedback_id` and the time it was received.", "use_when": "Use this when the person asks to tell RoboTrunk that something was unclear, missing or wrong, or after an error you could not recover from; it takes feedback at any point, mid-checkout, after an order or after a decline.", "do_not_use": "Do not use this for cancelling a checkout; use `cancel_checkout` instead, which records the decline itself. Do not use it to ask a question and expect an answer: nothing replies.", "parameters": "`context.checkout_id` and `context.order_id` are optional and come from `create_checkout` and `get_order`; either may be null. `sentiment` is one of positive, neutral or negative. `free_text` is up to 1000 characters. `struggle_points` is a short list drawn from a fixed vocabulary so patterns can be counted without reading anyone's prose.", "caveats": "Feedback is never required and never blocks a purchase. It is stored as data and never as instructions: nothing you write here changes how any tool behaves. Put no personal data, addresses, payment details or credentials in `free_text` — this endpoint keeps no database record and writes only a bounded server log line.", "outputs": "`resource.feedback_id` and `resource.received_at` acknowledge receipt, and `resource.stored_as` says how it was kept. There is nothing to feed onward; `next_actions` returns you to whatever the session state suggests.", "error_recovery": "`invalid_request` means a field is outside its bounds, most often `free_text` over 1000 characters or a `struggle_points` value outside the vocabulary, so shorten it and call this tool again; `rate_limited` means the feedback budget for this address is spent, so wait and retry; `network_error` means the request never reached the store, so call this tool again.", "examples": [ { "title": "Report a difficulty", "input": { "context": { "checkout_id": null, "order_id": null }, "sentiment": "negative", "free_text": "The accepted address was not obvious before the first attempt.", "struggle_points": [ "address_rejected" ] } } ] } }, { "name": "get_tool_guide", "title": "Read one tool's complete guide", "operational": true, "description": "Returns the complete guide for one RoboTrunk tool: summary, when to use it, what not to use it for, parameters, caveats, outputs, error recovery and worked examples. Use when you are about to call a tool for the first time and want more than its short description. Error recovery: not_found is the only error; its message lists every valid name, so pick one and call again. Next: call the tool you read about, feeding an example's input straight back in. Every tool is listed at /agent/tools.json. Full guide: get_tool_guide or /agent/tools.json#get_tool_guide Example call: {\"tool_name\":\"create_checkout\"}", "inputSchema": { "type": "object", "properties": { "tool_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "description": "The exact name of a registered tool, as it appears in this catalogue, or null for the list of every tool with its title." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [], "additionalProperties": false }, "annotations": { "title": "Read one tool's complete guide", "readOnlyHint": true, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "Returns the full, unabridged guide for one registered tool — everything the short description had to leave out — as a structured object rather than one long string.", "use_when": "Use this when you are about to call a tool for the first time, when a short description leaves you unsure which parameter comes from where, or when an error code named a recovery you want to read in full.", "do_not_use": "Do not use this for running the tool; call the tool by its own name instead. Do not use it to discover what tools exist; the catalogue you were registered with already lists them, and `/agent/tools.json` serves the same guides as one document.", "parameters": "`tool_name` is the exact name from the catalogue, such as `create_checkout`, or null (or left out) for the list of every tool with its title. Unknown names are refused with the list of valid names rather than a guess.", "caveats": "It reads a static catalogue that ships with this page, so it makes no network request, holds no handle and cannot fail for any reason but an unknown name. The guide it returns is the same text `/agent/tools.json` publishes.", "outputs": "`resource.name`, `resource.operational` and `resource.guide`, where the guide carries `summary`, `use_when`, `do_not_use`, `parameters`, `caveats`, `outputs`, `error_recovery` and `examples[]`. Feed an example's `input` straight back into the named tool.", "error_recovery": "`not_found` is the only error and it means the name is not in this catalogue; the message lists every valid name, so pick one and call again. There is nothing to retry and no network failure to recover from.", "examples": [ { "title": "Read a tool in full before first use", "input": { "tool_name": "create_checkout" } } ] } }, { "name": "ask_product_manual", "title": "Ask one product's manual a question", "operational": true, "description": "Asks one product's maker manual a specific question and returns the matching passage word for word, with the manual's link, the page and the section heading where the retained text has them, or says plainly that the manual does not cover it. Use when a shopper asks something the manual decides (installation, weight and height limits, age range, care, safety) about a product you hold a product_id for. Not for browsing; use search_catalog. It answers only from manuals RoboTrunk has read and checked, and never guesses. Error recovery: PRODUCT_NOT_FOUND means the store or product is not available through RoboTrunk right now (paused, or a wrong id), not that it is missing, so call search_catalog; INVALID_REQUEST names the field to fix; RATE_LIMITED means wait 60 seconds; unavailable means try again shortly; unverified means read the listed document or ask again; not_covered or no_manual means the manual does not answer it, so read the product's page with get_product; MANUAL_ASK_FAILED (or any other unexpected error): retry once, then call submit_feedback. Next: get_product, or create_checkout. Full guide: get_tool_guide or /agent/tools.json#ask_product_manual Example call: {\"merchant\":\"anbbaby-com\",\"product_id\":\"gid://shopify/Product/1234567890\",\"question\":\"What is the maximum weight for the seat?\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "The store slug from the earlier search_catalog result." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The product_id from search_catalog or get_product, or its bare numeric Shopify id. Example: \"gid://shopify/Product/1234567890\" or \"1234567890\", never a page link." }, "question": { "type": "string", "minLength": 3, "maxLength": 300, "description": "The person's question in plain words." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "product_id", "question" ], "additionalProperties": false }, "annotations": { "title": "Ask one product's manual a question", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "Answers one question from one product's retained maker manual: the passage that answers it, quoted exactly as the manual prints it and checked word for word against the retained text, with the document's URL, the page the extraction marked and the section heading printed above it.", "use_when": "Use this when the person asks a specific question the maker's manual settles, such as whether a car seat installs with a lap-sash belt, the maximum child height for a bassinet or how to wash a cover, about a product you hold from `search_catalog` or `get_product`.", "do_not_use": "Do not use this to find products; use `search_catalog`. Do not use it for price, stock or delivery; the manual says nothing about those and `get_product` and `create_checkout` do.", "parameters": "`merchant` is the store slug from the earlier `search_catalog` result. `product_id` is that result's `product_id`, or its bare numeric Shopify id. `question` is the person's question in plain words, 3 to 300 characters.", "caveats": "Only manuals the evidence pipeline has read, checked and published for that product can answer, so many products have none yet and answer `no_manual`. `page` is the page index the PDF extraction marked, which can differ from the number printed on the page. Answers take a few seconds because a model reads the closest passages.", "outputs": "`status` is `answered`, `not_covered`, `no_manual`, `unverified` or `unavailable`. On `answered`, `resource.passage.quote` is the maker's words, `resource.passage.document_url`, `page` and `section_heading` cite them, and `resource.answer` is one sentence restating only what the quote says. `resource.documents_searched` lists the manuals read. On anything else no passage is quoted and no answer sentence is given.", "error_recovery": "`INVALID_REQUEST` names the field to fix. `PRODUCT_NOT_FOUND` means the store or product is not available through RoboTrunk right now (paused, or a wrong id), not that it is missing; call `search_catalog`. `RATE_LIMITED` means wait 60 seconds. `unavailable` means try again shortly. `unverified` means the model's quote could not be matched to the manual; read the listed document or ask again.", "examples": [ { "title": "Ask a stroller manual about its weight limit", "input": { "merchant": "anbbaby-com", "product_id": "gid://shopify/Product/1234567890", "question": "What is the maximum weight for the seat?" } } ] } }, { "name": "watch_recalls", "title": "Watch a purchase's products for a recall", "operational": true, "description": "Starts a post-purchase recall watch on every product in a checkout that has been handed to the store to pay, once the person (or an agent authorised to accept on their behalf) has agreed to the current consent statement. RoboTrunk re-checks each watched product whenever a regulator publishes a new notice naming its brand; a match only ever flags with the regulator's own citation and never changes, cancels or delays the purchase. An item not matched to a listed product is watched by its checkout name, not refused; each product says watched_by \"product\" or \"name\". The full consent statement, version recall-watch-consent-v1: \"RoboTrunk will watch the products in this purchase for a recall. What is watched: each product bought through this checkout hand-off, re-checked whenever a regulator publishes a new notice naming its brand. What is stored: the product and its title, the channel chosen to be told (poll, an agent callback URL, or a person's email address), and, only for a channel that is switched on, that URL or address; never a name, a postal address or payment details. Channels: an agent can always poll get_recall_watch for the result; a callback URL is used only when RoboTrunk has switched callbacks on; a person's email is used only when RoboTrunk has switched email on, the person consents under the Australian Spam Act, and the address holder confirms it by a link sent to that address. Frequency cap: at most three messages a day on one channel, and at most one email a day to one address, several alerts combined into one. How to stop: call stop_recall_watch at any time, or use the one-click stop link in an email; stopping is instant and permanent, and removes the stored channel data. This watch never changes, cancels, blocks or delays the purchase it watches; a recall only ever flags with its regulator citation.\" channels is optional: leave it out for the poll-only watch every purchase gets, and a channels value that cannot be read is left out the same way, with the answer saying poll was used. One watch per checkout: a second call returns the existing watch unchanged, and a stopped watch cannot be restarted. Use it after complete_checkout; keep the watch_token it returns (shown once) for get_recall_watch and stop_recall_watch. Error recovery: consent_required means show the person the statement above and call again with it; invalid_request names the field to fix; channel_not_available means retry with channels left out (poll only); checkout_not_handed_off means call complete_checkout first; checkout_ended means there is nothing to watch; watch_stopped means this checkout's watch was stopped and cannot restart; product_not_resolved means no item could be matched or named; use check_product; checkout_too_large means more than 50 different products; forbidden, not_found or checkout_not_found means that checkout cannot be read here, so send checkout_id exactly as an earlier answer returned it; continuation_not_found means that reference is unknown or expired, so call create_checkout again; rate_limited means wait and retry; service_unavailable means try again later; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Next: get_recall_watch to poll for alerts. Full guide: get_tool_guide or /agent/tools.json#watch_recalls Example call: {\"checkout_id\":\"mcp1_c_examplereferencevaluehere0000000000000\",\"consent\":{\"given_by\":\"person\",\"statement_version\":\"recall-watch-consent-v1\"},\"channels\":[{\"kind\":\"poll\"}]}", "inputSchema": { "type": "object", "properties": { "checkout_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The reference get_checkout accepts for this checkout." }, "consent": { "type": "object", "properties": { "given_by": { "type": "string", "enum": [ "person", "agent_with_authority" ], "description": "\"person\" when the person themself agreed; \"agent_with_authority\" when you are authorised to accept such offers on their behalf." }, "statement_version": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Must be exactly \"recall-watch-consent-v1\", the version of the consent statement this tool's guide and description carry in full." } }, "required": [ "given_by", "statement_version" ], "additionalProperties": false }, "channels": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "poll" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "callback" }, "url": { "type": "string", "maxLength": 2048, "description": "An https URL RoboTrunk will POST each alert to, only while callbacks are switched on." } }, "required": [ "kind", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "email" }, "address": { "type": "string", "format": "email", "maxLength": 254, "description": "The address holder's own email; never used until they confirm it by the link RoboTrunk sends." }, "spam_act_consent": { "type": "boolean", "description": "true when the person themself agreed to be emailed (under the anti-spam law that applies, such as CAN-SPAM in the US or the Spam Act in Australia)." } }, "required": [ "kind", "address", "spam_act_consent" ], "additionalProperties": false } ] }, "description": "Optional: leave it out for a poll-only watch (poll is always on); a value that cannot be read as this list is left out and the answer says poll was used. When sent, one or more channels: callback and email are refused channel_not_available until RoboTrunk switches them on. Example: [{\"kind\": \"poll\"}]." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "checkout_id", "consent" ], "additionalProperties": false }, "annotations": { "title": "Watch a purchase's products for a recall", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Starts watching every product in a handed-off or completed checkout for a recall (an item it cannot match to a listed product is watched by the name on its checkout line), with poll always on and callback/email accepted only when switched on and consented to.", "use_when": "Use once a checkout has reached complete_checkout's hand-off (local status handoff_issued, completed_pending_order or completed) and the person has agreed to be watched. Call it right after telling the person their purchase will be watched, never before the hand-off.", "do_not_use": "Do not use this to check a product for a recall before buying; call check_product. Do not call it on a checkout that has not been handed off (ready_for_complete) or that ended (canceled, expired, failed); both are refused rather than started.", "parameters": "`checkout_id` is the reference get_checkout accepts for this purchase. `consent.given_by` is \"person\" when the person themself agreed, or \"agent_with_authority\" when you are authorised to accept such offers on their behalf. `consent.statement_version` must be exactly \"recall-watch-consent-v1\", the version of this statement: \"RoboTrunk will watch the products in this purchase for a recall. What is watched: each product bought through this checkout hand-off, re-checked whenever a regulator publishes a new notice naming its brand. What is stored: the product and its title, the channel chosen to be told (poll, an agent callback URL, or a person's email address), and, only for a channel that is switched on, that URL or address; never a name, a postal address or payment details. Channels: an agent can always poll get_recall_watch for the result; a callback URL is used only when RoboTrunk has switched callbacks on; a person's email is used only when RoboTrunk has switched email on, the person consents under the Australian Spam Act, and the address holder confirms it by a link sent to that address. Frequency cap: at most three messages a day on one channel, and at most one email a day to one address, several alerts combined into one. How to stop: call stop_recall_watch at any time, or use the one-click stop link in an email; stopping is instant and permanent, and removes the stored channel data. This watch never changes, cancels, blocks or delays the purchase it watches; a recall only ever flags with its regulator citation.\" `channels` is optional: leave it out, or send [{\"kind\":\"poll\"}], for a poll-only watch (poll is always on); a value that cannot be read as the list below is left out the same way, and the answer says poll was used. When you send it, it is one or more of: {\"kind\":\"poll\"} (always accepted), {\"kind\":\"callback\",\"url\":\"https://...\"} (accepted only when callbacks are switched on), or {\"kind\":\"email\",\"address\":\"...\",\"spam_act_consent\":true} (accepted only when email is switched on and given_by is \"person\").", "caveats": "Callback and email are refused channel_not_available until RoboTrunk switches them on; today only poll is available, so keep polling get_recall_watch. A watch also starts on a checkout that has already completed. An item RoboTrunk cannot match to a product it lists is watched by the name its store's checkout line states: its entry in resource.products has watched_by \"name\", product_id null and a watch_basis sentence, and a notice is matched to a name by RoboTrunk's model, which can be less sure than for a listed product; tell the person which items are watched by name. A finished checkout no longer holds its lines' names, so an unmatched line there cannot be watched: resource.not_watched counts those lines and the items_not_watched message says so; tell the person and use check_product on those items. resource.purchase_state is \"handed_off\" or \"completed\": RoboTrunk only learns a purchase completed from a later checkout read, so \"handed_off\" does not mean the purchase failed or was never made. A recall only ever flags with its citation; it never blocks, cancels, delays or otherwise changes this or any purchase, whether or not a watch exists.", "outputs": "status \"started\" on a new watch (resource.watch_token, shown once, is the authority to call get_recall_watch or stop_recall_watch; keep it), or \"watch_exists\" when this checkout already has one. resource.products[] lists each watched product's watched_by (\"product\" or \"name\"), current recall_status and any match already known at start; resource.alerts is empty at start, so poll get_recall_watch for later ones. An error status carries no resource beyond a type and null.", "error_recovery": "consent_required means no consent, or the wrong statement_version, was sent; show the person the statement in this guide and call again. channel_not_available means the requested channel is switched off, or an email channel's given_by or spam_act_consent was missing; retry with channels left out (poll only). checkout_not_handed_off means the checkout has not reached hand-off yet; call complete_checkout first. checkout_ended means the checkout was canceled, expired or failed, so there is nothing to watch. watch_stopped means this checkout's watch was already stopped and cannot be restarted. product_not_resolved means nothing in the checkout could be matched to a product RoboTrunk holds or named from the store's line, so there is nothing to watch and nothing was stored; use check_product for each item by name. checkout_too_large means the checkout has more than 50 different products, more than one watch covers. service_unavailable means the watch or its recall check is not reachable right now; nothing was stored, so try again later.", "examples": [ { "title": "Watch a just-handed-off purchase, polling only", "input": { "checkout_id": "mcp1_c_examplereferencevaluehere0000000000000", "consent": { "given_by": "person", "statement_version": "recall-watch-consent-v1" }, "channels": [ { "kind": "poll" } ] } } ] } }, { "name": "get_recall_watch", "title": "Read a recall watch", "operational": true, "description": "Reads a recall watch's current state and every alert newer than a given cursor, from stored rows only: no regulator call, no model call, no store call, so it is cheap to poll often. Use the watch_token watch_recalls returned when the watch started. First call: since null. Then pass the next_since value each answer returns to read only new alerts. Error recovery: watch_not_found means the token is wrong or the watch is stopped and past its term, so there is nothing to recover; rate_limited means wait the seconds stated and poll again; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Next: stop_recall_watch when the person asks to stop. Full guide: get_tool_guide or /agent/tools.json#get_recall_watch Example call: {\"watch_token\":\"rwt_exampletokenvaluehere00000000000000000000000\"}", "inputSchema": { "type": "object", "properties": { "watch_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The watch_token watch_recalls returned when the watch started." }, "since": { "type": [ "number", "null" ], "description": "The next_since cursor from a previous get_recall_watch answer, or null to read every alert from the start." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "watch_token" ], "additionalProperties": false }, "annotations": { "title": "Read a recall watch", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "The cheap pollable check for a recall watch: its current purchase_state, the watched products, and every alert newer than since.", "use_when": "Poll this after watch_recalls starts a watch, and again whenever you revisit the purchase, to see whether a new recall notice has matched a watched product.", "do_not_use": "Do not use this to start a watch; call watch_recalls. Do not use it to check a product for a recall before buying; call check_product.", "parameters": "`watch_token` is the token watch_recalls returned when the watch started. `since` is the next_since cursor from a previous get_recall_watch answer, or null to read every alert from the start.", "caveats": "A stopped watch answers status \"stopped\" with no new alerts, rather than an error. A wrong token and a stopped-and-past-its-term token both answer watch_not_found identically, so a token cannot be probed by trying values.", "outputs": "resource carries purchase_state, channels, products[] and alerts[] newer than since, plus next_since for the next poll. Each alert names the regulator, the notice (id, title, date, url) and a fixed meaning sentence: relay it to the person, and never say RoboTrunk changed, cancelled or delayed the purchase because of it.", "error_recovery": "watch_not_found means the token is wrong, or belongs to a watch that is stopped and past its term; there is nothing to recover, this watch is gone. rate_limited means wait the stated seconds and poll again.", "examples": [ { "title": "Poll for new alerts since the last check", "input": { "watch_token": "rwt_exampletokenvaluehere00000000000000000000000", "since": null } } ] } }, { "name": "stop_recall_watch", "title": "Stop a recall watch", "operational": true, "description": "Stops a recall watch for good: instant, permanent and idempotent. Erases the stored callback URL or email address in the same step the watch stops; the checkout this watch covered can never be watched again. Use when the person asks to stop the watch. Error recovery: watch_not_found means the token is wrong or the watch is already stopped and past its term; there is nothing further to do; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Nothing follows. Full guide: get_tool_guide or /agent/tools.json#stop_recall_watch Example call: {\"watch_token\":\"rwt_exampletokenvaluehere00000000000000000000000\"}", "inputSchema": { "type": "object", "properties": { "watch_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The watch_token watch_recalls returned when the watch started." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "watch_token" ], "additionalProperties": false }, "annotations": { "title": "Stop a recall watch", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "The opt-out. Stops a recall watch and erases its channel data, answering only after the stop has taken effect.", "use_when": "Use when the person withdraws consent to being watched, or no longer wants to hear about a recall on this purchase.", "do_not_use": "Do not use this to pause a watch; there is no pause. Stopping is permanent for this checkout, and a later watch_recalls call for the same checkout is refused watch_stopped.", "parameters": "`watch_token` is the token watch_recalls returned when the watch started.", "caveats": "A second call for an already-stopped watch answers the same stopped_at rather than an error. Stopping never affects the purchase itself, whether or not any product on it was recalled.", "outputs": "status \"stopped\" with resource.stopped_at. No further alert is ever produced for this watch, on any channel.", "error_recovery": "watch_not_found means the token is wrong, or the watch is already stopped and past its term; there is nothing further to do.", "examples": [ { "title": "Stop a watch", "input": { "watch_token": "rwt_exampletokenvaluehere00000000000000000000000" } } ] } }, { "name": "check_fit", "title": "Check whether a listing fits something", "operational": true, "description": "Asks whether one listing fits a named thing, such as a car, pram or bottle, and answers yes, no or not_known, from the listing's published checked facts and its own store page only. A yes or no always carries the exact quote it was read from and that quote's source; not_known means nothing RoboTrunk holds settles it. Never a guess. Use when a shopper asks whether a listing fits something they own; take merchant and product_id from search_catalog. For what the maker's manual says, fit included, use ask_product_manual: this tool reads only the listing and its store page. Confirm with the maker before relying on a fit for safety. Error recovery: PRODUCT_NOT_FOUND means the store or product is not available through RoboTrunk right now (paused, or a wrong id), not that it is missing, so call search_catalog; INVALID_REQUEST names the field to fix; RATE_LIMITED means wait 60 seconds; unavailable means try again shortly; FIT_ASK_FAILED (or any other unexpected error): retry once, then call submit_feedback. Next: get_product, or create_checkout. Full guide: get_tool_guide or /agent/tools.json#check_fit Example call: {\"merchant\":\"anbbaby-com\",\"product_id\":\"gid://shopify/Product/1234567890\",\"fits\":\"2022 Toyota RAV4\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "The store slug from the earlier search_catalog result." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The product_id from search_catalog or get_product, or its bare numeric Shopify id. Example: \"gid://shopify/Product/1234567890\" or \"1234567890\", never a page link." }, "fits": { "type": "string", "minLength": 3, "maxLength": 200, "description": "The thing to check fit against, in plain words, such as a car, pram or bottle." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "product_id", "fits" ], "additionalProperties": false }, "annotations": { "title": "Check whether a listing fits something", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Answers a shopper's fit question (does this listing fit a named car seat base, pram, bottle, and so on) as yes, no or not_known, with a word-for-word quote and its source whenever it is settled.", "use_when": "Use when the person asks whether a product you hold a product_id for is compatible with something they name, such as a specific car model, pram frame or bottle brand.", "do_not_use": "Do not use this to find products; use `search_catalog`. Do not use it for a question the maker's manual settles better, such as a weight or age limit; use `ask_product_manual`.", "parameters": "`merchant` is the store slug from the earlier `search_catalog` result. `product_id` is that result's `product_id`, or its bare numeric Shopify id. `fits` is the thing to check fit against, in plain words, 3 to 200 characters.", "caveats": "Only the listing's own published checked facts and its own store page are read; a maker's manual is not a source here. Many listings have neither a checked fact nor a readable store page today, so `not_known` is a common, honest answer, not a failure.", "outputs": "`status` is `answered` or `unavailable`. On `answered`, `resource.answer` is `yes`, `no` or `not_known`; a settled answer carries `resource.quote` (the source's own words) and `resource.source_type`/`resource.source_url`. `resource.reason` is one sentence on the reading. `resource.meaning` says to confirm with the maker before relying on fit for safety.", "error_recovery": "`INVALID_REQUEST` names the field to fix. `PRODUCT_NOT_FOUND` means the store or product is not available through RoboTrunk right now (paused, or a wrong id), not that it is missing; call `search_catalog`. `RATE_LIMITED` means wait 60 seconds. `unavailable` means try again shortly. `FIT_ASK_FAILED` (or any other unexpected error) means retry once, then call `submit_feedback`.", "examples": [ { "title": "Ask whether a car seat base fits a named car", "input": { "merchant": "anbbaby-com", "product_id": "gid://shopify/Product/1234567890", "fits": "2022 Toyota RAV4" } } ] } }, { "name": "watch_back_in_stock", "title": "Watch a sold-out listing for restock", "operational": true, "description": "Starts a poll-only watch on one listing the store itself currently shows as sold out, and returns a bearer token to poll or stop it. Refused not_sold_out on any listing that is not shown as sold out right now (unknown or not-published stock counts as available, never sold out), and listing_not_found for a store, product or variant RoboTrunk does not hold. Nothing is emailed or called back; poll get_back_in_stock_watch to learn when it flips. Use when a shopper wants to know when a sold-out listing comes back in stock. Keep the watch_token; stop with stop_back_in_stock_watch. Error recovery: invalid_request names the field to fix; listing_not_found means call search_catalog; not_sold_out means no watch is needed; rate_limited means wait a minute; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Next: get_back_in_stock_watch to poll for the restock. Full guide: get_tool_guide or /agent/tools.json#watch_back_in_stock Example call: {\"merchant\":\"anbbaby-com\",\"product_id\":\"gid://shopify/Product/1234567890\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "The store slug from the earlier search_catalog result." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The product_id from search_catalog or get_product, or its bare numeric Shopify id. Example: \"gid://shopify/Product/1234567890\" or \"1234567890\", never a page link." }, "variant_id": { "type": [ "string", "null" ], "maxLength": 200, "description": "One sold-out variant to watch, or null/omitted to watch the whole product, which alerts as soon as any variant is available again." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "product_id" ], "additionalProperties": false }, "annotations": { "title": "Watch a sold-out listing for restock", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "guide": { "summary": "Starts a back-in-stock watch on a listing the store shows as sold out right now, for up to 90 days, and returns the one-time watch_token needed to poll or stop it.", "use_when": "Use when a shopper wants to know when a specific sold-out listing (or one sold-out variant of it) comes back in stock.", "do_not_use": "Do not use this on a listing that is in stock, or whose stock the store does not publish; both are refused not_sold_out. Do not use this to find products; use search_catalog first.", "parameters": "`merchant` is the store slug from the earlier search_catalog result. `product_id` is that result's product_id, or its bare numeric Shopify id. `variant_id` is optional: name one sold-out variant, or omit it to watch the whole product, which alerts as soon as any variant is available again (not once every variant returns).", "caveats": "The watch_token is shown once, here, and never again; keep it to poll or stop the watch. A watch lapses on its own after about 90 days if nothing changes. This is a poll-only watch: nothing is emailed, called back or pushed; call get_back_in_stock_watch to check it.", "outputs": "status is ok or error. On ok, resource.watch_id, resource.watch_token, resource.listing and resource.state (\"sold_out\") confirm the watch; resource.started_at and resource.ends_at bound it.", "error_recovery": "invalid_request names the field to fix. listing_not_found means the store, product or variant is not available through RoboTrunk right now (paused, or a wrong id), not that it is missing; call search_catalog. not_sold_out means that listing is not shown as sold out right now, so no watch is needed. rate_limited means wait a minute.", "examples": [ { "title": "Watch a sold-out listing", "input": { "merchant": "anbbaby-com", "product_id": "gid://shopify/Product/1234567890", "variant_id": null } } ] } }, { "name": "get_back_in_stock_watch", "title": "Read a back-in-stock watch", "operational": true, "description": "Reads a back-in-stock watch's current state, from stored rows only: no store call, no model call, so it is cheap to poll often. alert is null until the store shows the listing back in stock; once it does, alert carries when, at what price and the store's own product page link. Use the watch_token watch_back_in_stock returned when the watch started. Error recovery: watch_not_found means the token is wrong or the watch does not exist, so there is nothing to recover; rate_limited means wait a minute and poll again; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Next: when alert appears, read the listing with get_product and buy with create_checkout. Full guide: get_tool_guide or /agent/tools.json#get_back_in_stock_watch Example call: {\"watch_token\":\"rwt_exampletokenvaluehere00000000000000000000000\"}", "inputSchema": { "type": "object", "properties": { "watch_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The watch_token watch_back_in_stock returned when the watch started." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "watch_token" ], "additionalProperties": false }, "annotations": { "title": "Read a back-in-stock watch", "readOnlyHint": true, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "The cheap pollable check for a back-in-stock watch: its listing, whether it is stopped, and alert (null until the store shows it back in stock).", "use_when": "Poll this after watch_back_in_stock starts a watch, to see whether the store has shown the listing back in stock yet.", "do_not_use": "Do not use this to start a watch; call watch_back_in_stock.", "parameters": "`watch_token` is the token watch_back_in_stock returned when the watch started.", "caveats": "watch_not_found is only for a wrong or unknown token. A stopped or past-its-term watch still resolves: this returns the stored watch with stopped_at set (or ends_at already past) rather than watch_not_found, so polling after stopping or lapsing still tells you the watch's final state. alert stays null until the store's stock actually flips; there is no separate push or email.", "outputs": "status is ok or error. On ok, resource carries listing, started_at, ends_at, stopped_at and alert (null, or back_at/price_minor/currency/product_page_url once it has fired).", "error_recovery": "watch_not_found means the token is wrong, or the watch does not exist; there is nothing to recover. rate_limited means wait a minute and poll again.", "examples": [ { "title": "Poll a watch", "input": { "watch_token": "rwt_exampletokenvaluehere00000000000000000000000" } } ] } }, { "name": "stop_back_in_stock_watch", "title": "Stop a back-in-stock watch", "operational": true, "description": "Stops a back-in-stock watch for good: instant, permanent and idempotent. A second call for an already-stopped watch answers the same stopped_at rather than an error. Use when the person no longer wants the watch. Error recovery: watch_not_found means the token is wrong or the watch does not exist; there is nothing further to do; watch_failed (or any other unexpected error): retry once, then call submit_feedback. Nothing follows. Full guide: get_tool_guide or /agent/tools.json#stop_back_in_stock_watch Example call: {\"watch_token\":\"rwt_exampletokenvaluehere00000000000000000000000\"}", "inputSchema": { "type": "object", "properties": { "watch_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The watch_token watch_back_in_stock returned when the watch started." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "watch_token" ], "additionalProperties": false }, "annotations": { "title": "Stop a back-in-stock watch", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "guide": { "summary": "The opt-out. Stops a back-in-stock watch; no further alert is ever produced for it.", "use_when": "Use when the person no longer wants to be told about this listing coming back in stock.", "do_not_use": "Do not use this to pause a watch; there is no pause. Stopping is permanent.", "parameters": "`watch_token` is the token watch_back_in_stock returned when the watch started.", "caveats": "Stopping never affects any purchase; it only ends the watch.", "outputs": "status ok with resource.status \"stopped\" and resource.stopped_at.", "error_recovery": "watch_not_found means the token is wrong or the watch does not exist; there is nothing further to do.", "examples": [ { "title": "Stop a watch", "input": { "watch_token": "rwt_exampletokenvaluehere00000000000000000000000" } } ] } }, { "name": "check_listing", "title": "Check a second-hand listing", "operational": true, "description": "You read the listing; RoboTrunk checks it. Use it for a second-hand listing on Facebook Marketplace or any other marketplace, such as a used car seat, cot, pram or heater: it adds a recall check and the sourced facts the listing leaves out, which can help the person decide. Send the listing's title, price, description and seller's notes as listing_text (and up to three photos), read with a Marketplace tool such as facebook-cli if you have one, otherwise a browser. One call returns the exact model; whether a product-safety regulator has recalled it, with the notice; what the listing leaves out (specifications, the maker's manual, expiry where the maker sets one, what to inspect in person, known problems), each with its source; and what the same product costs new against the asking price. If the exact product cannot be identified, the answer is not_identified and nothing is guessed: ask the person for the brand and model. If the person wants a second-hand listing checked but has not shared it yet, the check needs its link or text. If the person gives only a link, send it as listing_link: RoboTrunk never fetches Facebook Marketplace links, so when the answer is listing_text_required, read the listing yourself, first with a Facebook Marketplace tool if you have one, such as facebook-cli, and only otherwise in a browser, and call again with its title, price, description and seller notes as listing_text plus the link; if you cannot read it without logging in or passing a CAPTCHA, ask the person to paste those details. Other public pages RoboTrunk reads directly. Amazon links are never fetched. If resource.leaves_out.state is pending, call again in about a minute for the rest. Error recovery: invalid_request names the field to fix; not_identified means ask the person for the brand and model and call again; unavailable with hourly_bound_full means wait and try later, any other unavailable means try again shortly; check_listing_failed (or any other unexpected error): retry once, then call submit_feedback. Next: check_product with the identified brand and model, or search_catalog to shop for it new. Full guide: get_tool_guide or /agent/tools.json#check_listing Example call: {\"listing_text\":\"DaVinci Kalani 4-in-1 convertible crib in white. Used for one child, all hardware and the toddler rail included, a few teething marks on the top rail. Mattress not included.\",\"asking_price\":{\"amount\":90,\"currency\":\"USD\"},\"country\":\"US\"}", "inputSchema": { "type": "object", "properties": { "listing_text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The listing's own words as the person sees them." }, "asking_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "number", "description": "The asking price, in the listing's currency." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Three-letter currency code, such as USD." } }, "required": [ "amount", "currency" ], "additionalProperties": false, "description": "The listing's asking price, when it states one. Example: {\"amount\": 90, \"currency\": \"USD\"} for $90: the amount as written (89.5 for $89.50), not cents." }, "photos": { "type": [ "array", "null" ], "maxItems": 3, "items": { "type": "string", "minLength": 1 }, "description": "Up to three data:image/jpeg|png|webp;base64 images, at most 2 MB each decoded." }, "country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "Two-letter buyer country, such as US." }, "listing_link": { "type": [ "string", "null" ], "maxLength": 500, "description": "A listing link; public pages can be read without signing in. For a Facebook Marketplace link, read the listing with a Marketplace tool such as facebook-cli if you have one and send its text as listing_text too." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "anyOf": [ { "required": [ "listing_text" ], "properties": { "listing_text": { "type": "string", "minLength": 1 } } }, { "required": [ "listing_link" ], "properties": { "listing_link": { "type": "string", "minLength": 1 } } } ], "additionalProperties": false }, "annotations": { "title": "Check a second-hand listing", "readOnlyHint": false, "untrustedContentHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Answers three things about one used listing at once: safety (the live recall check across the regulators it reads, with the notice and its link when one names the product), what the listing leaves out (each item cited, and kept only when its source page confirms it), and the new price at RoboTrunk's stores or the maker's site, compared with the asking price.", "use_when": "Use when the person is looking at a second-hand listing (Facebook Marketplace, a classifieds site, a friend's post) and wants to know whether it is recalled, expired or fairly priced before they buy it.", "do_not_use": "Do not use this for a new product RoboTrunk sells; use `check_product`. Do not use it to find products; use `search_catalog`. Do not sign in or solve a CAPTCHA for this tool; if the page cannot be read, ask the person to paste its text.", "parameters": "Send `listing_text` (1 to 4000 characters) or `listing_link`. `asking_price` is `{ amount, currency }` with a three-letter currency such as `USD`, when the listing states one. `photos` is up to three `data:image/jpeg|png|webp;base64,...` images of at most 2 MB each, only when the text alone does not name the product. `country` is the two-letter buyer country, such as `US`. `listing_link` alone reads a public page; an excluded or unreadable page returns `listing_text_required` with open-and-retry instructions. For a Facebook Marketplace link, read the listing with a Marketplace tool such as facebook-cli first if you have one, then a browser. A link alongside pasted text is not fetched.", "caveats": "The first check of a product can take close to a minute. A part not finished in time answers `pending`; call again with the same listing about a minute later and it answers from the saved result, usually in seconds. What the listing leaves out can be thin for some products, because only claims whose source page confirms them are kept. A recall match means a model read the notice and judged it names this product: read the notice before relying on it. No match means no notice from the regulators read names it, never that the product is safe. A result is saved for 24 hours.", "outputs": "`status` is `checked`, `listing_text_required`, `not_identified`, `invalid_request` or `unavailable`. On `checked`, `resource.identified` names the brand and model with a confidence; `resource.safety.recall` carries the live recall answer and the regulators asked; `resource.leaves_out` carries `state` (`checked`, `pending` or a failure), `reused` and each cited item; `resource.new_price` lists RoboTrunk's offers, from every listing of the product the stores list, with each one's judged condition; `cheapest_robotrunk` (store, price, link), `saving_against_new` and `asking_as_percent_of_new` use only new ones, open-box or used offers are shown labelled and never as the new price, and `summary` says it in one plain sentence, including \"No new price at the stores RoboTrunk lists.\" when none exists, or what could not be finished.", "error_recovery": "`invalid_request` names the field to fix. `not_identified` means the listing did not name a product clearly enough; ask the person for the brand and model and call again. `unavailable` with `hourly_bound_full` means wait and try later; any other `unavailable` means try again shortly. A `pending` part means call again in about a minute.", "examples": [ { "title": "Check a used cot listing with its asking price", "input": { "listing_text": "DaVinci Kalani 4-in-1 convertible crib in white. Used for one child, all hardware and the toddler rail included, a few teething marks on the top rail. Mattress not included.", "asking_price": { "amount": 90, "currency": "USD" }, "country": "US" } } ] } }, { "name": "enrich_product", "title": "Start research on a product now", "operational": true, "description": "Starts research on one product RoboTrunk lists that has no checked facts yet, now, so the facts can be read in a few minutes. The first call starts it and answers started straight away, with an estimate of when it will be done once enough recent runs exist; it never waits for the research. Call this tool again with the same merchant and product_id at any time to see where it is up to: running (started at, expected by) or done. When it is done the checked facts, each with its source, are in check_product and on the product's page. Use it for a listed product that check_product or get_product shows with no checked facts: its sourced findings can help the person choose. A product that already has checked facts answers done and starts nothing, and a repeat call never starts a second research. Not for browsing; use search_catalog. Error recovery: INVALID_REQUEST names the field to fix; PRODUCT_NOT_FOUND means RoboTrunk does not list it, so call search_catalog; RESEARCH_KEY_LIMIT, RESEARCH_ADDRESS_LIMIT and RESEARCH_BUSY say how long to wait, then call again; RESEARCH_DAILY_LIMIT means no more can be started today, so carry on with check_product and say there are no checked facts; RESEARCH_PAUSED or RESEARCH_UNAVAILABLE means research is not running right now, so carry on without it and try again later; a failed answer carries RESEARCH_FAILED, RESEARCH_TIMED_OUT, RESEARCH_INTERRUPTED or RESEARCH_NOT_STARTED, so call again once to start it afresh; ENRICH_FAILED (or any other unexpected error): retry once, then call submit_feedback. Next: check_product to read the findings, then create_checkout. Full guide: get_tool_guide or /agent/tools.json#enrich_product Example call: {\"merchant\":\"anbbaby-com\",\"product_id\":\"gid://shopify/Product/1234567890\"}", "inputSchema": { "type": "object", "properties": { "merchant": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "The store slug, as search_catalog or get_product returned it." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The product_id, as search_catalog or get_product returned it, or its bare numeric Shopify id. Example: \"gid://shopify/Product/1234567890\" or \"1234567890\", never a page link." }, "shopping_session_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "Optional server-issued shopping session correlation ID. It is not purchase authority." } }, "required": [ "merchant", "product_id" ], "additionalProperties": false }, "annotations": { "title": "Start research on a product now", "readOnlyHint": false, "untrustedContentHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "guide": { "summary": "Starts the research RoboTrunk does on a product (the maker's manual, independent reviews, video review transcripts and the store's own page, each fact checked against its source) for one listed product that has none yet, then reports where it is up to when called again.", "use_when": "It is for a product the person is considering that `check_product` or `get_product` shows with no checked facts; its findings (specifications, how it holds up, what reviewers report) can change what you tell the person. The research can start as soon as you know the product; the conversation carries on while it runs, and a later call collects the answer.", "do_not_use": "Do not use this for a product that already has checked facts: it answers `done` and starts nothing. Do not use it to find products; use `search_catalog`. Do not call it again and again to wait: one call a minute or two apart is enough, and each answer says when to look next.", "parameters": "`merchant` is the store slug and `product_id` the product's id, both exactly as `search_catalog` or `get_product` returned them (the bare numeric Shopify id also works). Call again with the same two values to see where the research is up to.", "caveats": "The research runs in the background and usually takes a few minutes; this call never waits for it. `expected_by` and \"about N minutes\" appear only once at least five recent runs at the same depth have been measured, so the first calls may carry no estimate. A product with nothing that can be checked and published answers `done` with `outcome: no_publishable_facts`; that is not a fault. Each key and each address may start only so many researches an hour, and RoboTrunk starts only so many a day. A repeat call, a call on a product already being researched and a call on a researched product start nothing and use no allowance. Research is switched off while RoboTrunk pauses supply and enrichment; the answer then says so.", "outputs": "`status` is `started`, `running`, `done` or `failed`; a refusal is `error` with its code. `resource` carries `state`, `merchant`, `product_id` and, while it runs, `started_at`, `expected_by` (or null) and `estimate_minutes` (or null). On `done`, `resource.outcome` is `published`, `already_researched` or `no_publishable_facts`, with `fact_count`, `checked_at` and `evidence_url` when there are facts. On `failed`, `resource.failure_code` names why. `check_product` also says `research in progress, started