> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Returns — Read

> Search and inspect returns through the Loop MCP Server.

These read-only tools let an assistant search for returns, inspect a single return in detail, and review a return's event timeline. Each tool renders a Generative UI card so the merchant can drill in without leaving the chat.

***

## List Returns

**Tool name:** `list-returns-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Search and paginate the authenticated shop's returns with rich filtering. Filters compose with AND semantics across distinct fields and OR semantics within multi-value fields (`status`, `label_status`, `return_method_state`).

### Parameters

| Parameter             | Type      | Default     | Description                                                                                                        |
| --------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `query`               | string    | –           | Free-text search across order name, customer email, and other fields.                                              |
| `status`              | string\[] | –           | One or more of `open`, `partial`, `review`, `expired`, `processing`, `processed`, `closed`, `cancelled`.           |
| `label_status`        | string\[] | –           | One or more of `new`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `no_label`, `failure`.         |
| `return_method_state` | string\[] | –           | One or more of `new`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `needs_scheduled`, `canceled`. |
| `outcome`             | string    | –           | One of `exchange`, `upsell`, `refund`, `credit`, `exchange+refund`, `exchange+credit`, `credit+refund`.            |
| `flagged`             | boolean   | –           | `true` for only flagged returns, `false` for only unflagged.                                                       |
| `fraud_risk`          | string    | –           | `has_unconfirmed_high_fraud_risk` or `has_confirmed_fraud_risk`.                                                   |
| `is_warranty`         | boolean   | –           | `true` for warranty returns only, `false` to exclude warranty returns.                                             |
| `day_limit`           | integer   | –           | Restrict to returns updated within the last N days.                                                                |
| `sort_by`             | string    | `createdAt` | One of `returnId`, `orderName`, `returnStatus`, `labelStatus`, `createdAt`, `email`, `returnMethod`, `outcome`.    |
| `sort_direction`      | string    | `desc`      | `asc` or `desc`.                                                                                                   |
| `page`                | integer   | `1`         | Page number.                                                                                                       |
| `limit`               | integer   | `25`        | Page size, max `100`.                                                                                              |

### Example prompts

> "Show me the most recent 10 returns flagged for review."

> "List returns delivered in the last 7 days that haven't been processed yet."

***

## Get Return Details

**Tool name:** `get-return-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Fetch full detail for a single return, including order info, state, customer, line items, refund/exchange resolution, and notes. Renders an interactive card with action buttons for Process, Cancel, Close, Reject, and Timeline.

### Parameters

| Parameter   | Type    | Required | Description         |
| ----------- | ------- | -------- | ------------------- |
| `return_id` | integer | yes      | The Loop return ID. |

### Example prompts

> "Get return #1234 and summarize what's happening."

> "Pull up the details for the return I just flagged."

***

## Get Return Timeline

**Tool name:** `get-return-timeline-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Retrieve the chronological event timeline for a return — creations, state changes, label generation, shipping events, processing actions, customer notifications, and manual merchant actions. Large event payloads are truncated automatically.

### Parameters

| Parameter   | Type    | Default  | Description           |
| ----------- | ------- | -------- | --------------------- |
| `return_id` | integer | required | The Loop return ID.   |
| `page`      | integer | `1`      | Page number.          |
| `limit`     | integer | `50`     | Page size, max `200`. |

### Example prompts

> "What happened with return #1234? Walk me through the timeline."

> "When was the label for this return generated?"