machship-mcp

Create Quote

machship_create_quote

Creates a freight quote and returns available carrier rates for a shipment, so you can compare prices and transit times before creating a consignment.

Instructions

Creates a freight quote in Machship — returns available carrier rates for a shipment. Use this to compare carrier prices and transit times before creating a consignment.

Args:

quote (object): Quote request including:
- companyId (number): Company to quote under
- fromAddress or fromLocationId: Pickup address or location ID
- toAddress: Delivery address (suburb, postcode, state, country)
- items: Array of items with weight (kg), length/width/height (cm)
- carrierId / serviceId (optional): Filter to a specific carrier/service

Returns: Array of available rate options, each with: { "carrierId", "serviceName", "totalCost", "transitDays", "accountId" }

Examples:

Use when: "Get freight quotes from Sydney to Melbourne for a 5kg parcel"
Don't use when: You already have a carrier in mind — use machship_create_consignment directly

Input Schema

Name	Required	Description	Default
`quote`	Yes	Quote request body (companyId, fromAddress/fromLocationId, toAddress, items)

Output Schema

Name	Required	Description	Default
`errors`	No	Validation errors returned by Machship, if any
`object`	No	Response payload from the Machship API

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.1Nov 3, 2026

addedInput schema / properties / quote / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "errors": {
+      "anyOf": [
+        {
+          "items": {},
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Validation errors returned by Machship, if any"
+    },
+    "object": {
+      "description": "Response payload from the Machship API"
+    }
+  },
+  "type": "object"
+}

First observedv1.0.0Jun 12, 2026

TDQS

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds that the call reaches out to carrier networks and is a non-destructive pre-step to a consignment, but it never says whether a quote record is persisted and later retrievable via machship_get_quote, nor anything about rate limits or cost of repeated calls — a meaningful gap for a create-verb tool flagged non-idempotent.

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-loaded with the one-line purpose, then Args, Returns and Examples in a predictable structure, with no filler sentences. The nested bullet list is a little dense in proportion to the single top-level parameter, but every line carries usable information.

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

Completeness4/5

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

For a nested-object tool with a 100%-covered but structurally empty schema, the description supplies the input field list, the returned rate fields, and a concrete usage example, which is close to what an agent needs. Remaining gaps are the sibling disambiguation and the persistence/retrieval behaviour of the created quote; return values themselves are already covered by the output schema.

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?

The input schema's quote object is effectively opaque (additionalProperties: {} with only a short parenthetical), so the description carries real weight: it enumerates companyId, fromAddress vs fromLocationId, toAddress components, items with weight in kg and dimensions in cm, and marks carrierId/serviceId as optional filters. Units and the address-or-location-ID choice are genuine value-adds; it still leaves item-level array shape and any per-item optional fields implicit.

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 and resource with scope: it creates a freight quote and returns available carrier rates for a shipment, and it names the downstream step (consignment creation). The one ambiguity it leaves is against its nearest sibling, machship_create_quote_complex_items, which is never mentioned, so an agent still cannot tell from the description alone which quote tool fits which item shape.

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?

The description gives an explicit when-to-use ('compare carrier prices and transit times before creating a consignment') and a when-not with a named alternative ('you already have a carrier in mind — use machship_create_consignment directly'). It stops short of covering the more likely confusion case, the complex-items quote sibling, so routing guidance is strong but incomplete.

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

Deploy Server