All-in DDP quotes for China to USA shipments, 100 g to 2,000 kg, from a live rate card
Scored across 3 tools
Each tool has a distinct role: generate_offer creates a quote, check_offer_status resolves the async review on that quote, and track_shipment reads a booked shipment's tracking record. There is no functional overlap between them.
All tool names follow a clear verb_noun snake_case pattern: generate_offer, check_offer_status, track_shipment. This makes the expected action and target resource predictable.
With three tools, the server is tightly scoped to its apparent domain of freight offer generation and shipment tracking. Each tool covers a necessary stage and none feel superfluous.
The offer workflow (generate then check status) and tracking are covered, and read-only tracking is clearly defined. The only minor gap is that booking and enquiries are intentionally routed to email rather than exposed as a tool.
Poll a generated offer until the async agent check settles. Returns settled (true once the check finished), possibly updated options and summary text, follow-up questions whose answers change the price or customs channel, and needs_review. If needs_review is true the prices are withheld on purpose: the goods look restricted (batteries, food, chemicals) and a human must clear them first. Tell the user Plain Freight will follow up by email; do not present a number. Branded goods are never held; they are priced on the branded channel.
| Name | Required | Description | Default |
|---|---|---|---|
| quote_id | Yes | The quote_id returned by generate_offer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint annotation, detailing the async settlement behavior, the meaning of needs_review, the withholding of prices for restricted goods, the exception for branded goods, and specific user-facing instructions. This is rich behavioral disclosure that an agent needs to correctly handle results. No contradictions 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?
The description is a single paragraph but tightly packed; every sentence serves a purpose, from the polling behavior to the needs_review handling and the branded exception. It is longer than a one-liner but efficient. The core action is front-loaded. Not perfectly concise but not wasteful.
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 tool with no output schema, the description compensates fully: it lists the return fields (settled, options, summary, follow-up questions, needs_review), explains the semantics of the critical flag, and gives explicit action steps. An agent has everything needed to call and interpret the tool correctly.
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% for the sole parameter, and its description already states it's the quote_id from generate_offer. The description reinforces this by saying 'a generated offer' but adds no new semantic detail beyond the schema. Baseline of 3 is appropriate since schema handles it.
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 ('Poll') and resource ('a generated offer') and clearly indicates the async nature and output (settled, needs_review). It distinguishes from generate_offer (creates) and track_shipment (tracks), even though it doesn't name them explicitly. The core purpose is unambiguous.
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?
The description implies when to use it (after generate_offer, using the returned quote_id) and provides clear operational guidance (what to tell the user when needs_review is true). It does not explicitly state 'do not use for tracking' but the context and sibling names make the intended usage clear. No exclusions are stated, but the scenario is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an all-in DDP offer (freight, US customs clearance, duties, and US door delivery in one USD number) for a shipment from China to the USA, 100 g to 2,000 kg. Prices come from Plain Freight's live pricing engine. Provide dimensions when known: for light bulky cargo volumetric weight governs the price. After this returns, an async agent double-checks the shipment; call check_offer_status with the quote_id to pick up its verdict, extra questions, or a needs_review flag.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Customer name | |
| No | 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. | ||
| notes | No | HS code, FBA requirements, delivery constraints, certifications held | |
| origin | No | Pickup city or supplier in China | |
| company | No | Customer company | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behaviors beyond the annotations: it mentions the live pricing engine, the async agent double-check, and the need to poll via check_offer_status. The readOnlyHint=false annotation is consistent with the tool creating an offer, and the description adds value by describing the async flow and the volumetric weight rule.
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?
The description is three sentences with no filler. The main purpose is front-loaded, followed by the dimension caveat and the async follow-up instruction. Each sentence earns its place, and the structure is clear and efficient.
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?
Given the 10 parameters and no output schema, the description explains the all-in DDP nature, the weight range, the pricing source, and the crucial async check flow. It mentions the email sending in the param description, which is part of the overall behavior. The flow is well-covered, though it could note the daily email limit in the main description, but it is present in the schema.
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 90%, so the baseline is 3. The description adds marginal value by emphasizing dimensions for volumetric weight and the email's role in follow-up, but these are also covered in the parameter descriptions. It does not significantly enhance understanding beyond what the schema already provides.
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: 'Get an all-in DDP offer' for a China-to-USA shipment. It clearly distinguishes this tool from siblings by focusing on offer generation, while check_offer_status and track_shipment handle later stages. The scope (100 g to 2,000 kg) is also explicitly defined.
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?
The description provides clear guidance: it explains when to provide dimensions ('for light bulky cargo volumetric weight governs the price') and explicitly instructs the agent to 'call check_offer_status with the quote_id' after this returns, indicating the follow-up workflow. It does not explicitly say 'use this when you need a quote', but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the live tracking record for a booked shipment. Requires 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: to change a booking or ask a question, email hello@plainfreight.com and include 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains that the token is the credential and that only someone with the shared link can read the record. It also discloses the return contents, including the 10-stage lifecycle and dated event log, which is useful behavioral context not present in 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?
Three sentences, each earning its place: purpose, credential requirement, return value summary, and read-only boundary. Information is front-loaded and there is no redundant filler.
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-only tool with no output schema, the description is complete: it covers the required input, authentication semantics, what the response contains, and what actions are out of scope. No critical operational detail 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?
The schema already describes the single parameter at 100% coverage, so the baseline is 3. The description adds meaningful semantics by clarifying the accepted forms (full URL or bare token) and emphasizing that the token acts as the credential, which goes 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?
The description opens with a specific verb and resource: 'Read the live tracking record for a booked shipment.' It clearly distinguishes itself from siblings check_offer_status and generate_offer by focusing on shipment tracking rather than offer status or creation.
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 states when to use the tool (for a booked shipment when you have the tracking link) and explicitly when not to use it ('to change a booking or ask a question, email hello@plainfreight.com'). This gives the agent a clear decision boundary and an alternative path.
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_offer_statusgenerate_offertrack_shipmentLive USPS, UPS, FedEx and DHL rates from the US: domestic, Canada, UK, Germany, Australia. No scale.
Live USPS, UPS & FedEx shipping rates plus USPS postage and stamp prices. Free, no API key.
Air freight rates and transit times worldwide - search routes and request quotes via AI agents.
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
Add one secure layer between your agents and this server.
