warp-agent-mcp

Book International (Air / Ocean)

international_book

Destructive

Book an option from international_quote. Requires the option_id the user chose (before its valid_until), full pickup and delivery addresses with company, contact name, phone in international format and email, a pickup window, and the items exactly as quoted (omit items when the quote used containers or volume). For door_to_port and port_to_door options, set port_charges_acknowledged only after the user has accepted that charges at the far port are extra. Customs: collect what you can in customs (hazmat confirmation, commodity lines with Schedule B / HTS / HS code, value, country of origin, tax ids, EEI choice for US exports); anything missing can be added later with international_customs, and the forwarder follows up for it. The incoterm and direction are set from the route. An international booking cannot be cancelled through the API (cancellations go to Warp support), so only call after the user explicitly confirms this option and price. Payment follows the account (terms, balance or card); if a payment_link comes back, the order is held until the user pays there. Auth required.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "option_id": "<option_id>",
      "pickup": "<pickup>",
      "delivery": "<delivery>"
    },
    "name": "international_book"
  }
}

Input Schema

Name	Required	Description
`items`	No	The items exactly as quoted. Omit when the quote used containers or volume.
`pickup`	Yes	Pickup address and contact (the shipper)
`customs`	No	Customs data. Send what the user has; the rest can follow with international_customs.
`delivery`	Yes	Delivery address and contact (the consignee)
`option_id`	Yes	option_id the user chose, from your MOST RECENT international_quote
`international_info`	No	Advanced: raw fields in gw's internationalInfo shape, merged over customs
`port_charges_acknowledged`	No	true once the user accepts far-port charges (door_to_port / port_to_door only)

Schema Changelog

Changes observed during successful MCP inspections.

Changed58 schema fields changedOct 30, 2026

addedInput schema / properties / customs

