starshipit-mcp

Delete Address Book Entries

starshipit_delete_addresses

DestructiveIdempotent

Permanently delete one or more address book entries by ID to remove outdated or duplicate addresses; verify IDs first because deletion cannot be undone.

Instructions

Delete one or more addresses from the StarShipIt address book by their IDs. This action is permanent and cannot be undone.

When to use: Call this to remove outdated, duplicate, or unwanted address entries. You can delete multiple addresses in a single call by passing an array of IDs.

CAUTION: Deletion is irreversible. Verify the IDs with starshipit_list_addresses before calling this tool.

Parameters:

address_ids — non-empty array of integer address book IDs to delete

Returns: A success confirmation. If any ID does not exist, the API may still return success for the IDs that were found.

Errors:

400 — empty array or invalid ID format
401/403 — authentication failure

Example — delete two addresses:

{ "address_ids": [81692357, 81692358] }

Workflow tip: Always call starshipit_list_addresses with a search_term first to confirm which IDs you want to delete before proceeding.

Input Schema

Name	Required	Description	Default
`address_ids`	Yes	Array of address book IDs to permanently delete

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?

Beyond the destructive and non-read-only annotations, it discloses irreversibility, possible partial success when some IDs do not exist, and representative 400 and 401/403 errors. These details materially affect how an agent should verify inputs and interpret the result.

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 front-loaded with the operation and irreversibility, then organizes usage, parameters, results, errors, and an example clearly. However, the permanent-deletion warning and the instruction to verify IDs with `starshipit_list_addresses` are each repeated, making it somewhat longer than necessary for a one-parameter tool.

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 simple but destructive operation, it supplies everything needed for safe selection and invocation: ID-based scope, batching, verification steps, error cases, and an important partial-success caveat. The output schema already exists, while the brief return description still clarifies the practical success semantics.

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?

The schema already fully documents `address_ids`, including its integer items and non-empty constraint, so much of the parameter section repeats structured information. The concrete two-ID example and guidance to obtain and confirm IDs through the listing tool add useful practical context.

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 opening sentence gives a specific verb, resource, scope, and selection mechanism: deleting one or more StarShipIt address-book entries by ID. This clearly distinguishes it from siblings that delete orders or products and from address listing or updating tools.

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?

It explicitly recommends the tool for outdated, duplicate, or unwanted entries and notes that multiple IDs can be deleted in one call. It also gives a concrete pre-deletion workflow using `starshipit_list_addresses` with a search term to verify the intended IDs.

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

Deploy Server