Quote a shipment
quote_shipmentQuote a shipment: create a quotation with carrier rates for an origin, a destination and parcel(s). It buys nothing. Each call creates a quotation record, except that an identical request from the same user within 10 minutes returns the earlier one with mcp_repeat; asked for another quote with nothing new, ask in one question what changes (origin, destination, parcel, carrier) instead of resending the same payload.
Send address_from, address_to and either parcel or parcels. A postal_code per address is enough: estado, municipio and colonia are filled from the CP catalog and reported in mcp_autofilled, so do not ask for the colonia; mention the one picked. To insure the goods (SOS Protección), set package_protected and declared_value on the parcel and report the priced mcp_protection.protection_total as-is, never a computed percentage. order_id quotes an existing order; constraints / objective add mcp_ranking.
Rates price asynchronously: while mcp_next_step.status is pending, poll get_quotation with the id. Missing address data answers status: "needs_input" naming the fields to ask for.
Each rate carries pickup (the carrier collects at the origin), pickup_automatic and pickup_ocurre (drop-off at a branch): answer pickup questions from them. Entrega en sucursal / ocurre (the recipient collects at a carrier branch) is a purchase option of the rates whose office_delivery is true: mcp_office lists them and how to buy that way (list_office_points, then create_shipment with office_delivery). Offer it when the user mentions sucursal, ocurre or branch pickup; a rate with office_delivery_only is sold only that way.
Only after the user picks a rate, buy it with create_shipment (that rate's id as rate_id); protect_shipment is for a label already bought.
Returns the quotation with rates[] and mcp_* keys (mcp_office among them), or the needs_input payload.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "quote_shipment"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait server-side for carrier prices before returning (default true). Set false to return the raw pending quotation immediately. | |
| parcel | No | Single parcel (cm/kg) | |
| parcels | No | Multiple parcels (alternative to `parcel`) | |
| order_id | No | Optional. Id of an existing order of this account to quote instead of inline addresses (from list_orders, get_order or create_order in this conversation). Never pass a shipment or quotation id. | |
| products | No | Line items, needed for customs on international routes. Ignored when `parcels` is sent: put them in the first parcel's `products` instead. | |
| objective | No | How to rank eligible rates (default balanced). Adds `mcp_ranking` to the result. | |
| address_to | No | Destination = who receives (destinatario/cliente). Same keys as address_from. In a return (devolución), the customer becomes address_from and the merchant address_to. | |
| overweight | No | Marks the quotation as an overweight re-quote (no quotation webhook, rates priced for the whole quotation, not per package). Leave unset for a normal quote; false is the default. | |
| constraints | No | Structured requirements to rank rates against. Rates that violate any are moved to `mcp_ranking.unmet_constraints`. | |
| address_from | No | Origin = who sends (remitente/bodega del merchant). Never swap with address_to: 'mándale X a Juan' means Juan is address_to, not address_from. Map the user's words to these exact keys: estado→area_level1, municipio/alcaldía→area_level2, colonia→area_level3. | |
| items_quantity | No | Store-integration quotes only: number of items, packed into boxes from the connected store's package settings in place of `parcel`/`parcels`. Ignored without a connected store. | |
| declared_amount | No | Amount to COLLECT on delivery (cash on delivery). NOT the insured value: insure with the parcel's `package_protected` + `declared_value`. | |
| timeout_seconds | No | Max seconds to wait for prices when wait=true (default 20, capped at 30). | |
| cash_on_delivery | No | Quote cash on delivery: the carrier collects `declared_amount` from the recipient. The purchase keeps what is set here. | |
| requested_carriers | No | Restrict to these carrier names | |
| poll_interval_seconds | No | Seconds between internal polls when wait=true (default 2). | |
| recipient_pays_shipping | No | With cash_on_delivery, adds the shipping cost to the amount collected from the recipient |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Quotation id: pass it to get_quotation | |
| rates | No | One entry per carrier service | |
| reason | No | needs_input only: address_fields_absent | |
| status | No | needs_input when address fields are missing (no quotation made) | |
| message | No | needs_input only: what went wrong | |
| missing | No | needs_input only: missing fields per address | |
| order_id | No | Order quoted, when order_id was given | |
| packages | No | Parcels as quoted | |
| provided | No | needs_input only: the addresses as received | |
| field_help | No | needs_input only: what each missing field means | |
| mcp_repeat | No | quote_shipment only: present when an identical request from the same user within 10 minutes returned the earlier quotation | |
| mcp_ranking | No | Present only when constraints or objective were given | |
| is_completed | No | True once no rate is pending | |
| mcp_next_step | No | Server-added hint naming the next tool to call; absent when there is no next step | |
| how_to_resolve | No | needs_input only: how to obtain the missing values | |
| mcp_autofilled | No | Address fields completed from the postal code catalog, per address_from / address_to ({ filled, alternatives }); absent when nothing was filled | |
| mcp_protection | No | quote_shipment only: the protection priced in this quotation | |
| quotation_scope | No | national or international | |
| ambiguous_fields | No | needs_input only | |
| field_provenance | No | needs_input only: low-confidence fields to confirm | |
| retry_instruction | No | needs_input only: when to call quote_shipment again | |
| suggested_question | No | needs_input only: question to relay to the user |