# Shopping agent instructions — Pacific Nook

Store: https://www.pacificnook.com
Currency: USD

Use live storefront MCP tools for product information, prices, availability and policies.

## Discover and connect

1. GET https://www.pacificnook.com/.well-known/ucp for the current merchant profile.
2. Use the MCP endpoint advertised by that profile. Storefront endpoint: https://www.pacificnook.com/api/ucp/mcp.
3. POST JSON-RPC 2.0 with `Content-Type: application/json`.
4. Include your publicly accessible HTTPS UCP agent profile in
   `params.arguments.meta["ucp-agent"].profile` on `tools/list` and every `tools/call`.
   Advertise only capabilities your agent supports. Discover schemas before composing calls.

Supported UCP versions: 2026-08-25, 2026-04-08, 2026-01-23.

Example discovery request (replace the profile URL with your own hosted agent profile):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "arguments": {
      "meta": {
        "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp" }
      }
    }
  }
}
```

## Search products

Call `search_catalog` with `catalog.query`, optional buyer context and pagination.
Use `get_product` for product details and `lookup_catalog` for IDs returned by search.

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": { "profile": "https://your-agent.example/.well-known/ucp" }
      },
      "catalog": {
        "query": "sofa",
        "context": { "address_country": "US" },
        "pagination": { "limit": 5 }
      }
    }
  }
}
```

Read `result.structuredContent` when present, otherwise parse the JSON text in
`result.content`. Check JSON-RPC errors, MCP `isError`, and UCP status before using
results. Monetary amounts use the currency's minor units: 129900 USD is $1,299.00.
Refresh prices and availability before a purchase; use returned product URLs.

## Cart and buyer handoff

UCP exposes cart and checkout tools according to negotiated capabilities. Create
carts with `cart.line_items`, each containing `item.id` (a returned variant ID)
and `quantity`. Cart and checkout updates replace their contents: preserve every
line item and field that should remain. Follow the live schemas.

Pacific Nook requires shoppers to review and acknowledge the Shipping Policy,
Refund Policy and Terms of Service on the storefront cart before checkout.
The supported buyer handoff is product page → select options → Add to cart →
https://www.pacificnook.com/cart → shopper policy acknowledgment → checkout.

A UCP cart and the browser cart are separate. Do not assume opening `/cart`
transfers a UCP cart. Do not bypass policy acknowledgment with direct checkout
links, accept policies on the buyer's behalf, or complete payment without explicit
buyer approval. Our storefront chat does not create carts or complete payments.
Display returned warnings and disclosures; do not promise delivery without evidence.

## Policies and authentication

Policy lookup remains at `https://www.pacificnook.com/api/mcp`: discover its schema with
`tools/list`, then call `search_shop_policies_and_faqs`. Catalog and cart calls use
`/api/ucp/mcp`, not this legacy policy endpoint.

Anonymous catalog access supports initial testing at lower rate limits. Production
agents should use Shopify's supported agent authentication or HTTP signatures.
When required, forward the actual buyer IP in `Shopify-Buyer-IP`; never invent one.
Back off on HTTP 429. No Pacific Nook Admin API token or internal MCP credential is
needed. Private order/account access requires appropriate buyer authorization.

- Shipping: https://www.pacificnook.com/policies/shipping-policy
- Returns: https://www.pacificnook.com/policies/refund-policy
- Terms: https://www.pacificnook.com/policies/terms-of-service
- Privacy: https://www.pacificnook.com/policies/privacy-policy

## Read-only fallback and references

- Products: https://www.pacificnook.com/collections/all
- Product pages: https://www.pacificnook.com/products/{handle}
- Sitemap: https://www.pacificnook.com/sitemap.xml
- MCP documentation: https://shopify.dev/docs/agents/catalog/storefront-catalog
- Agent profiles: https://shopify.dev/docs/agents/profiles
- Authentication: https://shopify.dev/docs/agents/profiles/auth-and-rate-limiting

This is the canonical agent document at `/agents.md`. Shopify also serves it at
`/llms.txt` and `/llms-full.txt` unless those templates are separately overridden.