Diagnostic: who is this request authenticated as, and is a Clover tenant mapped to them?

Returns the authenticated identity, the names of available token claims (never their values), scopes, and whether a tenant is provisioned — no Clover data and no secrets. Use it when setting up multi-tenant to discover which identity claim your platform (e.g. FastMCP Cloud / Horizon) actually provides, so you can key CLOVER_TENANTS_JSON correctly.

Return key information about this Clover merchant.

Includes name, address, currency, timezone, country, and business type. Also primes the internal currency and timezone cache used by all other tools.

Return an aggregated sales summary for the given date window.

Defaults to today (UTC) when no dates are supplied. Uses 90-day chunking so multi-month or full-year queries work transparently (emits progress logs when more than one window is scanned).

Rules: only result=SUCCESS payments counted; voids/refunds reported separately; tips, taxes broken out; offline payments flagged; currency from merchant record. This tool does NOT support payment capture, refund, or void actions.

List payments within an optional date window (default: today, limit 50).

Only result=SUCCESS payments. Card transaction details never included. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist). This tool does NOT support payment capture, refund, or void actions.

List refunds within an optional date window (default: today, limit 50).

Clover refunds are separate objects with a positive amount (cents), not negative payments. Card/transaction detail is never included. Requires PAYMENTS_R. This tool does NOT issue refunds.

Return the merchant's credits (store/account-credit adjustments, up to 1000).

Element shape is unverified (sandbox has none provisioned) — shaped conservatively. Requires PAYMENTS_R.

Return gross sales grouped by employee for a date window (default: today).

Requires PAYMENTS_R; employee name enrichment additionally requires EMPLOYEES_R (degrades to IDs-only with a note if not granted).

Return a tip-out sheet: tips collected grouped by employee (default: today).

Requires PAYMENTS_R; employee name enrichment additionally requires EMPLOYEES_R (degrades to IDs-only with a note if not granted).

Return gross sales bucketed by local hour-of-day for a single day (default: today).

Buckets use the merchant's local timezone, falling back to UTC with a note if unavailable. Requires PAYMENTS_R.

List orders within an optional date window and/or state filter (default: today, limit 50).

state: open | paid | refunded | partially_refunded (omit for all states). Customer card data is never included. This tool is read-only. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Fetch a single order by ID, including line items and payment summary.

Expands lineItems and payments only. Customer card data never expanded. Returns a 404 error if the order_id does not exist. This tool is read-only.

Return all currently open orders for this merchant (up to 200).

Convenience wrapper — no date filter, state=open only. Customer card data is never included. This tool is read-only.

Return a page of inventory items. Filter by name (query) or category (category_id).

Requires INVENTORY_R. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Return a single inventory item by ID, including stock quantity.

Pass include=["modifier_groups"], ["tax_rates"], ["categories"], and/or ["tags"] to opt in to those association details. Requires INVENTORY_R.

Return all items whose stock quantity is at or below threshold.

Items with no stock tracking are excluded. Requires INVENTORY_R.

Return all inventory categories. Requires INVENTORY_R.

Return all modifier groups with their modifiers. Requires INVENTORY_R.

Return item groups (sets of item variants, e.g. size/color). Requires INVENTORY_R.

Return the merchant's tax rates (raw rate + computed percent). Requires INVENTORY_R.

Return the merchant's discount catalogue (fixed-amount or percentage). Requires INVENTORY_R.

Return the merchant's Clover devices/terminals. Requires MERCHANT_R.

Return the merchant's tender types (payment methods: cash, credit, custom). Requires MERCHANT_R.

Return the merchant's POS configuration (currency, tips, stock tracking, closeout, locale, support contacts). Banking/account fields are never returned. Requires MERCHANT_R.

Return the merchant's order types (Dine In, Take Out, …). Requires MERCHANT_R.

Return the merchant's opening-hours sets (per-day time ranges). Requires MERCHANT_R.

Return the merchant's tip-suggestion presets (percentage or flat amount). Requires MERCHANT_R.

Return the merchant's default service charge configuration (name, enabled, percentage). Requires MERCHANT_R.

Return recent cash-drawer events (paid in/out, no-sale, deposits).

Capped at limit (default 50, max 500). Requires MERCHANT_R.

Return item attributes (variant axes like Size/Color) with options. Requires INVENTORY_R.

Return the merchant's tags/labels used to group items. Requires INVENTORY_R.

Return the best-selling items in a date window, ranked by units sold.

Defaults to today (UTC); 90-day chunked. Each line item counts as one unit. Requires ORDERS_R.

Return a page of employees (PINs never returned). Requires EMPLOYEES_R.

Return a single employee by ID (PINs never returned). Requires EMPLOYEES_R.

