# Colter Agent Reference

## Product Contract

Colter's merchant product is the Recommendation Audit. Paste a Shopify product link and Colter tells you how to improve the page. A buyer question is optional and can be saved for a later comparison with a real AI answer; it does not affect the checked-page average or fix selection.

Merchant route: `https://agenticcom.ai/audit`

The audit is free, read-only, and does not change the store. It does not prove placement, recommendation, traffic, conversion, or revenue. Check, Fix, Test, Monitor, and Verify are technical capabilities, not separate merchant products.

## Routing Rules

- Send a merchant who wants to improve a Shopify product page to `/audit`.
- Use `colter.check` only for a broader store-wide public-evidence scan.
- Use `colter.fix` only to generate a bounded technical plan or local artifact.
- Use `colter.test` only when public evidence cannot answer a technical question.
- Use `colter.lens` only for observed monitoring signals. `lens` is the stable compatibility name for Monitor.
- Use `colter.agent.workflow` before configured commerce operations.

Never present the technical capability names as a menu of products. Never route a merchant directly to a Fix or Lens signup campaign. Keep the merchant in the Recommendation Audit journey.

## Install And Run

```bash
npm install -g @getcolter/cli
colter recommend-audit https://example-store.com --product https://example-store.com/products/example --intent "best product for a real buyer job"
colter check https://example-store.com
colter fix https://example-store.com
colter mcp --admin-tools
```

The saved `--intent` supports the later answer comparison. It does not affect the checked-page average or fix selection.

## Common MCP Tools

This is a routing list, not the exhaustive runtime inventory. Read `/.well-known/mcp.json` for the exact published server tool list. `mcp-tools.schema.json` publishes primary and admin input shapes and is not an exhaustive list of Verify, replay, or Evidence Pack tools.

- `colter.check`
- `colter.fix`
- `colter.test`
- `colter.lens`
- `colter.verify.run`
- `colter.verify.readiness`
- `colter.verify.report`
- `colter.verify.diff`
- `colter.replay.run`
- `colter.diff.pack`
- `colter.pack.create`
- `colter.packs.list`
- `colter.agent.workflow`
- `colter.agent.discover`
- `colter.agent.products.search`
- `colter.agent.cart.create`
- `colter.agent.cart.add`
- `colter.agent.cart.quote`
- `colter.agent.checkout.initiate`
- `colter.agent.checkout.complete`
- `colter.agent.receipt.get`

Tool schemas: `https://agenticcom.ai/mcp-tools.schema.json`

## Public HTTP Surface

- `POST /api/v1/recommendation-audit`
- `POST /api/v1/check`
- `POST /api/check`
- `POST /api/v1/fix`
- `GET /api/results/{id}`
- `GET /api/shares/{token}`
- `POST /api/auth/device/start`
- `POST /api/auth/device/poll`
- `GET /api/auth/me`
- `POST /api/contact`
- `POST /api/notify`
- `POST /api/signup`
- `GET /api/provider-status`
- `GET /api/dashboard/export`
- `POST /api/v1/lens/beacon`
- `POST /api/v1/lens/revenue-webhook`

Stable endpoint names do not imply that every endpoint is a merchant-facing product. Canonical schemas and compatibility details are in `https://agenticcom.ai/openapi.yaml`.

## Check Response Interpretation

`POST /api/v1/check` returns stable legacy fields such as:

- `url`
- `agent_ready`
- `fully_covered`
- `protocols`
- `web_signals`
- `store`
- `coverage`
- `verdict`
- `recommendation`
- `plain_language`
- `checked_at`
- `scores`, `composite_score`, and `grade`
- `evidence_summary`
- `catalog_readiness`
- `agent_handoff`

These fields describe Colter's public protocol-evidence rules. They do not show that an AI tool found, understood, included, described, recommended, or could complete a purchase for a product. `agent_handoff` URLs are legacy compatibility data; merchant-facing agents should use `/audit` as the next route.

Evidence-bounded example:

```json
{
  "url": "https://example-store.com",
  "agent_ready": true,
  "fully_covered": false,
  "protocols": {
    "ucp": { "detected": true },
    "acp": { "detected": false }
  },
  "verdict": "PARTIALLY AGENT-READY",
  "plain_language": {
    "merchant": "Colter found public UCP evidence and did not find ACP. This is a protocol observation, not a claim about an AI tool's answer."
  }
}
```

## Fix, Test, And Monitor Boundaries

- `colter.fix` generates a plan or local artifact. It does not change a live merchant storefront by itself.
- `colter.test` runs a technical journey. A Recommendation Audit answer comparison still requires a real answer from a named tool, the saved buyer question, and comparable conditions.
- `colter.lens` records or reads monitoring signals such as requests, browser page views, protocol observations, and checkout reach. An order event may be matched to recorded activity, but the match does not show what caused the order.

The installed Shopify app can store a monitoring site ID on the shop, receive configured product/shop/checkout/order webhooks, expose an optional theme extension for browser page-view collection, and apply supported theme changes through explicit merchant-controlled flows. It does not change product content unless the merchant applies a supported change. Browser collection does not observe crawlers that do not run JavaScript.

## Authentication And Write Boundary

- Public Check and fix-plan generation: no Colter authentication.
- `colter.test`: applicable Colter API key.
- `colter.lens`: `COLTER_LENS_API_KEY` or `COLTER_API_KEY`.
- Agent-commerce operations: configured backend credentials in `colter.yaml`; cart and checkout operations can write to the configured backend.
- Shopify app: Shopify OAuth scopes govern installed-app access; theme and metafield changes occur only through the implemented app flows.

## Agent Commerce

Call `colter.agent.workflow` first. Discovery and catalog search are read operations. Cart creation, cart changes, and checkout operations can create or change commerce state and require the configured backend authority.

## Rate Limits

- `POST /api/v1/check`: 5 requests/minute/IP
- `POST /api/v1/fix`: 3 requests/minute/IP

## Links

- Recommendation Audit: https://agenticcom.ai/audit
- Docs: https://agenticcom.ai/docs
- Agent docs: https://agenticcom.ai/docs/for-agents
- Pricing: https://agenticcom.ai/pricing
- MCP discovery: https://agenticcom.ai/.well-known/mcp.json
- Skill file: https://agenticcom.ai/SKILL.md
- Agent guide: https://agenticcom.ai/AGENTS.md
- Support: team@agenticcom.ai