All-in DDP quotes for China to USA shipments, 100 g to 2,000 kg, from a live rate card
Scored across 5 tools
Each tool targets a distinct step in the freight workflow: goods eligibility (check_goods), rough estimate (estimate_price), real offer (generate_offer), offer status (check_offer_status), and shipment tracking (track_shipment). Overlaps are minimal and descriptions clearly delineate side effects and inputs.
All tools use snake_case with a consistent verb_noun structure (check_goods, estimate_price, generate_offer, track_shipment), and check_offer_status follows the same pattern with a compound object. No mixing of conventions.
Five tools appropriately cover the core operations for a freight quote and tracking service, with each tool serving a unique purpose. The count is well within the typical 3-15 range and no tool feels redundant.
The surface covers goods screening, pricing, offer retrieval, and tracking, but lacks a tool to create or manage a booking; the descriptions indicate booking and changes are handled via email. This is a minor gap that agents can work around by directing users to the email channel.
Checks whether Plain Freight can ship a product from China to the US, and which documents it needs. Records nothing. Input: the product description. Returns a verdict: instant_offer or branded_rate (priced at once, each on its applicable rate) or person_checks_first (for example batteries, chemicals, food, cosmetics, seeds, vapes or weapons: a person reviews the goods before any price), with a plain explanation and the documents or details to have ready. It applies the same goods screen as Plain Freight's offers; it is not legal or customs advice.
| Name | Required | Description | Default |
|---|---|---|---|
| product | Yes | The product, in the user's words (materials and whether it has a battery help) |
| Name | Required | Description |
|---|---|---|
| error | No | |
| verdict | No | instant_offer: priced at once; branded_rate: priced at once on its applicable rate; person_checks_first: no price until a person reviews the goods |
| category | No | |
| next_step | No | |
| have_ready | No | Documents or details the person will ask for |
| explanation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent and non-destructive behavior, but the description adds real value: it explains the three possible verdicts, notes that person_checks_first triggers human review before any price, and clarifies no record is written and it is not legal/customs advice. It stops short of timing or failure behavior, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core verdict, then the outcome taxonomy, then scope caveats; each sentence earns its place. The verdict parenthetical is dense but informative, with only minor overlap between 'Records nothing' and the closing scope note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though an output schema exists and return values needn't be restated, the description covers scope, side effects, possible outcomes and the non-advice disclaimer, leaving nothing an agent needs to decide whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the description only restates 'Input: the product description,' adding no format or syntactic detail beyond the schema's own hint about materials and batteries. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (checks whether goods can be shipped) plus the precise scope (China to US) and explicitly says it 'Records nothing,' which distinguishes it from the offer-generating sibling tools. An agent can tell this is a pre-shipment eligibility screen 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage by noting it 'applies the same goods screen as Plain Freight's offers,' which suggests calling it before generate_offer, but it never says when to use this versus estimate_price or generate_offer, nor any exclusions. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the result of the second check on a Plain Freight offer, by the offer's quote_id. Read-only. Returns settled (true once the check finished), possibly updated options and summary, follow-up questions whose answers change the price or customs channel, the offer email status, and needs_review. When needs_review is true, prices are withheld until a person at Plain Freight reviews the goods (for example batteries, food or chemicals), and Plain Freight follows up by email.
| Name | Required | Description | Default |
|---|---|---|---|
| quote_id | Yes | The quote_id of a Plain Freight offer (a UUID) |
| Name | Required | Description |
|---|---|---|
| text | No | |
| No | Offer email status: sent, queued, deferred, skipped or failed | |
| error | No | |
| options | No | |
| settled | No | |
| quote_id | No | |
| questions | No | |
| needs_review | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the 'settled' flag flips true only once the check finishes, prices are withheld when needs_review is true (batteries, food, chemicals), and follow-up happens by email. These are workflow behaviors the agent could not infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph, front-loaded with purpose and read-only status, then the return semantics. Sentences are information-dense with no filler, though the enumeration of return fields is somewhat list-like. Slightly long but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not detail return shapes, yet it still explains the meaning of settled and needs_review and the withheld-price path. Annotations cover safety. Combined with a single well-documented required param, this is close to complete; only explicit usage/preconditions are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (quote_id) with 100% schema description coverage stating it is a UUID of a Plain Freight offer. The description repeats 'by the offer's quote_id' without adding format, sourcing, or error semantics. Baseline 3 applies when the schema carries the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource + scope: 'Reads the result of the second check on a Plain Freight offer, by the offer's quote_id.' It clearly identifies which stage of the offer lifecycle this covers, distinguishing it from siblings like generate_offer and estimate_price. An agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (poll the second check's result, keyed by quote_id) but never stated explicitly, and no alternative or precondition is named. It does not say, for example, that this should be called after generate_offer, or what to do before an offer exists. Adequate but with clear gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rough price estimate for shipping goods from China to a US address, 100 g to 2,000 kg. Records nothing, contacts no one and needs no email. Inputs: total weight, and optionally the product and carton sizes or total volume. Returns estimated door to door prices in USD for air (and sea from 10 kg chargeable weight), the chargeable weight used (the greater of actual weight and carton volume in cm3 / 6,000), transit estimates, and whether US import duty is included. Figures come from Plain Freight's pricing engine for densely packed goods, priced on the applicable rate; goods that need a review get no figure. The exact ZIP code, pickup city and cartons can move the price, so the result is an estimate, not an offer.
| Name | Required | Description | Default |
|---|---|---|---|
| product | No | What is being shipped, in a few words (sets the goods rate) | |
| total_cbm | No | Total volume in cubic meters, if known instead of carton sizes | |
| weight_kg | Yes | Total actual weight of the shipment in kg | |
| carton_count | No | Number of cartons of that size | |
| carton_width_cm | No | One carton's width in cm | |
| carton_height_cm | No | One carton's height in cm | |
| carton_length_cm | No | One carton's length in cm |
| Name | Required | Description |
|---|---|---|
| error | No | |
| goods | No | |
| options | No | |
| estimate | No | Always true: a rough figure, not an offer |
| actual_kg | No | |
| next_step | No | |
| priced_as | No | |
| priced_on | No | Date the pricing engine produced these figures |
| chargeable_kg | No | |
| volumetric_kg | No |
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional. The name to address the offer email to | |
| 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 |
| 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 |
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.
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.
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.
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.
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.
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.
Reads a booked Plain Freight shipment from its tracking link. Input: the tracking link from the booking email (https://plainfreight.com/track/) or the bare token; the token is the credential, so only someone the customer shared the link with can read the record. Returns the shipment reference, the current stage on the 10-stage lifecycle (Booking through Delivered), shipment details and the dated event log. Read-only; changes to a booking go by email to info@plainfreight.com with the shipment reference.
| Name | Required | Description | Default |
|---|---|---|---|
| tracking_link | Yes | The tracking URL from the booking email (https://plainfreight.com/track/<token>), or the token by itself |
| Name | Required | Description |
|---|---|---|
| error | No | |
| goods | No | |
| stage | No | e.g. '7 of 10'; null when cancelled |
| events | No | |
| status | No | |
| carrier | No | Shown only once the invoice is paid |
| contact | No | |
| lifecycle | No | |
| reference | No | |
| weight_kg | No | |
| record_url | No | |
| updated_at | No | |
| origin_city | No | |
| status_label | No | |
| tracking_number | No | Shown only once the invoice is paid |
| destination_city | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavioral context by explaining that the token itself is the credential (access is limited to whoever holds the link) and that booking changes must go via email. It does repeat the read-only claim, which is redundant with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with purpose and input, then output, then the mutation caveat. Every sentence carries information, though listing the returned fields partially duplicates the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: input form, access semantics, and the escalation path for changes. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter's format (full URL or bare token) is already documented in the schema. The description adds the meaningful nuance that the token is the credential, but the schema does the substantive documentation work, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (reads/retrieves) and resource (a booked Plain Freight shipment via its tracking link), plus the exact scope of what's returned (reference, lifecycle stage, details, event log). It is clearly distinguishable from siblings like check_offer_status or estimate_price, which operate on offers/pricing rather than an existing shipment record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage context: the tool is for an already-booked shipment and the input comes from the booking email tracking link. It also names the alternative channel for mutations (email info@ with the reference), which implicitly tells the agent this tool is read-only and not the path for changes. It stops short of explicitly contrasting with the sibling lookup tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_goods1 field changedOutput schema / properties / verdict / descriptionPrevious value: -"instant_offer: priced at once; branded_rate: priced at once on the higher branded rate; person_checks_first: no price until a person reviews the goods"New value: +"instant_offer: priced at once; branded_rate: priced at once on its applicable rate; person_checks_first: no price until a person reviews the goods"check_offer_status1 field changedInput schema / properties / quote_id / descriptionPrevious value: -"The quote_id returned by generate_offer"New value: +"The quote_id of a Plain Freight offer (a UUID)"estimate_price1 field changedOutput schema / properties / goods / properties / verdict / descriptionPrevious value: -"instant_offer: priced at once; branded_rate: priced at once on the higher branded rate; person_checks_first: no price until a person reviews the goods"New value: +"instant_offer: priced at once; branded_rate: priced at once on its applicable rate; person_checks_first: no price until a person reviews the goods"generate_offer2 fields changedInput schema / properties / email / descriptionPrevious 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."Output schema / properties / quote_id / descriptionPrevious value: -"Reference for check_offer_status and for booking"New value: +"Reference for the offer's second check and for booking"check_goodsestimate_pricegenerate_offer1 field changedOutput schema / properties / shipment / properties / chargeable_kgAdded value: +{
+ "description": "weight the price is computed on: the greater of actual and volumetric weight",
+ "type": "number"
+}check_offer_status1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "email": {
+ "description": "Offer email status: sent, queued, deferred, skipped or failed",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "needs_review": {
+ "type": "boolean"
+ },
+ "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": {
+ "type": "string"
+ },
+ "settled": {
+ "type": "boolean"
+ },
+ "text": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}generate_offer7 fields changedInput schema / properties / companyRemoved value: -{
- "description": "Customer company",
- "type": "string"
-}Input schema / properties / destination_zip / descriptionPrevious value: -"US destination ZIP code"New value: +"US destination ZIP code of the shipment"Input schema / properties / email / descriptionPrevious 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."Input schema / properties / name / descriptionPrevious value: -"Customer name"New value: +"Optional. The name to address the offer email to"Input schema / properties / notes / descriptionPrevious value: -"HS code, FBA requirements, delivery constraints, certifications held"New value: +"Optional shipment facts: HS code, Amazon FBA requirements, delivery constraints, certifications held"Input schema / properties / origin / descriptionPrevious value: -"Pickup city or supplier in China"New value: +"Pickup city or supplier's city in China"Output 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"
+}track_shipment1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "carrier": {
+ "description": "Shown only once the invoice is paid",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "contact": {
+ "type": "string"
+ },
+ "destination_city": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "events": {
+ "items": {
+ "properties": {
+ "customer_note": {
+ "type": "string"
+ },
+ "happened_at": {
+ "type": "string"
+ },
+ "status": {
+ "description": "Lifecycle status the event belongs to",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "goods": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "lifecycle": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "origin_city": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "record_url": {
+ "type": "string"
+ },
+ "reference": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "stage": {
+ "description": "e.g. '7 of 10'; null when cancelled",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ },
+ "status_label": {
+ "type": "string"
+ },
+ "tracking_number": {
+ "description": "Shown only once the invoice is paid",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "type": "string"
+ },
+ "weight_kg": {
+ "type": [
+ "number",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}check_offer_statusgenerate_offertrack_shipmentBefore-payment check for China quotes to US/EU: costs, low-value rules, and compliance blockers.
Live USPS, UPS, FedEx and DHL rates from the US: domestic, Canada, UK, Germany, Australia. No scale.
Compare carrier rates and buy US shipping labels, QR return labels, pickups and tracking.
Compare rates, manage orders, buy labels, schedule pickups, and report on shipping.
Add one secure layer between your agents and this server.