Added value: +{
+  "additionalProperties": false,
+  "description": "Customs data. Send what the user has; the rest can follow with international_customs.",
+  "properties": {
+    "commodities": {
+      "description": "One line per kind of goods. A line with description, code, country of origin, value, quantity and weight is complete; anything missing is collected by the forwarder after booking.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "country_of_origin": {
+            "description": "Where the goods were made, ISO alpha-2",
+            "pattern": "^[A-Za-z]{2}$",
+            "type": "string"
+          },
+          "description": {
+            "description": "Plain description of the goods",
+            "type": "string"
+          },
+          "eccn": {
+            "description": "US exports: ECCN; leave empty for EAR99 goods",
+            "type": "string"
+          },
+          "hs_code": {
+            "description": "No US end (between two other countries): 6-10 digit HS code",
+            "type": "string"
+          },
+          "hts_code": {
+            "description": "US imports: 10-digit HTS code",
+            "type": "string"
+          },
+          "license_type": {
+            "description": "US exports: license type or exception, e.g. NLR",
+            "type": "string"
+          },
+          "quantity": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "schedule_b": {
+            "description": "US exports: 10-digit Schedule B code",
+            "type": "string"
+          },
+          "value_usd": {
+            "description": "Total value of this line, USD",
+            "minimum": 0,
+            "type": "number"
+          },
+          "weight_lbs": {
+            "description": "Total weight of this line, lb",
+            "exclusiveMinimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "description"
+        ],
+        "type": "object"
+      },
+      "maxItems": 50,
+      "type": "array"
+    },
+    "consignee_tax_id": {
+      "description": "Consignee tax id in its country's format",
+      "type": "string"
+    },
+    "customs_bond": {
+      "description": "US imports: customs bond number",
+      "type": "string"
+    },
+    "ear99_no_license": {
+      "description": "US exports: every item is EAR99 and needs no export license",
+      "type": "boolean"
+    },
+    "eei_authorization": {
+      "description": "US exports: the shipper authorizes the forwarder to file the EEI in AES. Needed when any one Schedule B line is over $2,500 or a license is required, unless an ITN is given.",
+      "type": "boolean"
+    },
+    "exporter_of_record": {
+      "additionalProperties": false,
+      "description": "Only when someone other than the shipper is the exporter of record",
+      "properties": {
+        "city": {
+          "type": "string"
+        },
+        "contact_name": {
+          "type": "string"
+        },
+        "country": {
+          "pattern": "^[A-Za-z]{2}$",
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "name": {
+          "description": "Company name, Latin characters",
+          "type": "string"
+        },
+        "phone": {
+          "description": "International format, e.g. +862150000000",
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "street": {
+          "type": "string"
+        },
+        "street2": {
+          "type": "string"
+        },
+        "tax_id": {
+          "description": "Tax id in the party's country format (US: EIN)",
+          "type": "string"
+        },
+        "zipcode": {
+          "description": "Required where the country uses postal codes",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "street",
+        "city",
+        "country",
+        "contact_name",
+        "phone"
+      ],
+      "type": "object"
+    },
+    "importer_of_record": {
+      "additionalProperties": false,
+      "description": "Only when someone other than the consignee is the importer of record (e.g. the seller or a broker clears import)",
+      "properties": {
+        "city": {
+          "type": "string"
+        },
+        "contact_name": {
+          "type": "string"
+        },
+        "country": {
+          "pattern": "^[A-Za-z]{2}$",
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "name": {
+          "description": "Company name, Latin characters",
+          "type": "string"
+        },
+        "phone": {
+          "description": "International format, e.g. +862150000000",
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "street": {
+          "type": "string"
+        },
+        "street2": {
+          "type": "string"
+        },
+        "tax_id": {
+          "description": "Tax id in the party's country format (US: EIN)",
+          "type": "string"
+        },
+        "zipcode": {
+          "description": "Required where the country uses postal codes",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "street",
+        "city",
+        "country",
+        "contact_name",
+        "phone"
+      ],
+      "type": "object"
+    },
+    "importer_of_record_number": {
+      "description": "US imports: the consignee's importer of record number (EIN or CBP number YYDDPP-NNNNN)",
+      "type": "string"
+    },
+    "importer_registration_number": {
+      "description": "Destination importer registration: Brazil CNPJ (14 digits) or CPF (11), Colombia NIT, Argentina CUIT (11 digits), Nigeria Form M (MF + 8-12 digits)",
+      "type": "string"
+    },
+    "isf": {
+      "additionalProperties": false,
+      "description": "Ocean imports into the US only: Importer Security Filing (10+2) parties. The forwarder files it with the customer after booking; country of origin and HTS come from commodities.",
+      "properties": {
+        "buyer": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        },
+        "consignee_number": {
+          "type": "string"
+        },
+        "consolidator": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        },
+        "container_stuffing_location": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        },
+        "importer_of_record_number": {
+          "type": "string"
+        },
+        "manufacturer": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        },
+        "seller": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        },
+        "ship_to": {
+          "additionalProperties": false,
+          "properties": {
+            "address": {
+              "description": "One-line address",
+              "type": "string"
+            },
+            "country": {
+              "pattern": "^[A-Za-z]{2}$",
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name",
+            "address",
+            "country"
+          ],
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "itn": {
+      "description": "US exports: the ITN, when the shipper files the EEI itself",
+      "type": "string"
+    },
+    "no_hazmat": {
+      "description": "The shipper confirms nothing is hazardous: no batteries (also inside devices), aerosols, perfume or paint. Ask the user; without it the forwarder asks before moving the freight.",
+      "type": "boolean"
+    },
+    "shipper_tax_id": {
+      "description": "Shipper tax id. US exports: the EIN (9 digits); if omitted, the EIN on the account's customs profile is used.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / delivery / description

Previous value: -"Delivery address and contact"New value: +"Delivery address and contact (the consignee)"

removedInput schema / properties / delivery / properties / city / $ref
```
Removed value: -"#/properties/pickup/properties/city"
```
addedInput schema / properties / delivery / properties / city / description
```
Added value: +"City"
```
addedInput schema / properties / delivery / properties / city / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / company / $ref
```
Removed value: -"#/properties/pickup/properties/company"
```
addedInput schema / properties / delivery / properties / company / description
```
Added value: +"Company / location name"
```
addedInput schema / properties / delivery / properties / company / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / contact_name / $ref
```
Removed value: -"#/properties/pickup/properties/contact_name"
```
addedInput schema / properties / delivery / properties / contact_name / description
```
Added value: +"Contact full name"
```
addedInput schema / properties / delivery / properties / contact_name / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / country / $ref
```
Removed value: -"#/properties/pickup/properties/country"
```
addedInput schema / properties / delivery / properties / country / description
```
Added value: +"ISO alpha-2 country code; must match the quote"
```
addedInput schema / properties / delivery / properties / country / pattern
```
Added value: +"^[A-Za-z]{2}$"
```
addedInput schema / properties / delivery / properties / country / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / email / $ref
```
Removed value: -"#/properties/pickup/properties/email"
```
addedInput schema / properties / delivery / properties / email / description
```
Added value: +"Contact email"
```
addedInput schema / properties / delivery / properties / email / type
```
Added value: +"string"
```

addedInput schema / properties / delivery / properties / instructions

Added value: +{
+  "description": "Dock, access or appointment notes for the driver",
+  "type": "string"
+}

removedInput schema / properties / delivery / properties / latitude / $ref
```
Removed value: -"#/properties/pickup/properties/latitude"
```
addedInput schema / properties / delivery / properties / latitude / type
```
Added value: +"number"
```
removedInput schema / properties / delivery / properties / longitude / $ref
```
Removed value: -"#/properties/pickup/properties/longitude"
```
addedInput schema / properties / delivery / properties / longitude / type
```
Added value: +"number"
```
removedInput schema / properties / delivery / properties / phone / $ref
```
Removed value: -"#/properties/pickup/properties/phone"
```
addedInput schema / properties / delivery / properties / phone / description
```
Added value: +"Contact phone with country code, e.g. +862150000000"
```
addedInput schema / properties / delivery / properties / phone / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / ref_nums / $ref
```
Removed value: -"#/properties/pickup/properties/ref_nums"
```

addedInput schema / properties / delivery / properties / ref_nums / description

Added value: +"References for this stop (PO, SO, the customer's billing reference)"

addedInput schema / properties / delivery / properties / ref_nums / items
```
Added value: +{
+  "type": "string"
+}
```
addedInput schema / properties / delivery / properties / ref_nums / type
```
Added value: +"array"
```
removedInput schema / properties / delivery / properties / state / $ref
```
Removed value: -"#/properties/pickup/properties/state"
```

addedInput schema / properties / delivery / properties / state / description

Added value: +"2-letter state / province code in the US and Canada; region or province name elsewhere"

addedInput schema / properties / delivery / properties / state / type
```
Added value: +"string"
```
removedInput schema / properties / delivery / properties / street / $ref
```
Removed value: -"#/properties/pickup/properties/street"
```
addedInput schema / properties / delivery / properties / street / description
```
Added value: +"Street address"
```
addedInput schema / properties / delivery / properties / street / type
```
Added value: +"string"
```

addedInput schema / properties / delivery / properties / street2

Added value: +{
+  "description": "Suite / unit / building",
+  "type": "string"
+}

removedInput schema / properties / delivery / properties / window / $ref
```
Removed value: -"#/properties/pickup/properties/window"
```
addedInput schema / properties / delivery / properties / window / additionalProperties
```
Added value: +false
```

addedInput schema / properties / delivery / properties / window / description

Added value: +"Time window as ISO 8601 UTC timestamps. Pickup: when the freight is ready. Delivery: indicative only for international."

addedInput schema / properties / delivery / properties / window / properties

Added value: +{
+  "from": {
+    "type": "string"
+  },
+  "to": {
+    "type": "string"
+  }
+}

addedInput schema / properties / delivery / properties / window / required
```
Added value: +[
+  "from",
+  "to"
+]
```
addedInput schema / properties / delivery / properties / window / type
```
Added value: +"object"
```
removedInput schema / properties / delivery / properties / zipcode / $ref
```
Removed value: -"#/properties/pickup/properties/zipcode"
```

addedInput schema / properties / delivery / properties / zipcode / description

Added value: +"Postal code. Required in the US, Canada and countries that use one; must match the quote"

addedInput schema / properties / delivery / properties / zipcode / type
```
Added value: +"string"
```

changedInput schema / properties / delivery / required

Previous value: -[
-  "contact_name",
-  "phone",
-  "street",
-  "city",
-  "country"
-]New value: +[
+  "contact_name",
+  "phone",
+  "street",
+  "city",
+  "state",
+  "country",
+  "window"
+]

changedInput schema / properties / international_info / description

Previous value: -"Optional customs data in gw's internationalInfo shape (incoterm, shipper, consignee, commodities, ...)"New value: +"Advanced: raw fields in gw's internationalInfo shape, merged over customs"

changedInput schema / properties / items / description

Previous value: -"The items exactly as quoted"New value: +"The items exactly as quoted. Omit when the quote used containers or volume."

changedInput schema / properties / pickup / description

Previous value: -"Pickup address and contact"New value: +"Pickup address and contact (the shipper)"

addedInput schema / properties / pickup / properties / instructions

Added value: +{
+  "description": "Dock, access or appointment notes for the driver",
+  "type": "string"
+}

changedInput schema / properties / pickup / properties / ref_nums / description

Previous value: -"References for this stop (PO / SO)"New value: +"References for this stop (PO, SO, the customer's billing reference)"

changedInput schema / properties / pickup / properties / state / description

Previous value: -"State / province / region"New value: +"2-letter state / province code in the US and Canada; region or province name elsewhere"

addedInput schema / properties / pickup / properties / street2

Added value: +{
+  "description": "Suite / unit / building",
+  "type": "string"
+}

changedInput schema / properties / pickup / properties / window / description

Previous value: -"Time window as ISO 8601 UTC timestamps"New value: +"Time window as ISO 8601 UTC timestamps. Pickup: when the freight is ready. Delivery: indicative only for international."

changedInput schema / properties / pickup / properties / zipcode / description

Previous value: -"Postal code; must match the quote"New value: +"Postal code. Required in the US, Canada and countries that use one; must match the quote"

changedInput schema / properties / pickup / required

Previous value: -[
-  "contact_name",
-  "phone",
-  "street",
-  "city",
-  "country"
-]New value: +[
+  "contact_name",
+  "phone",
+  "street",
+  "city",
+  "state",
+  "country",
+  "window"
+]

changedInput schema / required

Previous value: -[
-  "option_id",
-  "pickup",
-  "delivery",
-  "items"
-]New value: +[
+  "option_id",
+  "pickup",
+  "delivery"
+]

AddedOct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The only annotation is destructiveHint=true, so the description must carry behavioral detail and it does: non-cancellable orders requiring explicit confirmation, payment following the account, an order held pending payment_link, far-port charges being extra, and forwarder follow-up on missing customs data. These are non-obvious consequences an agent could not infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core requirement (option_id from international_quote) opens, then conditional rules, then the customs guidance, then the safety warning. Several clauses are long ('before its valid_until') but each carries actionable information; minor tightening possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, deeply nested booking tool with no output schema, the description covers preconditions, conditional flags, customs fallback, payment/held-order outcomes and the irreversibility risk. Little an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: omit items when the quote used containers or volume, the exact required address fields including international phone format, and the gating condition for port_charges_acknowledged. It does not deepen customs sub-fields beyond what the schema already documents, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Book an option from international_quote') and names the upstream tool the option_id comes from. An agent can distinguish this from international_quote, book, parcel_book and batch_book without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit precondition (option_id before valid_until), a hard user-confirmation gate citing that bookings cannot be cancelled via the API, a conditional rule for port_charges_acknowledged on door_to_port/port_to_door, and routes missing customs data to international_customs. When-to-use and when-not-to-use are both covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All warp-agent-mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.