starshipit-mcp

Merge Orders

starshipit_merge_orders

Destructive

Merge selected child orders into a parent order so multiple purchases ship together as one package in StarShipIt.

Instructions

Merge one or more child orders into a parent order in StarShipIt. After merging, the child orders are absorbed into the parent and the combined shipment will be dispatched as a single package.

When to use: Use when a customer has placed multiple orders that should ship together in one box. Use starshipit_get_suggested_merges first to find recommended candidates.

Parameters:

parent_order_id (required) — The order ID that will be kept as the merged result
child_order_ids (required) — Array of order IDs to merge into the parent (at least one)

Returns: Confirmation of the merged order.

Warning: This is a destructive operation — child orders will no longer exist as independent orders after the merge.

Errors: 400 if child_order_ids is empty; 404 if any order ID not found; 409 if orders are not merge-compatible (e.g. different destination addresses); 401 if API keys invalid.

Input Schema

Name	Required	Description	Default
`child_order_ids`	Yes	Array of order IDs to merge into the parent order
`parent_order_id`	Yes	Order ID of the parent order that will contain the merged result

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

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description still adds real value with the post-state ('child orders are absorbed', 'dispatched as a single package'), compatibility constraints (matching destination addresses) and specific error semantics (400/404/409/401). It slightly restates the destructive warning the annotation already carries.

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 purpose, then clearly sectioned into when-to-use, parameters, returns, warning, errors. Slightly heavier than needed for a two-parameter tool, with the parameters and returns sections duplicating structured data, but no section is wasted.

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 destructive two-parameter merge, the agent gets trigger conditions, prerequisites, post-merge state, compatibility caveats, and failure modes; an output schema exists so the brief 'Returns' note is sufficient.

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% and both field descriptions already explain parent vs. children. The description's per-parameter bullets largely restate the schema, adding only the emphasis that the parent is 'kept as the merged result' and that at least one child is required (already enforced by minItems=1).

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?

Names a specific verb (merge) and resource (orders) with explicit scope: many-to-one children into a parent, resulting in one package. Easily distinguished from siblings like starshipit_update_order or starshipit_get_suggested_merges.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the trigger condition ('customer has placed multiple orders that should ship together in one box') and names the alternative/recommended preceding step, starshipit_get_suggested_merges, to find candidates.

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

Deploy Server