Title99/100
List Zinc orders
The title clearly communicates the tool’s action and subject. Keep it concise.
Description83/100
List or search the Zinc orders on the configured account, newest first. Renders an interactive order list. Use `search` for a partial order ID or tracking number, `status` to filter by order status, and `has_tracking` to show only shipped orders.
The description explains the capability, when to use it, and what to expect.
Inputs87/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
search
Partial Zinc order ID or tracking number to match
Clear enough to supply this argument.
status
Filter to one Zinc order status
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
has_tracking
True to return only orders that already have tracking numbers
Clear enough to supply this argument.
limit
How many orders to return (1-50, default 10)
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations75/100
Declare idempotentHint based on the tool’s actual behavior.
{
"title": "List Zinc orders",
"readOnlyHint": true,
"openWorldHint": true,
"destructiveHint": false
}Output schema92/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"orders",
"total",
"returned",
"environment"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Total matching orders on the account"
},
"orders": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"retailer",
"item_count",
"item_urls",
"retailer_logo",
"items",
"total_cents",
"total_display",
"max_price_cents",
"merchant_order_ids",
"shipment_summary",
"tracking",
"error",
"error_type",
"is_trial",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"description": "Zinc order UUID"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Failure reason when status is order_failed"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"title",
"image"
],
"properties": {
"url": {
"type": "string"
},
"image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"description": "One per line item. title/image are what the shopper saw in the review card when the order was placed through this connector; null when the order came from elsewhere."
},
"status": {
"type": "string",
"description": "Zinc order status"
},
"is_trial": {
"type": "boolean",
"description": "max_price of 0 marks a trial run: the retailer validates the order and deliberately does not place it, charging nothing. That outcome is recorded as order_failed with error_type max_price_exceeded, and nothing went wrong — do not report it as a failure. A trial carrying any other error_type did fail, before the price ceiling was ever reached, and the error explains how. This flag is the one to read: a null max_price_cents is an unknown ceiling, never a trial."
},
"retailer": {
"type": "string",
"description": "Merchant inferred from the item URLs — Zinc stores no retailer field"
},
"tracking": {
"type": "array",
"items": {
"type": "object",
"required": [
"carrier",
"tracking_number",
"status",
"estimated_delivery_date",
"tracking_url"
],
"properties": {
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "pending, in_transit, or delivered; null before first scan"
},
"carrier": {
"type": "string",
"description": "Carrier code, e.g. ups, usps, fedex"
},
"tracking_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tracking_number": {
"type": "string"
},
"estimated_delivery_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Carrier ETA as a destination-local YYYY-MM-DD date"
}
},
"additionalProperties": false
}
},
"item_urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Retailer URL per line item. Zinc stores no product name, so this is the only identification of what was ordered — a title derived from the URL path was a guess and often wrong."
},
"created_at": {
"type": "string"
},
"error_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Worker's classification of the failure, e.g. max_price_exceeded"
},
"item_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Total units across all line items"
},
"updated_at": {
"type": "string"
},
"total_cents": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"description": "What the retailer charged, in cents. Null when the order was never placed AND null on every list-orders row — the Zinc list endpoint omits it. Call get-order for the real total."
},
"retailer_logo": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The retailer's mark, for rows with no product picture."
},
"total_display": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Preformatted total, e.g. $41.98"
},
"max_price_cents": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"description": "Customer's price ceiling, in cents. Null means withheld, not zero: the public tracking view a guest reads does not carry it. A zero ceiling means something specific (see is_trial) that null does not."
},
"shipment_summary": {
"type": "string",
"description": "One-line shipment state rolled up from the tracking rows"
},
"merchant_order_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Retailer's own order numbers"
}
},
"additionalProperties": false
}
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"environment": {
"enum": [
"sandbox",
"live"
],
"type": "string",
"description": "Which Zinc dataset the configured API key reads"
}
},
"additionalProperties": false
}