starshipit-mcp

Track Shipment

starshipit_track_shipment

Read-onlyIdempotent

Look up a shipment by tracking number to retrieve current status, carrier details, and tracking events, including tracking-only orders imported into StarShipIt.

Instructions

Track a shipment by tracking number using StarShipIt.

When to use: Use this tool to retrieve the current status, tracking events and carrier details for any shipment tracked through StarShipIt. This works for shipments created in StarShipIt as well as tracking-only orders imported via starshipit_create_tracking_order.

Parameters:

tracking_number (required): The carrier tracking number to look up (e.g. "1Z999AA10123456784").
response_format (optional): Output format — "markdown" (default) for a human-readable summary with formatted tracking events, or "json" for the raw API response suitable for programmatic use.

Returns: Tracking status, order number and status, carrier name, service, shipment date, last update, carrier tracking URL, and a list of tracking events (date, status, details).

Example success response (markdown format):

## Tracking: 2XD198209601000935102

**Status:** In Transit
**Order:** C12346 (Shipped)
**Carrier:** Australia Post
**Service:** 7B05
**Shipped:** 2024-04-17T12:52:05
**Tracking URL:** https://auspost.com.au/mypost/track/details/2XD198209601000935102

### Tracking Events

- **2024-04-17T13:20:18 — In Transit:** Item processed at facility

Error cases: 404 if the tracking number is not found in StarShipIt; 400 if the tracking number format is invalid.

Input Schema

Name	Required	Description	Default
`response_format`	No	Output format: 'markdown' for human-readable or 'json' for machine-readable	markdown
`tracking_number`	Yes	The carrier tracking number to look up

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.3/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/destructive/openWorld, so safety is covered; the description adds genuinely new behavior: 404 when the tracking number is not found and 400 on malformed numbers. It also discloses that response_format changes the shape of the output (formatted events vs raw API payload) and enumerates the returned fields. It does not mention rate limits or caching/refresh behavior, so not a 5.

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 purpose, then when-to-use, parameters, returns, example and errors in a predictable order that is easy to scan. The full sample markdown response is somewhat long and partly redundant given an output schema exists, which keeps it from a 5.

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 two-parameter read tool with 100% schema coverage and an output schema, this description covers everything an agent needs: format semantics, error conditions, and lookup scope. The only thing it repeats rather than adds is the field list of return values already captured 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?

Schema coverage is 100%, so a baseline of 3 applies, and the description earns more by explaining the practical tradeoff behind response_format ('markdown' default with formatted tracking events vs 'json' raw API response for programmatic use) and giving a concrete tracking-number format example. This adds meaning beyond the schema's one-line enum description.

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 description opens with a specific verb+resource ('Track a shipment by tracking number') and immediately scopes it to StarShipIt, also clarifying that it covers both StarShipIt-created shipments and tracking-only orders imported via starshipit_create_tracking_order. This distinguishes it cleanly from sibling tools like starshipit_list_shipped_orders or starshipit_get_order.

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?

An explicit 'When to use' block states the purpose and the coverage boundary (shipments created in StarShipIt plus tracking-only orders), which is the key selection signal versus order-listing siblings. It stops short of naming a concrete alternative or when-not-to-use case, which keeps it from a 5.

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

Deploy Server