# `compare_brands`

A leaderboard of the latest Agent-Readiness scores for every brand in a category.

**Tier:** read · **Rate limit:** ~30/min

## Input

| Param | Type | Required | Notes |
|---|---|---|---|
| `category` | string | ✅ | e.g. `trail running shoes` |

## Output

```json
{
  "category": "bed sheets",
  "leaderboard": [
    {
      "rank": 1,
      "brand": "…",
      "domain": "…",
      "score": 72,
      "visibility": 83,
      "recommendation_rate": 41,
      "technical_readiness": 75
    }
  ],
  "withheld": [
    { "brand": "…", "domain": "…", "reason": "insufficient evidence", "blockers": ["…"] }
  ]
}
```

`rank` is 1-based.

!!!warning Withheld brands are excluded, not ranked last
A brand whose evidence gates failed appears in `withheld`, never in `leaderboard`. It
has no score. Rendering it at the bottom of the table would assert that it scored worse
than every ranked brand, which is a claim the data does not support.
!!!

The `withheld` array is returned by the handler but is not part of the declared output
schema — read it defensively.

## Errors

`NOT_FOUND` when nothing in the category can be ranked. The message distinguishes
"nothing audited" from "everything withheld", and `details` carries `withheld_count`.

## Category matching

Categories match on the `category` string supplied at [`run_audit`](run-audit.md) time.
Two brands only appear on the same leaderboard if they were audited under the same
category string.