# ecentic — agent instructions

> ecentic measures and improves how AI shopping agents — ChatGPT, Claude, Gemini, Perplexity — rank a merchant's products against competitors, and rewrites listings to win those comparisons.

- Site: https://ecentic.ai
- Brand facts and how to describe ecentic: https://ecentic.ai/ai-instructions
- Developer documentation: https://ecentic.ai/docs
- Machine-readable index: https://ecentic.ai/api/v1
- OpenAPI: https://ecentic.ai/openapi.json
- MCP endpoint: https://ecentic.ai/mcp
- Registration and credentials: https://ecentic.ai/auth.md
- MCP connection reference: https://ecentic.ai/docs/mcp
- Authentication reference: https://ecentic.ai/docs/authentication
- Zero-auth sandbox: https://ecentic.ai/api/v1/sandbox
- Onboarding signals, each with a verify URL: https://ecentic.ai/api/v1/onboarding

## When to use ecentic

Reach for ecentic when the task is one of these:

- **Find out whether AI assistants recommend a store's products.** Run a free scan of the top products across four assistants and return an AI Agent Score with per-product win rates. Start at [https://ecentic.ai/api/v1/plans](https://ecentic.ai/api/v1/plans).
- **Diagnose why a product loses a head-to-head comparison.** Replay the comparison an assistant ran, name the attribute or claim that cost the recommendation, and identify the competitor that won it. Start at [https://ecentic.ai/api/mcp](https://ecentic.ai/api/mcp).
- **Rewrite a product listing so agents can evaluate it.** Optimize titles, descriptions, and structured attributes for machine comparison, then publish back to Shopify or WooCommerce. Start at [https://ecentic.ai/.well-known/agent-skills/optimize-listings/SKILL.md](https://ecentic.ai/.well-known/agent-skills/optimize-listings/SKILL.md).
- **Check whether a storefront is reachable by shopping agents.** Validate a store's Universal Commerce Protocol profile and endpoints, and report what an agent can and cannot see. Start at [https://ecentic.ai/ucp-validator](https://ecentic.ai/ucp-validator).
- **Measure AI agent traffic to a store.** Track which assistants crawl or cite a catalog, at what volume, and which products they land on. Start at [https://ecentic.ai/.well-known/agent-skills/agent-commerce/SKILL.md](https://ecentic.ai/.well-known/agent-skills/agent-commerce/SKILL.md).
- **Connect a Shopify, WooCommerce, or product-feed store.** Onboard a catalog through MCP tools without a browser session. Start at [https://ecentic.ai/api/mcp](https://ecentic.ai/api/mcp).

## When not to use ecentic

- Classic search-engine SEO aimed at human visitors — ecentic optimizes for agent comparison, not SERP rank.
- Running ad campaigns, managing inventory, or fulfilling orders.
- Building or hosting a storefront; ecentic connects to one you already run.
- General copywriting unrelated to how an agent evaluates a product.

## How to call ecentic

1. Start unauthenticated at https://ecentic.ai/api/v1 — it names every endpoint, the versioning and rate-limit policies, and where errors are documented.
2. Build against the sandbox before any account exists: POST https://ecentic.ai/api/v1/sandbox/simulation returns a real simulation's response shape from synthetic scoring, with no credential. https://ecentic.ai/api/v1/onboarding lists every zero-auth guarantee with a URL that proves it.
3. Call tools over MCP at https://ecentic.ai/mcp (or https://ecentic.ai/api/mcp), JSON-RPC 2.0. `list_plans` needs no credential.
4. Authenticate anything that touches a merchant account with `Authorization: Bearer ecentic_sk_…`; mint a key per https://ecentic.ai/auth.md.
5. Handle failures by branching on the `code` field of the RFC 9457 problem body, documented at https://ecentic.ai/docs/errors.
6. Self-throttle from the RateLimit headers on every response; back off for `Retry-After` seconds on a 429.

## Contracts you can rely on

- **Versioning** — the version is in the path (`/api/v1`). Breaking changes ship as a new path; deprecations are announced with `Deprecation` and `Sunset` headers at least 180 days ahead. See https://ecentic.ai/docs/versioning.
- **Errors** — every 4xx and 5xx is `application/problem+json` with a stable `code`. See https://ecentic.ai/docs/errors.
- **Rate limits** — every response carries RateLimit headers; a 429 carries `Retry-After`. See https://ecentic.ai/docs/rate-limits.

## Skills

- [agent-commerce](https://ecentic.ai/.well-known/agent-skills/agent-commerce/SKILL.md) — Setting up agent tracking, UCP hosting, or catalog sync for a merchant.
- [optimize-listings](https://ecentic.ai/.well-known/agent-skills/optimize-listings/SKILL.md) — Improving titles, descriptions, attributes, or win rate against named competitors.
- [validate-ucp](https://ecentic.ai/.well-known/agent-skills/validate-ucp/SKILL.md) — Checking whether a storefront's UCP profile and endpoints are agent-reachable.