# multipov.ai — agent rules

> Contract for AI agents calling multipov. Read this before invoking tools.

## What multipov does

Orchestrates multi-persona, multi-LLM document reviews. Agents submit a
doc + optional persona panel; the server fans out to per-persona LLM
calls, deduplicates findings, and returns a consensus-ranked report.

## Authentication

All write tools require a bearer API key. Mint at:
https://multipov.ai/admin/api-keys (admin-only) or have an admin grant
one to your account. Key format: `mpov_live_*` (production) or
`mpov_test_*` (sandbox).

Pass via:
- HTTP `Authorization: Bearer mpov_live_...` for direct REST
- MCP server `MULTIPOV_API_KEY` env var

Quotas (per-key, per-day):
- 25 reviews/day total (tighter caps on deep mode: 5/day)
- 25 concurrent in-flight reviews max
- /day global cost cap (server-wide, kicks in around large fanouts)

## Required call sequence for reviews

The review tools are fire-and-poll, not synchronous:

1. `submit_review` (or plan/pipeline/codebase/fact-check/visual variant)
   → returns `{ job_id, estimated_seconds, selected_personas }`
2. `get_review_status({ job_id, wait_seconds: 20 })`
   → server long-polls; call in a loop until `status === "complete"`,
   `"failed"`, or `"cancelled"`
3. `get_review_report({ job_id })`
   → returns the final `{ executiveSummary, consensusFindings,
   disputedFindings, singleModelFindings, personaResults, warnings }`

Always honor `recommended_poll_interval_ms` from `get_review_status`.

## Key tools

| Tool | Use for |
|------|---------|
| `submit_review` | Business docs, pitches, marketing copy |
| `submit_plan_review` | Design docs, RFCs, architecture proposals |
| `submit_pipeline_review` | Code diffs (PR-style) |
| `submit_codebase_review` | Full repos / large code dumps |
| `submit_fact_check` | Multi-LLM fact verification on long-form text |
| `submit_visual_review` | UI/UX/iOS visual review (screenshots) |
| `list_personas` | Browse the 1,400+ reviewer pool |
| `recommend_personas` | Get auto-routed panel for a topic |
| `cancel_review` | Cancel in-flight; idempotent |
| `list_my_reviews` | Your own review history (no other users') |

## Modes

- `quick` — Claude-only primary panel, ~30s. Cheapest.
- `deep` — 4-LLM fanout (Claude + GPT-4o + Gemini + Grok), ~2-5 min.
  Counts against the 5/day deep cap.

## Persona panels

Default: content-aware 8-person panel (5 technical + 3 outside perspective).
Override with `personas: [...]` array of explicit persona ids. Use
`dry_run: true` to preview the auto-selected panel without consuming
quota or scheduling the review.

## Disproval (cross-architecture filter)

By default, every review runs through a disproval panel after the primary
panel completes. 3 cross-architecture disprovers attempt to refute every
Critical/High finding; refuted findings move to `droppedByDisproval`
(always shown for audit, never silently hidden). Pass `disprove: false`
to skip per-request.

## Errors you'll see

- `invalid_input` — missing/oversize content; check `details`
- `rate_limited` — quota or concurrency cap hit; `details.kind` says which
- `cost_cap_reached` — server-wide daily cap; `details.reset_at` has rollover
- `not_found` — unknown job_id, owned by another user, or corrupt record
  (indistinguishable for security)
- Per-persona `failed` status with `error.kind` ∈ `{ missing, failed, ...
  Per-job retry budget exhausted ... }` — provider rate-limit cascade
  (todo #29 / #32 fix in flight)

## What NOT to do

- Don't poll `get_review_status` faster than `recommended_poll_interval_ms`
- Don't retry submit_review on a 429 — back off; concurrency cap is real
- Don't pass `personas` for the primary panel unless you have a specific
  reason; the content-aware router is usually better than your guess
- Don't act on a `partial: true` report without checking `completedPersonas`
  vs `totalPersonas` — a 2/8 partial may have happened due to the cascade
  bug above and findings may be incomplete

## Source

https://github.com/capitalthought/multipov