generated: '2026-08-22'
method: probed
source: https://shop.hero.co/api/ucp/mcp (tools/list, 2026-08-22)
docs:
- https://shop.hero.co/agents.md
- https://shop.hero.co/llms.txt
- https://shop.hero.co/robots.txt
note: >-
  Derived from the live MCP tool input schemas plus the store's own published agent instructions.
  There is no OpenAPI to derive from; every statement below was observed on the wire or read from a
  document Hero Bread's host serves.
transport:
  protocol: MCP (JSON-RPC 2.0 over streamable HTTP)
  protocol_version: '2025-06-18'
  endpoint: https://shop.hero.co/api/ucp/mcp
  content_type: application/json
  accept: application/json, text/event-stream
authentication:
  see: authentication/hero-bread-authentication.yml
  summary: >-
    Anonymous for initialize/tools/list; every tools/call requires meta.ucp-agent.profile, and
    transactional tools additionally require a Shopify agent JWT.
idempotency:
  supported: true
  mechanism: request-field
  field: meta.idempotency-key
  type: string
  required_on:
  - complete_checkout
  scope: per checkout completion
  retention: not documented
  evidence: >-
    tools/list on https://shop.hero.co/api/ucp/mcp — complete_checkout declares
    meta.properties["idempotency-key"] with description "An idempotency key for completing the
    checkout" and lists it in meta.required alongside ucp-agent.
  note: >-
    complete_checkout is the only tool of the thirteen that requires an idempotency key. The
    remaining write tools (create/update/cancel cart and checkout) declare no idempotency field.
pagination:
  style: cursor
  applies_to: [search_catalog]
  request_field: catalog.pagination.cursor
  response_field: pagination.cursor
  evidence: >-
    search_catalog description — "Results are paginated, with initial results limited to improve
    experience. Use the pagination.cursor from the response to fetch additional pages."
money:
  representation: integer minor units + ISO 4217 currency code
  shape: '{"amount": 2500, "currency": "USD"} is $25.00'
  agent_rule: >-
    Convert to major units before quoting a price to a buyer — divide by 100 for two-decimal
    currencies; zero-decimal currencies such as JPY are already whole units.
  evidence: repeated verbatim in all 13 tool descriptions
identifiers:
  product: 'gid://shopify/Product/<id>'
  variant: 'gid://shopify/ProductVariant/<id>'
  note: Global relay-style IDs; lookup_catalog resolves several in one call.
buyer_context:
  fields: [context.address_country, context.currency]
  purpose: accurate pricing and availability
  source: https://shop.hero.co/llms.txt
versioning:
  scheme: dated protocol versions
  current: '2026-04-08'
  supported: ['2026-04-08', '2026-01-23']
  source: https://shop.hero.co/.well-known/ucp
error_envelope:
  see: errors/hero-bread-problem-types.yml
  format: JSON-RPC 2.0 error object
  shape: '{"jsonrpc":"2.0","id":N,"error":{"code":<int>,"message":<string>,"data":<string|object>}}'
rate_limit_signaling:
  see: rate-limits/hero-bread-rate-limits.yml
  documented: partial
  statement: 'The MCP endpoint is rate-limited per IP. Back off on 429 responses.'
  headers: not documented
human_in_the_loop:
  required: true
  statement: >-
    "Checkout requires human approval. Agents must not complete payment without explicit buyer
    consent." The robots.txt repeats it: no scripted form fills, browser automation, or end-to-end
    agent flows that finalize payment without an explicit, contemporaneous human approval step.
  sources:
  - https://shop.hero.co/llms.txt
  - https://shop.hero.co/robots.txt
dry_run_mode:
  supported: false
  grade: na
  note: No test/sandbox mode is published for this storefront; see sandbox coverage in the review.
reversibility:
  grade: documented
  note: >-
    Two reversal operations are published in the tool surface and both were observed in the live
    tools/list. Neither carries a stated time window in any document Hero Bread serves, so this
    grades `documented` rather than `verified` — a window is deliberately NOT asserted here because
    none is published. Post-purchase reversal (refunds) is governed by the store's refund policy
    page, which is prose and exposes no API operation.
  operations:
  - operation: cancel_checkout
    reverses: create_checkout / update_checkout
    kind: cancel
    window: not stated
    source: https://shop.hero.co/api/ucp/mcp (tools/list)
  - operation: cancel_cart
    reverses: create_cart / update_cart
    kind: cancel
    window: not stated
    source: https://shop.hero.co/api/ucp/mcp (tools/list)
  irreversible:
  - operation: complete_checkout
    note: >-
      No reversal tool is exposed for a completed checkout. There is no refund, void or
      cancel_order tool in the 13-tool surface; get_order is read-only. Post-purchase reversal is a
      human/customer-service path under the published refund policy.
    refund_policy: https://shop.hero.co/policies/refund-policy