starshipit-mcp

Delete Products

starshipit_delete_products

DestructiveIdempotent

Delete selected product IDs or clear the entire StarShipIt catalogue, including discontinued or test items; deletions are permanent and cannot be undone.

Instructions

Delete one or more products from the StarShipIt product catalogue. This operation is irreversible.

Two modes:

Delete specific products (recommended): Provide an array of numeric product_ids. Only those products are deleted. Leave all_products as false (default).
Delete ALL products (use with extreme caution): Set all_products: true and pass an empty product_ids array []. This permanently removes every product in the catalogue — there is no undo.

Parameters:

product_ids: Array of numeric product IDs to delete. Use an empty array [] only when all_products is true.
all_products: Set to true to delete the entire catalogue. Defaults to false. If true, product_ids is ignored.

Returns:

success: Whether the deletion succeeded
deleted_count: Number of products deleted (if returned by API)
errors: Any per-product errors

Error cases:

400: Invalid product IDs or malformed request body
404: One or more product IDs not found (partial deletes may still succeed)

Use this tool when:

Removing discontinued products from the catalogue
Purging test/dummy products after setup
Clearing the entire catalogue before a fresh import (all_products=true — use carefully)

Input Schema

Name	Required	Description	Default
`product_ids`	Yes	Array of numeric product IDs to delete. Pass an empty array [] only when all_products is true.
`all_products`	No	Set to true to delete ALL products in the catalogue. Irreversible. When true, product_ids is ignored. Default: false.
`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.8/5.0

Behavior5/5

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

Although annotations already mark this as destructive, non-read-only, idempotent, and open-world, the description adds important behavioral context: the operation is irreversible, deleting all products has no undo, and partial deletes may still succeed when some IDs are not found. It also documents per-product errors, which materially helps an agent reason about outcomes.

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?

The description is well structured and front-loads the irreversible nature of the operation, followed by mode guidance, parameters, returns, errors, and use cases. It is appropriately thorough for a destructive tool, though some parameter and return details repeat information already present in the schema and output schema.

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?

Given the destructive nature of the tool, the description is complete enough for correct invocation: it covers both modes, required empty-array behavior, irreversibility, partial-failure behavior, error cases, and when to use it. Output schema exists, so the brief returns section is supplemental rather than necessary.

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 description coverage is already 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining the coupling between product_ids and all_products, including that an empty product_ids array is only valid when all_products is true and that product_ids is ignored when all_products is true.

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 states a specific verb and resource: deleting one or more products from the StarShipIt product catalogue. It clearly distinguishes the two supported deletion modes, specific product IDs versus deleting the entire catalogue, so an agent can understand the operation 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 Guidelines5/5

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

The description includes an explicit 'Use this tool when' section with concrete scenarios such as removing discontinued products or purging test products. It also gives clear mode-selection guidance: specific product IDs are recommended, while all_products=true is framed as an extreme-caution path with no undo.

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

Deploy Server