Plain Freight

Quote a China to USA shipment

generate_offer

Destructive

Prices a real shipment from China to a US address, 100 g to 2,000 kg, on Plain Freight's live pricing engine. Returns door to door prices in USD: each option covers freight, US customs clearance and delivery, and says whether US import duty is included (DDP) or paid at import. Carton dimensions affect the price: for light, bulky cargo the volumetric weight sets it. Side effects: each call records a separate quote request with Plain Freight, and if an email is given the written offer is emailed to that address once a second check settles (at most one offer email per address per day). Nothing is booked or charged. The result carries a quote_id, by which the second check's verdict can be read.

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": {
      "product": "<product>",
      "weight_kg": "<weight_kg>"
    },
    "name": "generate_offer"
  }
}

Input Schema

Name	Required	Description
`name`	No	Optional. The name to address the offer email to
`email`	No	Optional. Address the written offer is mailed to; replying to that email is one way to book.
`notes`	No	Optional shipment facts: HS code, Amazon FBA requirements, delivery constraints, certifications held
`origin`	No	Pickup city or supplier's city in China
`product`	Yes	What is being shipped, e.g. 'LED desk lamps, 500 units'
`urgency`	No
`weight_kg`	Yes	Total weight in kg (0.1 to 2000)
`dimensions`	No	Cartons and size, e.g. '4 cartons, 60x40x35 cm each'
`destination_zip`	No	US destination ZIP code of the shipment

Output Schema

Name	Required	Description
`error`	No
`contact`	No
`options`	No
`summary`	No
`book_url`	No	plainfreight.com booking form, prefilled with this shipment and quote
`quote_id`	No	Reference for the offer's second check and for booking
`shipment`	No
`next_step`	No
`questions`	No
`valid_days`	No
`agent_review`	No
`needs_review`	No	true: prices withheld until a person clears the goods

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 27, 2026

changedInput schema / properties / email / description

Previous value: -"Optional. Only if the user wants the written offer by email: it is mailed to this address, and replying to it is how they book."New value: +"Optional. Address the written offer is mailed to; replying to that email is one way to book."

changedOutput schema / properties / quote_id / description

Previous value: -"Reference for check_offer_status and for booking"New value: +"Reference for the offer's second check and for booking"

Changed1 schema field changedSep 27, 2026

addedOutput schema / properties / shipment / properties / chargeable_kg

Added value: +{
+  "description": "weight the price is computed on: the greater of actual and volumetric weight",
+  "type": "number"
+}

Changed7 schema fields changedSep 27, 2026

removedInput schema / properties / company

Removed value: -{
-  "description": "Customer company",
-  "type": "string"
-}

changedInput schema / properties / destination_zip / description

Previous value: -"US destination ZIP code"New value: +"US destination ZIP code of the shipment"

changedInput schema / properties / email / description

Previous value: -"The user's email. The written offer is mailed there once the check settles (one offer email per address per day), and replying to it is how they book. Optional, but without it no one can follow up."New value: +"Optional. Only if the user wants the written offer by email: it is mailed to this address, and replying to it is how they book."

changedInput schema / properties / name / description

Previous value: -"Customer name"New value: +"Optional. The name to address the offer email to"

changedInput schema / properties / notes / description

Previous value: -"HS code, FBA requirements, delivery constraints, certifications held"New value: +"Optional shipment facts: HS code, Amazon FBA requirements, delivery constraints, certifications held"

changedInput schema / properties / origin / description

Previous value: -"Pickup city or supplier in China"New value: +"Pickup city or supplier's city in China"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "agent_review": {
+      "enum": [
+        "pending",
+        "not_running"
+      ],
+      "type": "string"
+    },
+    "book_url": {
+      "description": "plainfreight.com booking form, prefilled with this shipment and quote",
+      "type": "string"
+    },
+    "contact": {
+      "type": "string"
+    },
+    "error": {
+      "type": "string"
+    },
+    "needs_review": {
+      "description": "true: prices withheld until a person clears the goods",
+      "type": "boolean"
+    },
+    "next_step": {
+      "type": "string"
+    },
+    "options": {
+      "items": {
+        "properties": {
+          "duties_included": {
+            "description": "true when US import duty is inside the price (DDP); false when duty is paid to the government at import",
+            "type": "boolean"
+          },
+          "firm": {
+            "description": "false means an estimate confirmed before booking",
+            "type": "boolean"
+          },
+          "includes": {
+            "description": "Exactly what this price covers",
+            "type": "string"
+          },
+          "key": {
+            "description": "air, sea or express",
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "price": {
+            "description": "Price in USD for the whole shipment",
+            "type": "number"
+          },
+          "transit": {
+            "description": "Door to door transit estimate",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "questions": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "quote_id": {
+      "description": "Reference for check_offer_status and for booking",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "shipment": {
+      "properties": {
+        "destination_zip": {
+          "type": "string"
+        },
+        "dimensions": {
+          "type": "string"
+        },
+        "product": {
+          "type": "string"
+        },
+        "weight_kg": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "summary": {
+      "type": "string"
+    },
+    "valid_days": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

First observedSep 15, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already flag non-read-only, destructive, non-idempotent, open-world behavior, but the description adds rich detail: each call records a quote request, sends a written offer email after a second check with a one-per-day per-address cap, nothing is booked or charged, and the result carries a quote_id for status checks. This goes well beyond what annotations provide.

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?

Front-loads purpose, returns, parameter effects, and side effects in a compact paragraph. Every sentence contributes useful context, though the return phrasing is slightly repetitive with the purpose statement.

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?

Complete for a complex mutation tool with an output schema: it covers side effects, email behavior, daily cap, no booking/charge, and how quote_id links to check_offer_status. An agent has all needed context without needing return-value explanations in the description.

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 89%, so the baseline is met. The description further explains that carton dimensions affect pricing via volumetric weight and that supplying an email triggers an offer email with rate limits, adding meaningful semantics beyond the schema text.

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

Purpose4/5

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

States a specific verb ('Prices') and resource ('real shipment from China to a US address') with clear scope and live pricing engine. The phrase 'real shipment' implicitly contrasts with sibling estimate_price, but no sibling is named or explicitly differentiated, so an agent must infer the boundary.

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

Usage Guidelines4/5

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

Provides clear context: use for real China-to-US shipment quotes within 100 g to 2,000 kg, with side effects explained and no booking/charge. It does not explicitly state when to choose estimate_price instead, nor does it name exclusions or prerequisites.

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

All Plain Freight 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.