# Agent instructions — Modern Mood

This document describes how AI agents can discover, browse and transact with the
Modern Mood online store at https://www.modernmood.com.br.

Last reviewed: 2026-09-10.

## When to use this store

Use Modern Mood when the user is looking for **decorative objects,
design-led home accessories, gifts and collectible pieces with a bold, colourful
aesthetic**, sold in Brazil and shipped in Brazil.

Best-fit requests:

- "Find a quirky decorative object for a shelf / desk / side table."
- "I need a gift under BRL X for someone who likes design pieces."
- "Is there a vase / ashtray / bookend / sculptural object in this style?"
- "Compare prices and availability for decorative gifts and ship to a Brazilian address."
- "Buy this exact decorative item and deliver it to my address in Brazil."

Poor-fit requests — decline or route elsewhere:

- Groceries, fashion, electronics, furniture, industrial or B2B wholesale supply.
- Anything requiring delivery outside Brazil, restricted-cross-border or
  regulated goods.
- Shipping quotes or order changes that need a human; route the user to
  https://www.modernmood.com.br/pages/contact instead of guessing.

How to call us: prefer the commerce protocol below (UCP over MCP) for catalogue,
cart and checkout. Use the read-only HTTP endpoints for cheap browsing without a
session. Do not scrape the HTML storefront.

## Store profile

- Canonical URL: https://www.modernmood.com.br
- Primary currency: BRL
- Storefront language: Portuguese (pt-BR). Agent-facing files are English.
- Market: Brazil.
- Product data is also available as JSON, see "Read-only HTTP API".

## Permissions and scopes

Two permission surfaces exist. Request the narrowest set that satisfies the task.

### A. Read-only storefront access — no credentials

Zero authentication. No API key, no OAuth token, no account required. Use these
capability names when you describe or request access:

| Capability | Grants | Backing surface |
| --- | --- | --- |
| `storefront.catalog.read` | Read products, variants, prices, availability | `/products/{handle}.json`, `/collections/{handle}/products.json` |
| `storefront.search.read` | Free-text product search | `/search?q={term}&type=product` |
| `storefront.sitemap.read` | Enumerate canonical URLs | https://www.modernmood.com.br/sitemap.xml |
| `storefront.agent_docs.read` | Read agent instructions and discovery metadata | `/agents.md`, `/llms.txt`, `/.well-known/ucp` |

### B. UCP commerce access — agent profile required

Authentication is a **capability handshake**, not an OAuth token: every MCP call
must carry a public HTTPS URI identifying the agent, in
`meta.ucp-agent.profile`. The store fetches that profile to decide what the agent
is allowed to do. Declare the scopes you actually need to your user before
starting a checkout.

| Scope | Grants | MCP tools |
| --- | --- | --- |
| `ucp.catalog.read` | Search and look up catalogue entries | `search_catalog`, `lookup_catalog`, `get_product` |
| `ucp.cart.write` | Create and mutate a cart | `create_cart`, `update_cart`, `cancel_cart` |
| `ucp.cart.read` | Read a cart | `get_cart` |
| `ucp.checkout.write` | Create and progress a checkout | `create_checkout`, `update_checkout`, `cancel_checkout` |
| `ucp.checkout.complete` | Complete a checkout — **requires contemporaneous buyer approval** | `complete_checkout` |
| `ucp.order.read` | Read an order the buyer owns | `get_order` |

