# List shares (`list_shares`)

Lists the share links shoppers made for designs from the connected Store customisers, newest first, with each share id, its customiser id and name, the customiser product image and its creation date. Filters narrow the list by customiser, by customiser name text, by sign category and by creation day, counted in an IANA timezone (UTC by default). The link token and the stored design are not returned. It requires the shares:read scope and has no side effects.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/list_shares/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/list_shares.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `shares:read`
- Behaviour: read

## Purpose

See which customisers shoppers share designs from, and obtain the share ids get_share and delete_share take.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A merchant has connected this store and approved the shares:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | How many shares to return per page, between 1 and 100. Defaults to 20. |
| `cursor` | string | no | The opaque next_cursor value from the previous page, sent back with identical filters and timezone. |
| `filter` | object | no | Optional filters. An unknown filter is rejected, never ignored. |
| `filter.customiser_id` | integer | no | Only shares from this customiser. |
| `filter.customiser_name` | string | no | Only shares whose customiser name contains this text, ignoring case and surrounding spaces. |
| `filter.sign_category` | string | no | Only shares from customisers of this sign category. One of: `neon`, `acrylic_channel_letter`, `metal_channel_letter`, `metal_cut_out`, `stencil`, `lightbox`, `wood_letter`, `aluminium_plate`, `braille_sign`, `wood_frame`. |
| `filter.created_from` | string | no | The first included creation day, YYYY-MM-DD, counted in timezone. |
| `filter.created_to` | string | no | The last included creation day, YYYY-MM-DD, counted in timezone. It must not precede created_from. |
| `timezone` | string | no | The IANA timezone the creation days are counted in, such as Australia/Sydney. Defaults to UTC. |

## Result

Up to `limit` shares, newest first, plus the cursor for the next page.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `shares` | array of object | yes | The page of shares, newest first. |
| `shares[].id` | integer | yes |  |
| `shares[].customiser_id` | integer | yes |  |
| `shares[].customiser_name` | string | yes |  |
| `shares[].image_url` | string or null | no | The product image of the customiser, as the merchant admin shows it. Null when the customiser has none. |
| `shares[].created_at` | string or null | no | When the shopper made the link, UTC. Null on links older than the record. |
| `pagination` | object | yes |  |
| `pagination.has_more` | boolean | yes |  |
| `pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without shares:read. |
| `invalid_cursor` | The cursor was altered or reused for a different collection, Store, filters, or timezone; restart with no cursor. |
| `invalid_parameter` | A filter value is blank or too long, sign_category is not a supported value, a date is not YYYY-MM-DD, created_to precedes created_from, or timezone is not an IANA timezone name. |
| `unknown_filter` | Remove the filter named in parameter. This tool forwards unknown filter names so the API can refuse them explicitly. |

## Example: Neon shares made in July, Sydney time

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_shares",
    "arguments": {
      "limit": 1,
      "filter": {
        "sign_category": "neon",
        "created_from": "2026-07-01",
        "created_to": "2026-07-31"
      },
      "timezone": "Australia/Sydney"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "shares": [
        {
          "id": 512,
          "customiser_id": 42,
          "customiser_name": "Neon signs",
          "image_url": "https://cdn.example.com/customisers/42/product.png",
          "created_at": "2026-07-18T03:14:15Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}
```

## Example: A connection without shares:read (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_shares",
    "arguments": {}
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [list_shares] requires the shares:read scope, which this connection was not granted.",
        "recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the Sign Customiser connector and approve the scope named in required_scopes. If the approval screen does not offer that permission, ask them to remove the connector from this AI agent and add it again. Do not retry this call.",
        "required_scopes": [
          "shares:read"
        ],
        "granted_scopes": [
          "store:read"
        ]
      }
    }
  }
}
```
