Skip to main content
Glama
Sign In
devkindhq

starshipit-mcp

by devkindhq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Get Order

starshipit_get_order
Read-onlyIdempotent

Retrieve a single StarShipIt order by internal ID or merchant order number to access full order details such as destination, items, packages, carrier assignment, and metadata.

Instructions

Retrieve a single order from StarShipIt by its internal ID or merchant order number. At least one of order_id or order_number must be supplied.

When to use: Use when you need the full detail of a specific order — destination, items, packages, carrier assignment, and metadata.

Parameters:

  • order_id (optional) — StarShipIt internal numeric order ID

  • order_number (optional) — Merchant-assigned order number / reference (e.g. "#1001")

At least one of order_id or order_number must be provided.

Returns: Full Order object.

Example response (JSON):

{
  "order": {
    "order_id": 12345,
    "order_number": "#1001",
    "carrier": "AUSPOST",
    "destination": { "name": "Jane Smith", "street": "1 Test St", "post_code": "3000", "country": "Australia" }
  }
}

Errors: 400 if neither identifier provided; 404 if order not found; 401 if API keys invalid.

Input Schema

NameRequiredDescriptionDefault
order_idNoStarShipIt internal numeric order ID
order_numberNoMerchant-assigned order number (e.g. "#1001")
response_formatNoOutput format: 'markdown' for human-readable or 'json' for machine-readablemarkdown

Output Schema

NameRequiredDescriptionDefault
errorsNoValidation or processing errors returned by StarShipIt
objectNoThe response payload when StarShipIt returns a non-object value
successNoStarShipIt success flag (a boolean on most endpoints)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the 400 error when neither identifier is supplied, 404 on not-found, and 401 on invalid keys — plus what the returned payload contains. Return-shape detail is somewhat redundant given an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Headers and front-loaded purpose make it scannable, but the 'at least one identifier' rule is repeated three times (intro, Parameters, Errors), and the full example JSON response duplicates information already available in the output schema. The content is useful but noticeably padded for a three-parameter read tool.

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?

With annotations and an output schema available, the bar is mostly about invocation correctness: the identifier constraint and error cases are documented, so an agent can call it successfully. The only real gap is that `response_format` and its enum are left to the schema alone.

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 per-parameter text largely restates the schema. However, the description contributes the cross-field constraint that at least one of `order_id` or `order_number` must be supplied, which is absent from the schema (no required list, no anyOf), and clarifies the merchant reference format. The third parameter, `response_format`, is never mentioned.

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?

States a specific verb and resource ('Retrieve a single order') plus the two lookup keys, and the word 'single' implicitly separates it from the many list_*/search_orders siblings. An agent can identify the right tool without opening the schema.

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' block gives a clear condition: when full detail of one specific order is needed (destination, items, packages, carrier, metadata). It does not explicitly name the alternative to pick instead when searching by other criteria (e.g. starshipit_search_orders), so it falls short of 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

Other Tools