# List customiser options (`list_customiser_options`)

Lists the records in one option family of one customiser: the colours, fonts, sizes, materials, backboards, mountings, letter types, presets or other choices a shopper picks from. The family is chosen with the option_type argument, and exactly one family is read per call. Results are paginated, carry the field names the public API publishes, and are always limited to the connected Store. It requires the customisers:read scope and has no side effects.

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

## Purpose

Discover what a customiser offers in one option family, and obtain the record ids the option read and write tools take.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers.
- letter_type_id for the letter_part and letter_part_colour families, and letter_part as well for letter_part_colour.
- A merchant has connected this store and approved the customisers:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `option_type` | string | yes | Which option family to read. Exactly one family is read per call; the value maps to the same per-family boundary the public API enforces. One of: `backboard`, `backlight`, `colour`, `extra`, `font`, `form`, `icon`, `jacket`, `letter_type`, `letter_part`, `letter_part_colour`, `material`, `mounting`, `mounting_colour`, `preset`, `size`, `support_finish`, `legacy_fixed_height_size`. |
| `letter_type_id` | integer | no | The letter type that owns the records, required for the letter_part and letter_part_colour families and rejected for every other family. |
| `letter_part` | string | no | The letter part whose colours to read, required for the letter_part_colour family. Which parts a letter type offers is that letter type own letter_parts list. One of: `face`, `back`, `side`, `top`, `bottom`, `left`, `right`, `halo`, `trim`, `tube`. |
| `limit` | integer | no | How many records to return per page, between 1 and 100. Defaults to 20. The letter_part family accepts no page size. |
| `cursor` | string | no | The opaque next_cursor value from the previous page. Omit it for the first page and keep option_type identical between pages. |

## Result

Up to `limit` records of the requested family in the order the storefront presents them, plus the cursor for the next page. The letter_part family is a complete catalogue of one letter type and returns every record in one page.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes | The customiser the records belong to. |
| `option_type` | string | yes | The family that was read. One of: `backboard`, `backlight`, `colour`, `extra`, `font`, `form`, `icon`, `jacket`, `letter_type`, `letter_part`, `letter_part_colour`, `material`, `mounting`, `mounting_colour`, `preset`, `size`, `support_finish`, `legacy_fixed_height_size`. |
| `options` | array of object | yes | The page of records, in the order the storefront presents them. Members are the family own public API fields; get_customiser_option returns the same record with its image slots resolved. |
| `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 customisers:read. |
| `invalid_cursor` | The cursor was altered or reused with a different family; restart with no cursor. |
| `resource_not_found` | No customiser or letter type with that id belongs to this store. |
| `unknown_parameter` | limit and cursor were sent to the letter_part family, which returns one complete page and accepts neither. |
| `validation_failed` | option_type was omitted or is not a family name, or a nested family was called without letter_type_id or letter_part. |

## Example: First page of a customiser colours

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customiser_options",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "limit": 1
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "options": [
        {
          "id": 7,
          "name": "Warm White",
          "colour_type": "single",
          "hexcode": "#FFEEDD",
          "sort_order": 1,
          "base_price": 0,
          "currency": "USD"
        }
      ],
      "pagination": {
        "has_more": true,
        "next_cursor": "eyJpZCI6N30"
      }
    }
  }
}
```

## Example: A nested family called without its letter type (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customiser_options",
    "arguments": {
      "customiser_id": 42,
      "option_type": "letter_part"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The letter type id field is required.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "pointer": "/letter_type_id"
      }
    }
  }
}
```