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

# Tool reference

> The seven tools the AIOD MCP server exposes, what each one is for, and the conventions they share.

The AIOD MCP server exposes seven tools. Five read, two write. There is no general Shopify API access behind them.

Most people never need this page — your assistant picks the right tool on its own. It is here for anyone building an agent, debugging a call, or wanting to know exactly what a tool returns.

## The tools

<CardGroup cols={2}>
  <Card title="Find discounts" icon="search" href="/docs/docs/mcp-server/tools/shopify-discount-find">
    Lists the store's discounts. Start here — every other tool needs an id from this one.
  </Card>

  <Card title="Read a discount" icon="file-text" href="/docs/docs/mcp-server/tools/shopify-discount-get">
    The full setup of one discount. Answers "why isn't this applying?"
  </Card>

  <Card title="Discount performance" icon="chart-line" href="/docs/docs/mcp-server/tools/shopify-discount-performance">
    Orders, revenue, and margin given away, for a date range.
  </Card>

  <Card title="Read the discount schema" icon="file-json" href="/docs/docs/mcp-server/tools/shopify-discount-config-schema">
    AIOD's templates and field shapes. Read before building anything.
  </Card>

  <Card title="Search the docs" icon="book-open" href="/docs/docs/mcp-server/tools/shopify-discount-docs-search">
    Setup, widgets, stacking, POS, troubleshooting.
  </Card>

  <Card title="Draft a discount" icon="pencil" href="/docs/docs/mcp-server/tools/shopify-discount-draft">
    Builds an offer and returns a review link. Writes nothing to Shopify.
  </Card>

  <Card title="Create in test mode" icon="rocket" href="/docs/docs/mcp-server/tools/shopify-discount-publish">
    Creates a real Shopify discount that only applies to your test email.
  </Card>
</CardGroup>

## At a glance

| Tool                             | Touches your store | Writes to Shopify        |
| -------------------------------- | ------------------ | ------------------------ |
| `shopify_discount_config_schema` | No                 | No                       |
| `shopify_discount_docs_search`   | No                 | No                       |
| `shopify_discount_find`          | Reads              | No                       |
| `shopify_discount_get`           | Reads              | No                       |
| `shopify_discount_performance`   | Reads              | No                       |
| `shopify_discount_draft`         | Reads              | No — stages a draft only |
| `shopify_discount_publish`       | Reads              | **Yes, in test mode**    |

Every read tool is marked read-only, so most clients allow them without asking. `shopify_discount_publish` is marked **destructive**, which means well-behaved clients will ask you before every single call.

<Note>
  Why is creating a discount "destructive"? Because of its update path. Creating a *new* discount is harmless. But passing an existing discount's id replaces that discount's rule and forces it back into test mode — so a discount that was live for shoppers stops applying. That is destructive, and it deserves a prompt.
</Note>

## Things that apply to every tool

### Discount ids

Every store-scoped tool needs an AIOD discount id, and the only place to get one is [Find discounts](/docs/mcp-server/tools/shopify-discount-find). It is not a Shopify discount GID. Never build one by hand.

### Configurations are sparse

Both write tools take a `config` object containing **only the fields you are setting**.

* **Creating** — the config must name a `template`.
* **Editing** — send only what changes. It is merged *onto* the stored configuration, not swapped in for it. So read the discount first: you cannot safely change a field without knowing its current value.

These shapes belong to AIOD. They are **not** Shopify's native discount API shapes and cannot be guessed from them. Anything invented gets rejected rather than quietly fixed.

### Rejections are useful, not fatal

When a tool returns a `4xx`, that is not a broken connection. It is a result to read.

A rejected draft or publish comes back with an `issues` list naming the exact fields at fault, and it carries the relevant reference material inline — so you can fix those fields and call again without starting over or re-fetching the schema.

| Code                          | What it means                                         | What to do                                                                   |
| ----------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
| `unsupported_template`        | The template is missing or not a real one.            | Pick one from the list attached to the rejection.                            |
| `edit_changed_nothing`        | Your patch matched the saved discount exactly.        | The change you meant to make wasn't in it. Look at the current config again. |
| `template_field_out_of_scope` | Every field you sent is uneditable for this template. | Stop. Tell the merchant the setting isn't available here. Don't retry.       |
| `tier_has_no_action`          | A tier ended up empty.                                | Each tier needs `conditions` and `actions` in the shapes from the reference. |
| `config_shape_parse_failed`   | A condition or action field has the wrong shape.      | Fix that one field. The exact syntax comes back with the error.              |
| `saved_rule_unavailable`      | The discount you're editing couldn't be read safely.  | Nothing was staged. Don't retry blindly.                                     |

And the HTTP statuses:

| Status                 | Meaning                                              |
| ---------------------- | ---------------------------------------------------- |
| `400`                  | Missing or unusable input.                           |
| `404`                  | That id isn't one of this store's discounts.         |
| `422`                  | The discount being edited couldn't be loaded.        |
| `200` with `ok: false` | Validation or simulation rejected it. Read `issues`. |

If AIOD's session for the store breaks — usually after an uninstall — every tool returns an error asking you to reconnect, rather than failing opaquely.

### Timeouts

One tool call, 60 seconds.

### Old tool names

The tools were renamed when they were namespaced. Clients are only ever offered the current names, but the old ones still work if you have them written down.

| Old                        | Current                          |
| -------------------------- | -------------------------------- |
| `get_aiod_context`         | `shopify_discount_config_schema` |
| `search_aiod_docs`         | `shopify_discount_docs_search`   |
| `find_discounts`           | `shopify_discount_find`          |
| `get_discount`             | `shopify_discount_get`           |
| `get_discount_performance` | `shopify_discount_performance`   |
| `save_discount_draft`      | `shopify_discount_draft`         |
| `publish_discount`         | `shopify_discount_publish`       |