Skip to main content
All Guides
Intermediate11 min read

Best Practices for AI Agent Discoverability

A full checklist for making your store discoverable, usable, and monitorable by AI shopping agents. Most stores only score around 30/100. The gap is usually operational, not theoretical.

Foundation layer

These are the baseline signals every agent stack still depends on, even when deeper protocol coverage exists.

JSON-LD schema markup

Focus on complete, consistent product schema:

Product

Required on every product page. Include name, description, price, currency, availability, brand, images, SKU, and GTIN where available.

Offer

Nested inside Product. Include price, priceCurrency, availability, seller, and sale logic that matches the rendered page.

Organization

Expose business identity, contact points, logo, and canonical URLs so agents can connect products to the merchant.

BreadcrumbList

Give agents store hierarchy and clean navigation context, especially for category and product pages.

Crawl and guidance files

  • Serve a valid XML sitemap and keep product URLs current
  • Keep robots.txt crawl-friendly for storefront pages while protecting admin and checkout
  • Publish llms.txt if you want model-specific navigation or policy guidance
  • Add AGENTS.md or Markdown-for-Agents when your store exposes richer agent workflows
  • Make sure product content is present in server-rendered HTML, not hidden behind JS-only rendering

Open Graph and content quality

  • Every product page needs og:title, og:description, og:image, and og:url
  • Use product-specific titles, descriptions, and images rather than global fallbacks
  • Keep pricing and availability synchronized between page copy and schema
  • Write structured descriptions that help agents compare products instead of guessing

Protocol layer

Protocols turn discoverability into usable actions. Cover as many as your stack supports without faking capabilities.

UCP manifest

  • Serve a valid JSON manifest at /.well-known/ucp
  • Expose browse, cart, checkout, and payment capabilities accurately
  • Keep manifest declarations synced with the real API
  • Verify endpoint responsiveness after deploys

ACP endpoint

  • Expose product discovery and transaction flows for ChatGPT-style commerce agents
  • Keep order and payment steps explicit instead of burying them behind HTML-only interactions
  • Validate behavior against the actual Stripe-backed transaction path

MCP

  • Expose store tools with clear names, input expectations, and stable endpoints
  • Use MCP where Claude-style agents need more than page scraping
  • Keep tool definitions versioned and auditable

WebMCP

  • Annotate forms with toolname and tooldescription
  • Add toolparamdescription to fields so agents know what each input means
  • Use toolautosubmit only when the submit behavior is deterministic and safe
  • Focus first on search, filter, cart, and checkout entry forms

A2A

  • Publish an agent card at /.well-known/agent.json
  • Declare capabilities that map to real store or support actions
  • List useful skills so other agents know when to hand work off
  • Keep the card versioned and aligned with your real deployment

Security posture

Agents do not just ask whether your store is reachable. They ask whether it looks safe to act on autonomously.

  • Serve HSTS to lock traffic to HTTPS
  • Use a clear Content-Security-Policy and avoid overly permissive defaults
  • Send X-Frame-Options and X-Content-Type-Options where appropriate
  • Expose rate-limit headers for public APIs and protocol endpoints
  • Document agent auth requirements instead of failing silently

Content quality

Good technical signals with weak product content still produce bad recommendations.

Clear product titles

Use specific titles with brand, variant, size, and material context where relevant.

Structured descriptions

Lead with facts agents can compare: dimensions, materials, compatibility, constraints, and use cases.

Accurate pricing

Keep rendered prices and structured prices aligned. Mismatches degrade trust quickly.

High-quality images with alt text

Use descriptive alt text and keep product imagery current, distinct, and accessible.

Consistent availability data

If inventory changes, update schema and page copy immediately so agents do not recommend unavailable products.

Testing and monitoring

Agent readiness is operational. Treat it like performance or uptime, not a one-time launch task.

  • Run a Colter Check after every deploy to catch regressions across 30+ signals
  • Use Colter Fix when you need platform-specific code for missing schema, manifests, or WebMCP form markup
  • Run Colter Test with Browser Shopper, Gemini Shopper, and The Edge Case to verify real journeys
  • Track score changes, protocol regressions, and agent traffic in Colter Lens
  • Retest after theme updates, plugin installs, platform migrations, or security changes

Common mistakes to avoid

Blocking AI crawlers in robots.txt or WAF rules

Stores often disable the exact bots that would have discovered their products. Allow storefront crawling intentionally.

Duplicate or conflicting schema

Multiple plugins or theme overrides can emit inconsistent product data, which makes agents distrust the page.

Stale protocol declarations

A manifest or agent card that advertises endpoints you no longer support is worse than no declaration at all.

Missing browser annotations on critical forms

If search, variant, or checkout forms are opaque, browser agents end up guessing at field meaning.

Not testing after changes

Theme updates, plugin updates, and security changes are common sources of silent regressions.

Your store is already being scored by AI agents

Run a Colter Check to see what they see across discovery, transaction, security, ecosystem, and content quality.

See What Agents See