# AOO — Agent Operability Optimizer

Version 2.0.0. Base URL: https://daas-aoo.listeningmind.ai

## What this measures

AOO sends a real LLM agent at a website with a concrete task and instruments
every tool call: the URL fetched, the HTTP status, and — the part that matters —
how the agent learned that URL. Each fetch is labelled with one of:

  link, sitemap, llms_txt, robots_txt, earlier_response, web_search,
  model_recall, other

The first four mean the site guided the agent. The rest mean it did not, and the
agent found its way from outside. Every score is derived from that distribution
plus the HTTP status profile. Nothing is inferred from a static crawl.

Labels are assigned server-side from observed evidence. The model never labels
its own steps, so the same trajectory always produces the same score.

## Authentication

None. All endpoints are keyless and rate limited per IP.

## Endpoints

  GET  /api/v1                     service descriptor
  GET  /api/v1/goals               the goal + category catalog behind the score
  POST /api/v1/scan                run a full site audit (202 + poll URL)
  GET  /api/v1/scan/stream         run an audit, stream progress as SSE
  GET  /api/v1/score/{domain}      latest stored score, never triggers a scan
  GET  /api/v1/audits/{audit_id}   the full report
  POST /api/v1/traces            run one agent task
  GET  /api/v1/traces/{run_id}   one recorded trajectory, step by step
  GET  /api/v1/history             domains analysed and score trends
  GET  /api/v1/badge/{domain}      SVG score badge

OpenAPI: https://daas-aoo.listeningmind.ai/api/openapi.json

## Typical flow

1. GET  /api/v1/score/{domain}       — is there already a score?
2. POST /api/v1/scan {"url": "..."}  — if not, or if you want a fresh one
3. GET  /api/v1/audits/{audit_id}    — poll until status is "done"
4. Read findings[] worst-first, then synthesis.recommendations
5. Fix, then POST /api/v1/scan with {"force": true} to re-measure

## Scoring

Four categories, 100 points total:

  discovery    20
  access       30
  navigation   30
  completion   20

Each is earned by goals:

  enter                  access      probe
  welcome                access      probe
  guidance               discovery   probe
  readable               navigation  probe
  intent:pricing         completion  trace
  intent:signup          completion  trace
  intent:api-docs        navigation  trace
  intent:get-started     navigation  trace
  intent:support         completion  trace
  intent:shipping        completion  trace
  intent:contact         completion  trace
  intent:fees            completion  trace
  intent:eligibility     completion  trace
  intent:booking         completion  trace
  intent:locations       completion  trace
  intent:stock           completion  trace
  intent:careers         completion  trace
  intent:policy          completion  trace
  intent:compare         completion  trace
  intent:latest          completion  trace
  intent:docs            completion  trace
  intent:civil           completion  trace
  intent:processing      completion  trace
  intent:products        completion  trace
  intent:nutrition       completion  trace
  intent:retailers       completion  trace

Available intents: pricing, signup, api-docs, get-started, support, shipping, contact, fees, eligibility, booking, locations, stock, careers, policy, compare, latest, docs, civil, processing, products, nutrition, retailers

## Two harnesses

fetch-agent reads raw HTML — what most AI assistants actually see.
playwright-agent renders first — what a person sees.

The gap between the two scores is the rendering gap a client-rendered site pays.
A request for the rendering harness is refused when it is not installed rather
than silently downgraded, because a run mislabelled as rendered would poison any
comparison.

## What AOO does not do

It does not submit forms, log in, create accounts, or make purchases. It reads.
It obeys robots.txt, identifies itself as AOO-Bot, and makes at most one request
per second per host. To block it: User-agent: AOO-Bot / Disallow: /
(Rules written for its former name, AGO-Bot, are honoured as well.)

It also does not measure payment rails, third-party rankings or reviews.
Those fields are absent rather than guessed.

## Versioning

major = a stable field removed, renamed or changed in meaning
minor = additive fields, goal-catalog membership changes
patch = spec corrections

Pin the major. Gate CI on explicit goal ids or a score threshold, not on
category totals.

## Agent tools (ListeningMind agent hub)
- [MCP server](https://daas-aoo.listeningmind.ai/mcp): Streamable HTTP. All UI functions as tools, plus app_guide
- WebMCP: every page registers the same tools for browser agents (document.modelContext)
- [OpenAPI](https://daas-aoo.listeningmind.ai/.well-known/openapi.json) · [agents.md](https://daas-aoo.listeningmind.ai/agents.md) · [API catalog](https://daas-aoo.listeningmind.ai/.well-known/api-catalog)
- Accounts: reading results is open. Starting a run or changing data needs a ListeningMind member ([sign up](https://daas-aoo.listeningmind.ai/_lm/auth/signup)). Over MCP, runs return confirm_url for a signed-in member to approve; other changes need the member's agent key in the LM-User-Key header (https://daas-aoo.listeningmind.ai/_lm/account)