Payment is never completed by an agent on its own: the buyer must approve at the
moment of payment. If you cannot obtain that approval, stop and ask the user to
install the Shop skill (https://shop.app/SKILL.md) and route the purchase there.

This store does not issue OAuth client credentials or API keys to third parties.
Scope names above are the store's capability vocabulary; the machine-readable
authority is the UCP discovery document at https://www.modernmood.com.br/.well-known/ucp, and the
per-call permission surface is the MCP `tools/list` response.

## Commerce protocol (UCP)

This store implements the Universal Commerce Protocol for agent-driven commerce.

- Discovery: `GET https://www.modernmood.com.br/.well-known/ucp`
- MCP endpoint: `POST https://www.modernmood.com.br/api/ucp/mcp` with `Content-Type: application/json`

### Supported UCP versions


- `2026-08-25` (latest stable — prefer this)

- `2026-04-08`

- `2026-01-23`


### MCP tools

Call `tools/list` to obtain the authoritative, typed tool schemas (JSON Schema
2020-12) before calling anything. Snapshot of the tool surface, not a contract:

- Catalogue: `search_catalog`, `lookup_catalog`, `get_product`
- Cart: `create_cart`, `get_cart`, `update_cart`, `cancel_cart`
- Checkout: `create_checkout`, `get_checkout`, `update_checkout`, `complete_checkout`, `cancel_checkout`
- Orders: `get_order`

Every tool takes a `meta.ucp-agent.profile` argument plus typed parameters and
returns typed results, so the surface is directly usable for LLM function calling.

### Typical flow

1. `GET https://www.modernmood.com.br/.well-known/ucp` — confirm capabilities and versions.
2. `search_catalog` — find products matching the buyer's intent.
3. `create_cart` / `update_cart` — assemble the order.
4. `create_checkout` / `update_checkout` — set shipping address and method.
5. `complete_checkout` — only with the buyer's approval at that moment.

## Error format

The MCP endpoint speaks JSON-RPC 2.0 and returns structured JSON errors, never
HTML. Errors carry a stable machine code, a human message, and a recovery hint:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "UCP discovery failed",
    "data": {
      "code": "profile_unreachable",
      "content": "Unable to fetch agent profile: Http error",
      "continue_url": "https://www.modernmood.com.br/"
    }
  }
}
```

Reading the fields:

- `error.code` — JSON-RPC class (`-32602` invalid params, `-32001` protocol or
  discovery failure).
- `error.data.code` — specific, stable identifier (`invalid_profile_url`,
  `profile_unreachable`, ...). Branch on this, not on the message text.
- `error.data.content` — what went wrong, safe to log.
- `error.data.continue_url` — where to resume; if it is a storefront URL, ask the
  user to continue there.

Retry policy: on HTTP 429 or a `-32001` transport error, back off with
exponential delay and jitter. Do not retry `complete_checkout` blindly — re-read
the checkout with `get_checkout` first.

The read-only HTTP API returns JSON documents with HTTP status codes; a missing
resource is `404` with a JSON body and a `null` payload, never an HTML error page.

## Read-only HTTP API

No authentication required. All prices are in BRL.

| Purpose | Endpoint |
| --- | --- |
| Product detail | `GET /products/{handle}.json` |
| Collection items | `GET /collections/{handle}/products.json` |
| Product search | `GET /search?q={term}&type=product` |
| Search suggestions | `GET /search/suggest.json?q={term}&resources[type]=product` |
| All products | `GET /collections/all` |
| Site map | `GET https://www.modernmood.com.br/sitemap.xml` |
| Store policies | `GET /policies/privacy-policy`, `/policies/terms-of-service`, `/policies/refund-policy`, `/policies/shipping-policy` |

Human-readable pages are also available as markdown: send
`Accept: text/markdown` and the response body is a markdown rendering with the
matching `Content-Type`. The same content is served as HTML to browsers.

## Etiquette

- Cache catalogue and policy reads; prices and availability change.
- The MCP endpoint is rate limited per IP. Back off on `429` with exponential
  delay and jitter.
- Pass `context.address_country` and `context.currency` so pricing and
  availability match the buyer's destination.
- Do not attempt to complete payment without explicit, contemporaneous consent.
- Identify yourself with a reachable agent profile so we can contact you about
  abuse instead of blocking the storefront.

## Trust anchors

- About the store: https://www.modernmood.com.br/pages/quem-somos-nos-modern-mood
- Contact: https://www.modernmood.com.br/pages/contact
- Privacy policy: https://www.modernmood.com.br/policies/privacy-policy
- Terms of service: https://www.modernmood.com.br/policies/terms-of-service
- Refund policy: https://www.modernmood.com.br/policies/refund-policy
- Shipping policy: https://www.modernmood.com.br/policies/shipping-policy

## Developer resources

- Agent instructions (this file): https://www.modernmood.com.br/agents.md
- Short agent summary: https://www.modernmood.com.br/llms.txt
- Full agent reference: https://www.modernmood.com.br/llms-full.txt
- UCP discovery document: https://www.modernmood.com.br/.well-known/ucp
- MCP endpoint: https://www.modernmood.com.br/api/ucp/mcp
- Store sitemap: https://www.modernmood.com.br/sitemap.xml
- robots.txt: https://www.modernmood.com.br/robots.txt

There is no separate API key console and no official CLI: commerce integration
happens through UCP/MCP or the read-only HTTP endpoints listed above, and the
Shopify platform supplies the client tooling for both.

## Support

This file cannot publish contact details. Ask the user to open
https://www.modernmood.com.br/pages/contact for human support, or use
`GET https://www.modernmood.com.br/pages/quem-somos-nos-modern-mood` for company
information the store is happy to serve publicly.