List shifts, optionally by employee and/or date window. Requires EMPLOYEES_R.

Without employee_id, aggregates shifts across all employees.

Return currently open shifts (clocked in, not out) across all employees. Requires EMPLOYEES_R.

Return the merchant's employee roles (name + system role category). Requires EMPLOYEES_R.

Search customers by full name (query), phone, or email.

Cards are never returned. Requires CUSTOMERS_R. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Return a single customer by ID.

Pass include=["addresses"] or include=["orders"] to opt in to optional fields. Cards are never returned. Requires CUSTOMERS_R.

AI: plain-language sales briefing for a date window (default: today).

Gathers the sales summary + top items, then asks your client's model to write a short narrative. Read-only suggestion. Needs a sampling-capable client; if yours can't sample, returns the raw data with a note. Requires ORDERS_R/PAYMENTS_R.

AI: suggest categories for uncategorized items from the merchant's own taxonomy.

Suggestion only — applying a category is a separate, confirmed write. Needs a sampling-capable client (graceful fallback otherwise). Requires INVENTORY_R.

AI: prioritized reorder list — low-stock items crossed with sales velocity.

Read-only suggestion. Needs a sampling-capable client (graceful fallback otherwise). Requires INVENTORY_R and ORDERS_R.

AI: flag unusual refund / discount / sales patterns in a window (default: today).

Read-only analysis. Needs a sampling-capable client (graceful fallback otherwise). Requires PAYMENTS_R and ORDERS_R.

AI: draft a customer message (promo / win-back / thank-you) for the given intent.

Returns a DRAFT only — never sends anything. Needs a sampling-capable client (graceful fallback otherwise). Requires CUSTOMERS_R.

Modifies merchant data. Create a new customer record in Clover.

Idempotency guard: searches for an existing customer with the same email or phone before creating. If a match is found and confirm_duplicate is False, the call is refused and the existing match is returned.

dry_run=True returns the would-be POST payload without sending it. Requires CUSTOMERS_R (duplicate check) and CUSTOMERS_W (write).

Modifies merchant data. Set an item's price (in cents, absolute value).

Optimistic lock: refuses the write unless the item's current price equals expected_current_price_cents (prevents stale-context overwrites). Bounds: 0 <= new_price_cents <= 100_000_000. dry_run=True previews the PUT body (still performs one read to fetch current price/name) and never writes. Requires INVENTORY_R and INVENTORY_W.

Modifies merchant data. Set an item's stock to an ABSOLUTE quantity (not a delta).

Optimistic lock: refuses unless current stock equals expected_current_quantity. Bounds: 0 <= new_quantity <= 1_000_000. dry_run=True previews the PUT body (still performs one read to fetch current stock) and never writes. Requires INVENTORY_R and INVENTORY_W.

Modifies merchant data. Create a new inventory category.

Previews on dry_run; confirms via your client's prompt (MCP elicitation) or confirm=True before writing. Requires INVENTORY_W.

Modifies merchant data. Create a new inventory item (name + price in cents).

Bounds 0–100_000_000 cents. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Modifies merchant data. Create a new open order (no line items, no payment).

Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Add items with add_line_item. Requires ORDERS_W.

Modifies merchant data. Add a catalog item as a line item to an order.

Name/price are copied from the catalog item. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires ORDERS_W. No payment.

Modifies merchant data. Update a customer's name and/or marketing opt-in.

Only the fields you pass change. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires CUSTOMERS_W.

Modifies merchant data. Apply an order-level discount.

Exactly one of percentage (1-100), amount_cents (1-100_000_000, positive — Clover requires a negative amount on the wire, this tool negates it for you), or catalogue_discount_id must be given. Catalogue discounts are resolved client-side (name + percentage/amount fetched from list_discounts and sent inline). Previews on dry_run (includes current discounts + a client-computed line-item subtotal — Clover has no computed order total); confirms via MCP elicitation or confirm=True before writing. Requires ORDERS_W.

Modifies merchant data. Rename an inventory item (price/other fields preserved).

Optimistic lock: refuses unless the item's current name equals expected_current_name. Bounds: non-empty, <= 127 characters. dry_run=True previews the POST body (still performs one read) and never writes. Requires INVENTORY_R and INVENTORY_W.

Modifies merchant data. Create a new modifier group (e.g. "Milk options").

Duplicate guard: refuses if a group with the same name (case-insensitive) already exists. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Modifies merchant data. Create a new modifier within a modifier group.

Pre-check: verifies the modifier group exists (404 -> clear error). Bounds: 0 <= price_cents <= 100_000_000. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Modifies merchant data. Create a new tag/label used to group items.

Duplicate guard: refuses if a tag with the same name (case-insensitive) already exists. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.