Update to Shippo

{
  "name": "label-purchase",
  "description": "Purchase domestic and international shipping labels, handle customs declarations, return labels, and void/refund labels via the Shippo API",
  "included_files": [
    {
      "relative_path": "shippo/references/address-formats.md",
      "size_in_bytes": 4083
    },
    {
      "relative_path": "shippo/references/carrier-guide.md",
      "size_in_bytes": 5690
    },
    {
      "relative_path": "shippo/references/csv-format.md",
      "size_in_bytes": 5976
    },
    {
      "relative_path": "shippo/references/customs-guide.md",
      "size_in_bytes": 9321
    },
    {
      "relative_path": "shippo/references/error-reference.md",
      "size_in_bytes": 11389
    },
    {
      "relative_path": "shippo/references/international-shipping.md",
      "size_in_bytes": 6910
    },
    {
      "relative_path": "shippo/references/label-formats.md",
      "size_in_bytes": 2825
    },
    {
      "relative_path": "shippo/references/rate-shopping-guide.md",
      "size_in_bytes": 4320
    },
    {
      "relative_path": "shippo/references/response-envelope.md",
      "size_in_bytes": 1184
    },
    {
      "relative_path": "shippo/references/tool-reference.md",
      "size_in_bytes": 15981
    }
  ],
  "skill_md_contents": "---\nname: label-purchase\ndescription: Purchase domestic and international shipping labels, handle customs declarations, return labels, and void/refund labels via the Shippo API\nmetadata:\n  version: \"1.5.2\"\n---\n\n# Label Purchase\n\n## Purchases Are Live\n\nLabel purchases charge the authorized Shippo account for real. **Before purchasing, explicitly state \"this will charge your Shippo account\" with the carrier, service, and cost, and require the user to acknowledge.** Do not purchase without that confirmation.\n\n---\n\n## Purchase Confirmation Gate\n\nBefore every call to `CreateTransaction`, summarize the following and ask the user for explicit confirmation:\n- Carrier and service level\n- Estimated cost\n- Estimated delivery time\n- Origin and destination\n\n**Do not proceed without explicit user confirmation.**\n\n---\n\n## Domestic Label\n\n1. Optionally validate both addresses with `ValidateAddress` (see Address Validation).\n2. Call `CreateShipment` with `address_from`, `address_to` (as inline address objects using v1 field names -- `street1`, `city`, `state`, `zip`, `country`), `parcels`, and `async: false`.\n3. Present rates to the user. Let them choose.\n4. **Confirm purchase** (see Purchase Confirmation Gate above).\n5. Call `CreateTransaction` with: `rate` (selected rate object_id), `label_file_type` (default `PDF_4x6`), `async: false`.\n6. Check response `status`:\n   - `SUCCESS`: return `tracking_number`, `label_url` (display the COMPLETE URL -- S3 signed URLs break if truncated), and `tracking_url_provider`.\n   - `QUEUED`/`WAITING`: poll `GetTransaction` until resolved.\n   - `ERROR`: report messages from the `messages` array.\n\n---\n\n## International Label\n\nAll domestic steps apply, plus customs handling before shipment creation. See `shippo/references/customs-guide.md` for the full customs workflow.\n\n1. Optionally validate addresses with `ValidateAddress`. Sender must include `email` and `phone`. Ask if missing.\n2. Create customs items: call `CreateCustomsItem` per item (description, quantity, net_weight, mass_unit, value_amount, value_currency, origin_country, tariff_number). Alternatively, you can skip this step and pass inline item objects directly in the declaration (step 3).\n3. Create the customs declaration: call `CreateCustomsDeclaration` with contents_type, non_delivery_option, certify: true, certify_signer, and the items (either object_ids from step 2, or inline item objects). See `shippo/references/customs-guide.md` for field details.\n4. Call `CreateShipment` with all standard fields plus `customs_declaration` (the declaration object_id).\n5. Present rates, **confirm purchase** (see Purchase Confirmation Gate), then purchase label and return results as in the domestic flow.\n\n### Contents Type Decision Tree\n\nUse this to determine the correct `contents_type` value:\n\n| Scenario | Value |\n|---|---|\n| Selling to the recipient (commercial sale) | `MERCHANDISE` |\n| Sending a free gift | `GIFT` |\n| Sending a product sample | `SAMPLE` |\n| Paper documents only | `DOCUMENTS` |\n| Customer returning a purchased item | `RETURN_MERCHANDISE` |\n| Charitable donation | `HUMANITARIAN_DONATION` |\n| None of the above | `OTHER` (requires `contents_explanation`) |\n\n### Incoterms Decision Logic\n\nThe `incoterm` field on the customs declaration controls who pays duties and taxes:\n\n- **B2C / e-commerce (default):** Use `DDU` (Delivered Duty Unpaid) -- recipient pays duties at delivery.\n- **Seller prepays duties:** Use `DDP` (Delivered Duty Paid) -- seller covers all duties and taxes.\n- **FedEx/DHL only:** `FCA` (Free Carrier) is available for advanced trade scenarios.\n\nIf the user does not specify, default to `DDU` for standard e-commerce shipments.\n\n---\n\n## Return Labels\n\nTo generate a return label, swap `address_from` and `address_to` so the original recipient becomes the sender and the original sender becomes the recipient. All other steps (shipment creation, rate selection, label purchase) remain the same.\n\n---\n\n## Label Format Options\n\nDefault to `PDF_4x6` unless the user specifies otherwise. Supported formats: `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A5`, `PDF_A6`, `PDF`, `PDF_2.3x7.5`, `PNG`, `PNG_2.3x7.5`, `ZPLII`.\n\n---\n\n## Label Customization Options\n\nWhen purchasing a label via `CreateTransaction`, the following options may be set on the shipment or rate:\n\n- **Signature confirmation**: set `signature_confirmation` on the shipment's `extra` field. Values: `STANDARD`, `ADULT`, `CERTIFIED`, `INDIRECT`, `CARRIER_CONFIRMATION`.\n- **Insurance**: set `insurance` on the shipment's `extra` field with `amount`, `currency`, and `provider`.\n- **Saturday delivery**: set `saturday_delivery` to `true` in the shipment's `extra` field. Only supported by certain carriers and service levels.\n- **Reference fields**: pass `metadata` on the transaction for order numbers or internal references.\n\n---\n\n## Label from Existing Rate\n\nIf the user already has a rate object_id: optionally call `GetRate` to confirm details, then **confirm purchase** (see Purchase Confirmation Gate), then call `CreateTransaction` directly.\n\n---\n\n## Voiding a Label\n\nCall `CreateRefund` with the transaction object_id.\n\n**Refund limitations:** Void/refund eligibility depends on carrier and timing. Not all labels can be refunded after purchase. If `CreateRefund` fails, advise the user to contact Shippo support.\n\n---\n\n## Quick Reference\n\n**Domestic label:**\n(optional) `ValidateAddress` (x2) -> `CreateShipment` (with inline addresses) -> user picks rate -> confirm -> `CreateTransaction`\n\n**International label:**\n(optional) `ValidateAddress` (x2) -> `CreateCustomsItem` (per item) -> `CreateCustomsDeclaration` -> `CreateShipment` (with inline addresses + customs_declaration) -> user picks rate -> confirm -> `CreateTransaction`\n\n**Return label:**\nSame as domestic/international, but swap `address_from` and `address_to`.\n\n**Order-to-label:**\n`CreateOrder` -> `CreateShipment` (using order address/item data) -> user picks rate -> confirm -> `CreateTransaction` -> packing slip (REST fallback, see below)\n\n---\n\n## Orders and Packing Slips\n\nUse orders to represent e-commerce fulfillment requests. An order captures the shipping address, line items, and totals -- then feeds into the standard label purchase workflow.\n\n### Tools\n\n- **`CreateOrder`**: Create an order with line items, shipping address, and order details.\n- **`GetOrder`**: Retrieve an order by its object_id.\n- **`ListOrders`**: List all orders.\n- **Packing slip (known gap):** Generate a packing slip PDF for an order. There is no packing-slip tool in the MCP catalog. The underlying REST endpoint exists at `GET /orders/{ORDER_ID}/packingslip/` (returns a 24-hour S3 PDF link). Fall back to a direct REST call, or advise the user to use the Shippo dashboard until the MCP gap is closed.\n\n### Workflow\n\n1. Call `CreateOrder` with the shipping address, line items (title, quantity, sku, total_price, etc.), and order-level fields.\n2. Use the order's address and item data to call `CreateShipment`, then follow the standard label purchase flow (rate selection, confirmation, `CreateTransaction`).\n3. After purchasing the label, generate a packing slip via the REST fallback (see Tools above for the known MCP gap).\n"
}