starshipit-mcp

Get Shipping Rates

starshipit_get_rates

Read-onlyIdempotent

Compare available shipping rates by price for a shipment between sender and destination addresses using package dimensions, so you can choose a service before creating an order.

Instructions

Get available shipping rates (quotes) for a shipment between a sender and destination address with the given package dimensions.

When to use: Call this before creating an order when you need to compare services by price. It is read-only and safe to call multiple times.

Required parameters:

sender — pickup/origin address (street, suburb, post_code, country_code are required; city and state are optional but improve accuracy)
destination — delivery address (same shape as sender)
packages — array of package objects; each must have weight (kg); height, width, length (all in metres) are optional but recommended for volumetric pricing

Returns: An array of rate objects, each with:

service_name / service_code — service description and machine-readable code (use service_code when setting a carrier on an order)
total_price — quoted price in the account currency

Errors:

400 — invalid address or package data (check post_code format and country_code)
401/403 — authentication failure; verify API keys
No rates returned — the origin/destination combination may not be supported by any connected carrier

Example request body:

{
  "sender": { "street": "184 Exhibition St", "suburb": "Melbourne", "post_code": "3000", "country_code": "AU", "state": "VIC" },
  "destination": { "street": "20 Liverpool St", "suburb": "Paddington", "post_code": "2021", "country_code": "AU", "state": "NSW" },
  "packages": [{ "weight": 0.5, "length": 0.3, "width": 0.2, "height": 0.1 }]
}

Input Schema

Name	Required	Description	Default
`sender`	Yes	Origin/pickup address
`packages`	Yes	One or more packages to ship; weight (kg) is required per package
`destination`	Yes	Delivery address
`response_format`	No	Output format: 'markdown' for human-readable or 'json' for machine-readable	markdown

Output Schema

Name	Required	Description
`errors`	No	Validation or processing errors returned by StarShipIt
`object`	No	The response payload when StarShipIt returns a non-object value
`success`	No	StarShipIt success flag (a boolean on most endpoints)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 3, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower; the description still adds value by documenting 400/401/403 causes and the empty-result case where no connected carrier supports the lane. It could say more about pricing currency/surcharge behavior, but the error and no-rates semantics are genuinely useful additions.

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 one-line purpose followed by clearly labeled When to use / Required parameters / Returns / Errors sections, plus a concrete example body. It is somewhat longer than necessary because it repeats schema constraints (required address fields, kg/metres units) that the schema already enforces.

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 nested three-object payload with four parameters, the description supplies call timing, address shape, package geometry guidance, response fields (service_code vs service_name, total_price), failure modes, and a worked example. An agent could invoke this correctly without opening the schema.

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

Parameters3/5

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

Schema coverage is 100%, so units (kg, metres) and field-level notes are already documented in structured form. The description mostly restates required fields and adds a mild hint that city/state improve accuracy, but never mentions the `response_format` parameter at all, so it does not exceed the baseline.

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 opening sentence gives a specific verb and resource: retrieve available shipping rates (quotes) for a shipment between sender and destination with given package dimensions. It is clearly distinguishable from siblings like starshipit_create_order (which consumes the rates) and starshipit_get_delivery_services (which lists services rather than prices).

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?

It states a concrete trigger — call before creating an order when comparing services by price — and that it is read-only and safe to repeat. It does not name a sibling alternative (e.g. when to prefer get_delivery_services or tracking lookups instead), so the when-not guidance is implicit rather than explicit.

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

Deploy Server