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

# Tools

> Reference for all tools available in the Subtotal Data MCP.

The Subtotal Data MCP provides three tools for exploring and querying your purchase data.

## ask

Ask a natural language question about your purchase data. The server translates it into SQL and returns the results — no SQL knowledge required.

**Parameters:**

| Name       | Type   | Required | Description                                          |
| :--------- | :----- | :------- | :--------------------------------------------------- |
| `question` | string | Yes      | A natural language question about your purchase data |

**Example questions:**

* "Show me the top 5 retailers by purchase count this year"
* "How many active connections do I have?"
* "What are my highest-value purchases from the last 30 days?"
* "Which brands appear most frequently in my items?"

**Response format:**

```json theme={null}
{
  "fields": ["name", "purchase_count"],
  "results": [
    ["Amazon", 1523],
    ["Target", 892],
    ["Walmart", 641]
  ],
  "result_count": 3
}
```

**Constraints:**

* Questions must be plain English — embedded SQL will be rejected
* Only `SELECT` queries are generated — your data is never modified
* Results are limited to 100 rows and 5 MB
* A 5-second execution timeout is enforced

<Warning>
  If the question cannot be answered with the available data, or the generated query fails, the response will contain an `error` field:

  ```json theme={null}
  {
    "error": "This question cannot be answered with the available data."
  }
  ```

  Other possible errors include request timeouts and response size limits.
</Warning>

<Note>
  `ask` uses an AI model to translate your question into SQL. For best results, be specific about the data you want, time ranges, and how results should be grouped or sorted. To inspect the data model itself (entities, fields, relationships), use `get_data_model` instead.
</Note>

## get\_retailers

List the retailers available to your account as structured rows. By default returns only the retailers enabled for your team (each with a Subtotal Link URL); pass `include="all"` to list every active retailer in the catalog, annotated with whether it's enabled for your team.

**Parameters:**

| Name      | Type   | Required | Description                                                                                                                                                                                                                                                   |
| :-------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `include` | string | No       | `enabled` (default) — only the retailers enabled for your team, each with a `link_url`. `all` — every active retailer in the catalog, each annotated with an `enabled` flag and a `link_url` (present only when enabled). These are the only accepted values. |

**Response format:**

```json theme={null}
{
  "retailers": [
    {
      "retailer_id": "walmart",
      "name": "Walmart",
      "images": {
        "logo": { "light": ".../light/logo.svg", "dark": ".../dark/logo.svg" },
        "icon": { "light": ".../light/icon.svg", "dark": ".../dark/icon.svg" }
      },
      "status": "active",
      "enabled": true,
      "link_url": "https://link.subtotal.com/a1b2c3d4"
    }
  ]
}
```

**Fields:**

| Field         | Description                                                                                                |
| :------------ | :--------------------------------------------------------------------------------------------------------- |
| `retailer_id` | Retailer slug — the exact value used to filter purchase data by retailer (e.g. in `ask`).                  |
| `name`        | Retailer display name.                                                                                     |
| `images`      | Logo and icon URLs, each with a `light` and `dark` theme.                                                  |
| `status`      | Platform status: `active`, `limited`, or `inactive`.                                                       |
| `enabled`     | Whether this retailer is enabled for your team.                                                            |
| `link_url`    | URL to launch Subtotal Link for the retailer. Present only when the retailer is enabled; `null` otherwise. |

<Note>
  This is the same retailer contract returned by the public `GET /retailers` API. With `include="all"`, `link_url` is `null` for retailers not enabled for your team.
</Note>

## get\_data\_model

Returns the data model for your purchase data, including entities, fields, types, and relationships.

**Parameters:** None

**Returns:** A plain-text data model describing six entities: `connection`, `purchase`, `item`, `retailer`, `product`, and `brand`.

<Note>
  If you're using `ask`, you typically don't need to call `get_data_model` — the server already has the data model when answering questions.
</Note>