amazon-orders-mcp

Overview Schema Source Related Servers Discussions Admin

get_orders

Read-only

Retrieve Amazon order history in batches for a chosen site and time range, including Household members' orders the account can view, and return a cursor for the next batch.

Instructions

Get a batch of the Amazon Order history for a given time period, with the Amazon Household members whose Orders the account can view and a cursor to fetch the next batch.

Input Schema

Name	Required	Description
`site`	No	The Amazon site to read, e.g. `amazon.de`, since each site has its own orders. By default, the user's default site (see `check_session`).
`year`	No	The year for which to get history. Ignored if `time_filter` or `cursor` is provided. Defaults to the current year if neither `year` nor `time_filter` is specified.
`limit`	No	Stop fetching history pages once at least this many Orders are collected. Whole pages are fetched, so the batch can hold up to a page more than `limit`. `None` fetches every page.
`cursor`	No	The `cursor` of the previous batch, to fetch the next one. The filters it was fetched with carry over.
`start_index`	No	The index of the Order from which to start fetching in the history. Ignored if `cursor` is provided.
`time_filter`	No	The time filter to use. Supported values are `"last30"` (last 30 days), `"months-3"` (past 3 months), or `"year-YYYY"` (specific year). If provided, this takes precedence over the `year` parameter.
`full_details`	No	Get the full details for each Order in the batch. This will execute an additional request per Order.
`order_filter`	No	The order type filter to use, e.g. `"digital-orders"` for Kindle and other digital purchases, which the default history doesn't include. If provided, appended alongside the time filter.
`family_member_id`	No	The ID of an Amazon Household member whose Orders to get, such as a linked Teen account, from `household_members`. An account in an Amazon Household gets the whole household's Orders by default; pass `"self"` for only its own.

Output Schema

Name	Required	Description
`items`	No	The results in this batch.
`cursor`	No	Pass this back as `cursor` to the same call to fetch the next batch. A JSON-safe `dict` to keep as it is, not to build or change. `None` when there are no more results.
`has_more`	No	`True` if there are more results to fetch with `cursor`.
`household_members`	No	The Amazon Household members whose Orders the account can view, such as linked Teen accounts, from the Order history's member filter. Pass a member's `id` as `family_member_id` to get their Orders. Empty if the account has none.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.1.0Oct 25, 2026

changedInput schema / properties / family_member_id / description

Previous value: -"The ID of an Amazon Household member whose Orders to get, such as a linked Teen account, from `get_family_members`."New value: +"The ID of an Amazon Household member whose Orders to get, such as a linked Teen account, from `household_members`. An account in an Amazon Household gets the whole household's Orders by default; pass `\"self\"` for only its own."

changedOutput schema / description

Previous value: -"The batch of Orders, and the cursor for the next one."New value: +"The batch of Orders, the Amazon Household members, and the cursor for the next one."

addedOutput schema / properties / household_members

Added value: +{
+  "description": "The Amazon Household members whose Orders the account can view, such as linked Teen accounts, from the Order history's member filter. Pass a member's `id` as `family_member_id` to get their Orders. Empty if the account has none.",
+  "items": {
+    "additionalProperties": true,
+    "description": "A member of the Amazon Household whose Orders the account can view, such as a linked Teen account. Pass its `id` as `family_member_id` to `get_orders` to get their Orders.",
+    "properties": {
+      "id": {
+        "description": "The FamilyMember ID, the value Amazon's household member filter (`householdMembers`) takes.",
+        "type": "string"
+      },
+      "name": {
+        "description": "The FamilyMember name.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

Addedv2.0.1Oct 24, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With readOnlyHint=true and openWorldHint=true already declaring the safety profile, the description still adds real context: results come in batches, a cursor drives the next batch, and household members whose orders the account can view are included. It stops short of noting that the batch may exceed `limit` due to whole-page fetching or that `full_details` triggers extra requests, both of which remain schema-only.

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?

A single front-loaded sentence with no filler; the return-shape clause is packed but each part (history, household members, cursor) carries information. Slightly dense/run-on for a one-liner but efficient.

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?

An output schema exists, so explaining return values is unnecessary; the description covers purpose and pagination adequately for a 9-param, all-optional tool. The remaining gap is routing guidance among the many sibling retrieval tools, which is the one thing an agent still has to infer.

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% with rich per-parameter documentation, so the baseline is 3. The description only gestures at the time-period and cursor semantics; precedence rules, filter values, and `family_member_id` behavior are all left to the schema, which is acceptable but adds nothing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (get a batch of Amazon Order history) plus the returned payload shape (household members, cursor). This distinguishes it implicitly from the singular `get_order` and from `search_orders`, but it never names those siblings to make the split explicit.

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

Usage Guidelines3/5

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

Usage is only implied: fetching history for a time period with cursor-based paging and optional household scope. There is no statement of when to prefer this over `search_orders` or `get_order`, and no prerequisites (e.g. requiring a session) are given.

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

Deploy Server