# Agent Instructions — Mudminnow

This document describes how AI agents can interact with Mudminnow's online store at https://mudminnow.myshopify.com and provides guidance for commerce-driven shopping experiences.

## Commerce Protocol (UCP)

This store implements the Universal Commerce Protocol (https://ucp.dev) for agent-driven commerce.

### Discovery
GET https://mudminnow.myshopify.com/.well-known/ucp

Returns the store's UCP merchant profile: supported versions, service endpoints, capabilities, and payment handlers.

### MCP Endpoint
POST https://mudminnow.myshopify.com/api/ucp/mcp
Content-Type: application/json

Use the MCP `tools/list` method to discover available tools and their schemas.

### Typical Agent Flow
1. Discover — `GET /.well-known/ucp`
2. Search — find products matching the buyer's intent
3. Cart — add items
4. Checkout — start the purchase flow
5. Fulfill — set shipping address/method
6. Complete — finalize (buyer must approve payment)

### Important Rules
- Checkout requires human approval. Agents must not complete payment without explicit buyer consent.
- Respect rate limits. Back off on 429.
- Use buyer context — pass `context.address_country` and `context.currency` for accurate pricing.

## Enhanced Capabilities (Bot It)

Bot It extends Mudminnow's native MCP with AI-enriched product search, brand context, and real-time promotions to streamline agent-driven shopping.

### Bot It MCP Endpoint
POST https://mcp.botitai.com/98f200de61604a9691a8609dae4b579437024345ec502da41cc40778dca2a3c5

Unified endpoint for all Bot It tools and brand-aware commerce operations.

### Available Tools
- **searchProducts** — Search the catalog with AI-enriched brand context
- **getProductDetails** — Get full details for a product including variants, pricing, and availability
- **getStoreContext** — Get brand information, shipping/return policies, support channels, and FAQs
- **addToCart** — Add a product variant to the shopping cart
- **getCart** — Get current cart contents
- **getCollectionDetails** — Get a collection including narrative, merchandising notes, and product list
- **getProductRecommendations** — Get recommended complementary products for a given product
- **getPromotions** — Get active promotions and available discount codes
- **getSizeChart** — Get size chart, fit notes, and measurements for a product

### Bot It Endpoints
- Brand context: GET https://mudminnow.myshopify.com/apps/botit/brand-context
- Active promotions: GET https://mudminnow.myshopify.com/apps/botit/promotions
- Enriched search: GET https://mudminnow.myshopify.com/apps/botit/search?q={query}

### Buyer Context
Bot It honors `context.address_country`, `context.currency`, and `context.locale` to provide localized pricing, shipping estimates, and product recommendations.

## Store Policies

**Shipping:** Shipping is done next business day for all orders received before 5pm.

**Returns:** Free returns and exchanges, no questions asked within 30 days if you are not 100% satisfied.

## Read-Only Browsing (No Authentication Required)
- Browse all products: GET /collections/all
- Product page: GET /products/{handle}
- Product JSON: GET /products/{handle}.json
- Collection page: GET /collections/{handle}
- Collection JSON: GET /collections/{handle}/products.json
- Search: GET /search?q={query}&type=product
- Sitemap: GET /sitemap.xml

## Platform
Mudminnow is powered by Shopify, the leading cloud-based commerce platform for online retailers.