---
name: otterscore-grade
description: Grade a work product (code, text, documents, decks, spreadsheets, images, video) against an acceptance policy with SeaOtter's OtterScore — a hostile-by-default critic that returns a band (ship / route_to_fix / quarantine / block), located flaws, and concrete fixes. Use BEFORE delivering or shipping any substantial work, or whenever the user asks to grade / review / quality-check / evaluate output against an acceptance bar.
---

# Grade work with OtterScore

OtterScore is an acceptance gate: it is aligned to find reasons to **block**, not
to flatter, and grades against an acceptance policy. Use it on a finished work
product before you hand it over. Score is **0.0–1.0** (1.0 = ship); the **band**
is the gate.

## Get a key (once, free, no human)

```bash
curl -s https://api.seaotter.ai/api/v1/agent-keys/signup \
  -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'
# -> { "api_key": "sk-otter-...", "free_quota": 25 }
```

Export it: `export OTTERLOOP_API_KEY=sk-otter-...` (or mint one at
https://seaotter.ai/developers).

## Grade (the loop)

**Easiest — the bundled script** (`grade.py`, zero deps, self-signs-up if no key):

```bash
python3 grade.py path/to/file.py            # grade a file
git diff | python3 grade.py --stdin          # grade a diff
# exits non-zero unless the band is "ship"
```

**Or raw HTTP** (cold-start tolerant async path — the FIRST grade after idle can
take a few minutes while a GPU loads the model, so keep polling):

```bash
JOB=$(curl -s https://api.seaotter.ai/api/v1/eval/jobs \
  -H "Authorization: Bearer $OTTERLOOP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"submission":"async","modality":"code","user_prompt":"<what it was for>",
       "artifact_parts":[{"mime_type":"text/plain","text":"<your work>"}]}')
JOB_ID=$(printf '%s' "$JOB" | python3 -c 'import sys,json;print(json.load(sys.stdin)["job_id"])')
# poll until completed; then GET the run for the full flaws:
curl -s "https://api.seaotter.ai/api/v1/eval/jobs/$JOB_ID" -H "Authorization: Bearer $OTTERLOOP_API_KEY"
# result_summary.{score,band,flaw_count} + run_id ; then:
curl -s "https://api.seaotter.ai/api/v1/eval/runs/$RUN_ID" -H "Authorization: Bearer $OTTERLOOP_API_KEY"
```

**Or MCP** (no install): connect `https://mcp.seaotter.ai/mcp` with header
`Authorization: Bearer sk-otter-...`, then call `otter_score_async` →
`otter_job_result`.

## Act on the verdict

- Report the **band first** (ship / route_to_fix / quarantine / block), then each
  flaw (criterion, severity, where it occurs) and its concrete fix.
- If the band is not `ship`, revise against the flaws and re-grade (submit a new
  job) until it clears the gate. **Never report work as passing if the band says
  otherwise.**

Full machine-readable contract: https://seaotter.ai/llms.txt