starshipit-mcp

Manifest Shipments

starshipit_manifest_shipment

Idempotent

Finalise and commit StarShipIt shipments to the carrier by order IDs, generating a manifest PDF for end-of-day or batch pickup.

Instructions

Manifest (finalise/close) shipments by order IDs in StarShipIt.

When to use: Use this tool to finalise and commit shipments to the carrier. Manifesting is typically done once at end-of-day or when a batch of orders is ready for carrier pickup. Once manifested, shipments cannot be easily reversed — ensure labels are correct before manifesting.

Important: This operation is idempotent — manifesting already-manifested orders will not create duplicate manifests.

Parameters:

order_ids (required): Array of numeric StarShipIt order IDs to include in the manifest. All orders must already have labels printed.

Returns: The manifest document as a base64 PDF, with its label type.

Example success response:

{
  "success": true,
  "label_type": "PDF",
  "pdf": "JVBERi0xLjQK..."
}

Error cases: 400 if order IDs are invalid or orders do not have labels printed; 404 if orders do not exist; 409 if orders are in an incompatible state for manifesting.

Input Schema

Name	Required	Description	Default
`order_ids`	Yes	Array of StarShipIt order IDs to manifest. All must have labels already printed.

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

Behavior4/5

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

Beyond annotations it discloses the key risk (manifesting cannot be easily reversed), the prerequisite that labels must already be printed, and concrete error semantics (400/404/409). The idempotency claim merely restates idempotentHint=true, and destructiveHint=false is not visually contradicted since manifesting locks state rather than deleting data.

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 action, then labelled When to use / Important / Parameters / Returns / Errors sections that are easy to scan. The inline example JSON response is partly redundant given an output schema exists, making it slightly longer than necessary.

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 one-parameter, state-committing tool the definition covers prerequisites, irreversibility, idempotency, return payload (base64 PDF plus label type), and the full set of failure codes. Nothing an agent needs before calling is missing.

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 the schema already documents order_ids, its integer item type, and the label prerequisite. The description repeats that content plus the word 'numeric' but adds no format, batching limit, or ordering semantics beyond the schema — baseline 3 applies.

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?

"Manifest (finalise/close) shipments by order IDs" gives a specific verb, resource, and selection axis. The 'by order IDs' phrasing implicitly separates it from siblings like starshipit_manifest_by_tracking and starshipit_manifest_by_carrier, but neither is named, so an agent must infer the routing rule.

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 'When to use' section states the operational context clearly: end-of-day batch finalisation before carrier pickup, with a caution to verify labels first. It stops short of explicitly naming when to prefer the tracking- or carrier-based manifest siblings instead.

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

Deploy Server