> ## 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 two 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\_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>