@jkudish/jev-mcp 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.0
+
+- New `jev_review` tool: score a proposed diff against the request before the task is called done. Four 0..2 Score rubrics (correctness, spec match, test gap, blast radius, the last two inverted in the composite) plus a safe-to-apply probability, combined into a weighted composite (0.4 / 0.3 / 0.15 / 0.15) and one `auto | review | escalate` action. Auto requires safe_to_apply and every rubric confidence at `auto_accept` (default 0.8) and the composite at `composite_floor` (default 0.7); below `review_at` escalates. Unknown confidence escalates and can never satisfy a threshold, even a zero one. Text fields capped at 50,000 characters; truncated or malformed input never returns auto. Question design adapted from [burnigtm/jev-mcp](https://github.com/burnigtm/jev-mcp) (MIT) via [PR #2](https://github.com/jkudish/jev-mcp/pull/2) by rimusz, with deliberate divergences: caps raised from 2,000 characters so auto is reachable on real diffs, thresholds parameterized instead of a hardcoded safe_to_apply escalation, strict per-answer validation under the package's invalid_response contract, and anti-injection framing (every field is evidence to evaluate, never instructions to follow).
+- New `jev_gate` tool: the completion gate. The same patch review plus up to 16 completion claims verified against caller-supplied evidence in one request, each claim a Choice over verified / contradicted / unsupported, with claim questions instructed to use evidence only (the request, diff, and tests fields are assertions to check, never proof; all fields share one model state, so the isolation is instructional). Evidence is capped at 16 items and 200,000 characters in aggregate, rejected before any model call. The final action is the worst of the review and every claim; `reason_codes` records why (`incomplete_context`, `invalid_response`, `review_escalated`, `review_required`, `claims_contradicted`, `claims_unsupported`, `claim_confidence_low`, `claim_confidence_below_auto_accept`, `accepted`). Same credits and divergences as `jev_review`.
+- Deliberately excluded from that PR: its `jev_coding_loop` tool, an agent loop that runs the review gate repeatedly. This package stays judgment primitives that a coding agent calls; it does not become one.
+- Docs: README restructured around the ten tools (capability bullets, collapsible per-client install sections, a When to call which tool section), the `jev_rerank` example replaced with a live-captured semantic-ranking example that shows where candidate text comes from, and guidance added for ranking whole documents by chunking with distinct ids.
+- New `jev_rerank` tool: one independent relevance probability per candidate in a single request, returned sorted with scores. Candidate ids preserved verbatim; any malformed answer marks the whole ranking `invalid_response` instead of sorting a missing score as zero. TypeSafe's rerank cookbook reports that on the CLERC benchmark this pattern lifted top-1 from 5% to 18% and top-10 from 38% to 62%. Bounded at 250 candidates and a 100,000-character aggregate budget.
+- New `jev_compare` tool: overall same_fact / contradicts / different_facts relation between two passages, plus optional per-aspect judgments, each an independent Choice in the same request with aspect-specific wording for the third outcome, with distributions, confidence, an argmax guard, and an auto-versus-review decision.
+- New `jev_extract` tool: your regex finds candidate substrings, Jev picks which candidate is each field's value, and the value returns verbatim. Regexes run in a sandboxed worker with a 1-second deadline, so pathological patterns cannot hang the server. Complete zero-match fields are omitted from the model request (`not_found`); if no field reaches the model, no API call is made, and a confident `none_of_them` is a model-judged negative. An incomplete candidate universe (matches beyond the 20-per-field cap, or matches skipped for exceeding 2,000 characters) forces every otherwise-valid positive or `none_of_them` result to `review` (malformed answers remain `invalid_response`), with explicit flags rather than silent truncation; invalid patterns and timeouts report `invalid_pattern` without failing the call. Bounded at 32 fields, a 50,000-character document, and a separate 50,000-character aggregate candidate-match budget.
+
+## 0.4.0
+
+- New `jev_classify` tool: assign up to 64 items to a shared catalog of up to 250 classes in one batched request (catalog sent once, one Choice per item). Per-item distribution, confidence, winner margin, and an auto-versus-review decision gated on both top probability (default 0.85) and margin (default 0.5). Caller IDs are preserved verbatim (opaque internal keys on the wire); the catalog is sent once in shared state with each item in its own question; malformed responses surface as invalid_response rather than uncertainty; batches are capped at an 8,000 item-class budget.
+
 ## 0.3.0
 
 - Cloudflare Workers AI support: with `CLOUDFLARE_API_TOKEN` (or `JEV_CLOUDFLARE_API_TOKEN`) and `CLOUDFLARE_ACCOUNT_ID` set, judgments run through Cloudflare at the `typesafe/jev` alias; `JEV_PROVIDER=cloudflare` forces it. Usage tokens are reported on every call.

package/README.md

@@ -5,13 +5,33 @@
 
 Fast, cheap, typed judgments from TypeSafe's Jev model, as MCP tools.
 
-Give your agent three judgment tools: `jev_verify` checks claims against evidence, `jev_screen` judges content before it enters context, `jev_find` ranks candidates by meaning with no embeddings. Each call returns verdicts with probability distributions and confidence in roughly 150 to 500 ms, for a fraction of a cent. The cheap mechanical checks agents otherwise skip, because a frontier model is too slow to run on every page, claim, or candidate list.
-
-Things it has done in real use:
-
-- Caught a contradicted claim at confidence 1.0 against a city ordinance.
-- Blocked a pricing page carrying a hidden "ignore your instructions" note at injection probability 0.99, while still reading it as a real page.
-- Ranked three files for "how caching affects infrastructure costs" and picked the right one at probability 1.0.
+Give your agent ten judgment tools:
+
+- `jev_verify` checks claims against evidence.
+- `jev_screen` judges content before it enters context.
+- `jev_find` picks the best candidate by meaning.
+- `jev_rerank` scores and sorts every candidate.
+- `jev_classify` batch-assigns items to classes.
+- `jev_decide` settles bounded alternatives.
+- `jev_compare` judges how two passages relate.
+- `jev_extract` pulls field values with regex plus judgment.
+- `jev_review` scores a proposed diff before the task is called done.
+- `jev_gate` reviews a patch and verifies completion claims in one call.
+
+Each judgment comes back typed: probabilities, and for most tools a confidence score, in roughly 150 to 500 ms, for a fraction of a cent. The cheap mechanical checks agents otherwise skip, because a frontier model is too slow to run on every page, claim, or candidate list.
+
+What you can use it for (the use cases are endless; these are just examples):
+
+- Fact-check a report, PR description, or agent brief against the sources it cites, claim by claim.
+- Screen a fetched page for injected instructions before it enters context, and skip pages with nothing to say.
+- Find which document, file, or note answers a question, across hundreds of candidates, with no embeddings and no index to maintain.
+- Rerank retrieval results, triage near-duplicates, or order a feed by relevance.
+- Route support messages, label issues, or sort an inbox against your own label set, in batches.
+- Choose between a handful of options with evidence and priorities in view, with an explicit ask-the-user escape hatch when it cannot decide.
+- Reconcile a changelog against its docs, a summary against its source, or catch two pages that disagree about a price or a date.
+- Pull prices, dates, versions, and IDs out of a page or document as verbatim strings the model found but never wrote.
+- Score a proposed diff for correctness, spec match, test gap, and blast radius before your agent declares the task done.
+- Gate a merge or a ship on completion claims: the patch review and every "tests pass" claim checked against the evidence actually supplied.
 
 This is early software. Expect rough edges. Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
 
@@ -38,19 +58,26 @@ From npm:
 npx -y @jkudish/jev-mcp
 ```
 
-### Amp
+<details>
+<summary>Amp</summary>
 
 ```bash
 amp mcp add jev -- npx -y @jkudish/jev-mcp
 ```
 
-### Claude Code
+</details>
+
+<details>
+<summary>Claude Code</summary>
 
 ```bash
 claude mcp add jev -- npx -y @jkudish/jev-mcp
 ```
 
-### Codex (`~/.codex/config.toml`)
+</details>
+
+<details>
+<summary>Codex (<code>~/.codex/config.toml</code>)</summary>
 
 ```toml
 [mcp_servers.jev]
@@ -58,7 +85,10 @@ command = "npx"
 args = ["-y", "@jkudish/jev-mcp"]
 ```
 
-### OpenCode (`opencode.json`)
+</details>
+
+<details>
+<summary>OpenCode (<code>opencode.json</code>)</summary>
 
 ```json
 {
@@ -72,7 +102,10 @@ args = ["-y", "@jkudish/jev-mcp"]
 }
 ```
 
-### Any other MCP client
+</details>
+
+<details>
+<summary>Any other MCP client</summary>
 
 ```json
 {
@@ -86,6 +119,8 @@ args = ["-y", "@jkudish/jev-mcp"]
 }
 ```
 
+</details>
+
 Some MCP clients filter the environment before spawning servers, which silently drops `TYPESAFE_API_KEY`. If the server reports a missing key, pass it explicitly as shown above.
 
 ## The tools
@@ -180,15 +215,298 @@ Rank candidates against a plain-language query. No embeddings, no index to maint
 - Up to 250 candidates per call. Candidate texts are truncated at 2,000 characters.
 - Pattern from the [semantic-find cookbook](https://docs.typesafe.ai/cookbooks/semantic_find).
 
+### jev_classify
+
+Assign each item to one class from a shared catalog, in one batched request: the catalog is sent once and every item becomes an independent Choice question. Designed for labeling many documents, messages, or records against a stable label set.
+
+```jsonc
+// arguments
+{
+  "purpose": "Route support messages",
+  "items": [
+    { "id": "m1", "text": "I was charged twice for my subscription this month." },
+    { "id": "m3", "text": "Do you have a student discount?" }
+  ],
+  "classes": [
+    { "id": "billing", "description": "Payments, invoices, refunds, subscription charges" },
+    { "id": "sales", "description": "Pricing questions, discounts, upgrade inquiries" }
+  ]
+}
+```
+
+```jsonc
+// live result, abridged: 4 items classified in one call for 669 input tokens
+{
+  "summary": { "items": 4, "auto": 4, "review": 0, "by_class": { "billing": 1, "technical": 2, "sales": 1 } },
+  "results": [
+    { "id": "m1", "classification": "billing", "margin": 1.0, "confidence": 1, "decision": "auto" }
+  ]
+}
+```
+
+- Auto-acceptance requires both a top probability at or above `auto_accept` (default `0.85`) and a winner-to-runner-up `margin` at or above `minimum_margin` (default `0.5`); conservative by design, based on classification spike testing where choice wording swayed uncertain cases.
+- Include a `manual_review` class in your catalog if you want an explicit escape hatch; the tool never invents one.
+- Class descriptions carry the decision. Strong ones state a precise definition, what belongs, what does not, precedence over overlapping classes, and a short example.
+- Up to 250 classes and 64 items per call, with an 8,000 item-class budget per batch (split larger waves into multiple calls); item text is truncated at 2,000 characters.
+- A malformed or incomplete model response is reported as `status: invalid_response` on that item, never as model uncertainty.
+
+### jev_decide
+
+One bounded decision, 2-6 candidates, evidence, and explicit priorities. Jev returns a Choice distribution over the candidates plus escape hatches, and a per-candidate per-requirement check, in one request.
+
+```jsonc
+// arguments
+{
+  "decision": "Choose the report status update channel.",
+  "evidence": "Polling updates within 30 seconds. Managed push updates within one second but adds a paid vendor.",
+  "priorities": "The user accepts 30 seconds and prioritizes no new paid services.",
+  "candidates": [
+    { "id": "poll", "description": "Poll the existing authenticated endpoint." },
+    { "id": "push", "description": "Add the managed push service." }
+  ],
+  "requirements": ["No new paid service is needed."]
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "recommendation": { "selected": "poll", "escaped": false, "confidence": 1,
+                      "probabilities": { "poll": 1, "push": 0, "ask_user": 0 } },
+  "checks": [ { "candidate": "poll", "requirement": 0, "answer": "supported" },
+              { "candidate": "push", "requirement": 0, "answer": "contradicted" } ]
+}
+```
+
+- Escape hatches (`ask_user`, `investigate`, `none`) let the model decline to rank when a preference or fact is missing; `escaped: true` in the result marks it. Disable with `escape_hatches: false` for closed-world choices.
+- Requirement checks run as independent questions in the same request and may disagree with the recommendation; a contradiction on the recommended candidate surfaces as a warning.
+- One call per unchanged decision. Repeat only with materially new evidence or criteria.
+
+<sub>Pattern credit: [thesammykins/jev_ampcode](https://github.com/thesammykins/jev_ampcode).</sub>
+
+### jev_rerank
+
+Score every candidate's relevance to a query and get them back sorted. You bring the candidates (file contents, database rows, search hits); Jev scores and sorts what you hand it. Unlike `jev_find`, which picks one best answer, rerank gives each candidate its own relevance probability, so the whole ordering survives. TypeSafe's rerank cookbook reports that on the CLERC benchmark this pattern lifted top-1 from 5% to 18% and top-10 from 38% to 62%.
+
+```jsonc
+// arguments
+{
+  "query": "why did our bandwidth charges triple",
+  "candidates": [
+    {
+      "id": "infra/main.tf",
+      "text": "resource \"aws_instance\" \"api\" {\n  count         = 3 # always-on\n  instance_type = \"m5.large\"\n}"
+    },
+    {
+      "id": "src/cache.ts",
+      "text": "// CDN cache control\nexport const CDN_TTL_SECONDS = 60; // was 86400 until the perf sprint"
+    },
+    {
+      "id": "docs/runbook.md",
+      "text": "# On-call runbook\n\nEscalation contacts and the weekly rotation schedule."
+    }
+  ]
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "ranked": [
+    { "rank": 1, "id": "src/cache.ts", "relevance": 0.74 },
+    { "rank": 2, "id": "infra/main.tf", "relevance": 0.23 },
+    { "rank": 3, "id": "docs/runbook.md", "relevance": 0.03 }
+  ]
+}
+```
+
+Each candidate is a file: `id` is any handle you choose, echoed back verbatim, and `text` is the file's contents (truncated at 2,000 characters). No candidate contains the words bandwidth or triple. A shorter CDN TTL means more origin fetches, so `src/cache.ts` ranks first on meaning alone; the always-on VMs are cloud spend too, just not bandwidth.
+
+- One relevance probability per candidate, all in a single request; cost scales with the number of candidates, not with candidate-pairs.
+- Candidate ids are preserved verbatim. If any answer comes back malformed, the whole ranking is reported `invalid_response` rather than sorting a missing score as a confident zero.
+- Up to 250 candidates and a 100,000-character aggregate budget; split larger batches.
+- Ranking whole documents? Chunk them into ~2,000-character candidates with distinct ids (`report.md#c1`, `report.md#c2`) and merge per document by its best chunk's score.
+- Use `jev_find` when you want one best answer plus an existence check; use `jev_rerank` when the ordering itself is the deliverable. See the [rerank cookbook](https://docs.typesafe.ai/cookbooks/rerank_typesafe).
+
+### jev_compare
+
+Judge how two passages relate: `same_fact`, `contradicts`, or `different_facts`, with the full probability distribution, confidence, and an auto-versus-review decision. Supply optional aspects (price, launch date, method) and each gets its own independent judgment in the same request.
+
+```jsonc
+// arguments
+{
+  "passage_a": "The Pro plan costs $29 per month and includes unlimited builds.",
+  "passage_b": "The Pro plan is priced at $59 per month. All plans include unlimited builds.",
+  "aspects": ["price", "build limits"]
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "overall": { "relation": "contradicts", "confidence": 1, "decision": "auto" },
+  "aspects": [
+    { "aspect": "price", "relation": "contradicts", "decision": "auto" },
+    { "aspect": "build limits", "relation": "same_fact", "decision": "auto" }
+  ]
+}
+```
+
+- Per-aspect judgments are independent and may disagree with the overall relation; that disagreement is signal, not noise.
+- Each passage is capped at 20,000 characters; requests above that are rejected up front.
+- At aspect granularity, `different_facts` explicitly means the passages do not both make a comparable assertion about the aspect: at least one does not address it, or their mentions do not overlap.
+- The request supplies no evidence beyond the two passages, so a `same_fact` verdict means they agree with each other, not that they are true.
+- Use for source reconciliation, changelog-versus-code drift, or checking that a summary matches its source.
+
+### jev_extract
+
+Pull structured fields out of a document with your regex and Jev's judgment. Your regex finds candidate substrings in code, Jev picks which candidate is the field's real value, and the value comes back verbatim, exactly as it appears in the document, never model-generated.
+
+```jsonc
+// arguments
+{
+  "document": "Starter is $9/mo. Pro is $29/mo. Enterprise: contact sales. Version 3.2.1 released 2024-06-01. The early-bird launch price for Pro was $19/mo.",
+  "fields": [
+    { "id": "price_pro", "pattern": "\\$\\d+", "description": "The current monthly price of the Pro plan in US dollars" },
+    { "id": "version", "pattern": "\\d+\\.\\d+\\.\\d+", "description": "The release version number of the software" }
+  ]
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "results": [
+    { "id": "price_pro", "value": "$29", "status": "auto", "candidates_considered": 3,
+      "candidates_truncated": false, "matches_skipped_too_long": 0 },
+    { "id": "version", "value": "3.2.1", "status": "auto", "candidates_considered": 1,
+      "candidates_truncated": false, "matches_skipped_too_long": 0 }
+  ]
+}
+```
+
+- A field whose regex matches nothing comes back `not_found` with reason `no_regex_matches` and never reaches the model: no hallucinated value. In a call where every field is a zero-match, no API call is made at all. Jev can also pick `none_of_them` when every regex match is wrong for the field; that `not_found` is model-judged and gated on top probability and winner margin like any pick.
+- Values are verbatim document substrings, exactly as the regex matched them. The model picks among matches; it never writes a value.
+- Ambiguous picks come back flagged `review` with the value still attached; treat a `review` value as provisional, not extracted. If the regex found more matches than the cap allows, or skipped matches longer than 2,000 characters, the field can never be `auto` and a `none_of_them` pick can never be a definite `not_found`: it returns `review` with reason `candidate_limit` and `candidates_truncated` or `matches_skipped_too_long` set, because the best value may be among the unsent matches. When every match is over 2,000 characters and none is eligible at all, the reason is `matches_too_long` instead. A malformed model answer is still `invalid_response`, not a semantic outcome.
+- Invalid patterns and regexes that time out (they run in a sandboxed worker with a 1-second deadline, so a pathological pattern cannot hang the server) return `invalid_pattern` with the error instead of failing the whole call.
+- Up to 32 fields per call and 20 candidate matches per field, judged in one request. The document is capped at 50,000 characters, and the candidate match text at 50,000 characters in aggregate.
+
+### jev_review
+
+Score a proposed diff against the request before the task is called done. Jev answers four rubric questions, correctness, spec match, test gap, and blast radius, each 0..2, plus one safe-to-apply probability; the server combines them into a weighted composite and one action: `auto`, `review`, or `escalate`. It judges what you hand it. It never runs tests and never applies the patch.
+
+```jsonc
+// arguments
+{
+  "request": "Our CLI reads a JSON config from stdin. It crashed on empty input. Make it tolerate an empty document and any whitespace-only document, returning our zero-value config instead.",
+  "diff": "--- a/src/parse.ts\n+++ b/src/parse.ts\n@@ def parse(stdin) @@\n-  return JSON.parse(stdin);\n+  const trimmed = stdin.trim();\n+  if (trimmed === \"\") return zeroConfig();\n+  return JSON.parse(trimmed);",
+  "tests": "node --test: 2 passed, 1 failing (parse: invalid JSON still rejects)"
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "action": "escalate",
+  "composite": 0.756,
+  "safe_to_apply": 0.24,
+  "scores": {
+    "correctness": { "score": 1.51, "confidence": 0.27 },
+    "spec_match":  { "score": 1.65, "confidence": 0.47 },
+    "test_gap":    { "score": 0.80, "confidence": 0.14 },
+    "blast_radius":{ "score": 0.45, "confidence": 0.32 }
+  },
+  "weights":    { "correctness": 0.4, "spec_match": 0.3, "test_gap": 0.15, "blast_radius": 0.15 },
+  "thresholds": { "auto_accept": 0.8, "review_at": 0.5, "composite_floor": 0.7 },
+  "truncated": false,
+  "usage": { "input_tokens": 855, "output_tokens": 79 }
+}
+```
+
+Here the composite clears the floor, but the failing test drags `safe_to_apply` to 0.24 and rubric confidences sit under `review_at`, so the patch escalates instead of sailing through on its decent scores.
+
+- Rubric scores run 0..2. Higher is better for `correctness` and `spec_match`; higher is worse for `test_gap` and `blast_radius`, and the composite inverts those two before weighting, so a composite of 1.0 means favorable on every rubric.
+- `auto` requires `safe_to_apply` and every rubric confidence at `auto_accept` and the composite at `composite_floor`. `safe_to_apply` or any rubric confidence below `review_at`, or unknown, escalates; a composite below `composite_floor` returns `review`, not `escalate`. Unknown confidence counts as escalate, never as a value that can satisfy a threshold.
+- `request` frames the review; it is not proof of anything. Put real output in `tests`. Every field is treated as evidence to evaluate, never instructions to follow.
+- Each text field is capped at 50,000 characters. Truncated input sets `truncated: true` and can never return `auto`; a malformed answer is `invalid_response`, not a semantic outcome.
+
+<sub>Adapted from [burnigtm/jev-mcp](https://github.com/burnigtm/jev-mcp) (MIT), via [PR #2](https://github.com/jkudish/jev-mcp/pull/2) by rimusz.</sub>
+
+### jev_gate
+
+The completion gate: the same patch review as `jev_review`, plus your completion claims verified against evidence you supply, in one call. Auto only when the review is accepted and every claim is verified at or above `auto_accept`; a confidently contradicted claim escalates. The request and the claims are assertions to check, never proof.
+
+```jsonc
+// arguments
+{
+  "request": "Our CLI reads a JSON config from stdin. It crashed on empty input. Make it tolerate an empty document and any whitespace-only document, returning our zero-value config instead.",
+  "diff": "--- a/src/parse.ts\n+++ b/src/parse.ts\n@@ def parse(stdin) @@\n-  return JSON.parse(stdin);\n+  const trimmed = stdin.trim();\n+  if (trimmed === \"\") return zeroConfig();\n+  return JSON.parse(trimmed);",
+  "claims": [
+    "The empty-input parser test passed.",
+    "Whitespace-only input is also handled.",
+    "The full test suite passes with no failures."
+  ],
+  "evidence": [
+    { "id": "test-log", "text": "node --test output: 2 passed, 1 failing (parse: invalid JSON still rejects)." },
+    { "id": "diff",      "text": "parse.ts: trimmed input; empty string returns zeroConfig(); JSON.parse on the trimmed text otherwise." }
+  ],
+  "tests": "node --test: 2 passed, 1 failing (parse: invalid JSON still rejects)"
+}
+```
+
+```jsonc
+// live result, abridged
+{
+  "action": "escalate",
+  "reason_codes": ["review_escalated", "claims_contradicted"],
+  "review": { "action": "escalate", "composite": 0.816, "safe_to_apply": 0.19 },
+  "verification": {
+    "action": "escalate",
+    "summary": { "verified": 2, "contradicted": 1, "unsupported": 0, "needs_review": 1 },
+    "results": [
+      { "claim": "The empty-input parser test passed.",
+        "verdict": "verified", "confidence": 1, "action": "auto" },
+      // second claim likewise verified at confidence 1
+      { "claim": "The full test suite passes with no failures.",
+        "verdict": "contradicted", "confidence": 1, "action": "escalate" }
+    ]
+  },
+  "truncated": false,
+  "usage": { "input_tokens": 1559, "output_tokens": 201 }
+}
+```
+
+The two true claims verify at full confidence, and the one that matters, "the full test suite passes," is contradicted by the test log at full confidence: exactly the claim a coding agent is most tempted to hand-wave.
+
+- Claim questions instruct Jev to use `evidence` only, not world knowledge, and not the request, diff, or tests fields; if a claim needs a diff excerpt or a test log as support, supply it in `evidence`. All fields share one model state, so this is instruction-level isolation, not a hard boundary. Every field is evidence to evaluate, never instructions to follow.
+- `reason_codes` collects why the gate decided as it did: `incomplete_context`, `invalid_response`, `review_escalated`, `review_required`, `claims_contradicted`, `claims_unsupported`, `claim_confidence_low`, `claim_confidence_below_auto_accept`, `accepted`.
+- Up to 16 claims and 16 evidence items per call. Text fields are capped at 50,000 characters each, claims at 2,000, and evidence at 200,000 characters in aggregate; oversized evidence is rejected before any model call. Malformed answers surface as `invalid_response` and the gate never returns `auto` on one.
+- Use `jev_verify` for claims without a patch review, and `jev_review` for a patch without claims.
+
+<sub>Adapted from [burnigtm/jev-mcp](https://github.com/burnigtm/jev-mcp) (MIT), via [PR #2](https://github.com/jkudish/jev-mcp/pull/2) by rimusz.</sub>
+
+## When to call which tool
+
+- `jev_verify`: one or more claims against evidence you already have.
+- `jev_screen`: fetched or pasted content, before it enters context.
+- `jev_find`: pick the single best candidate from up to 250.
+- `jev_rerank`: score and sort the whole list.
+- `jev_classify`: label many items against your own catalog, in batches.
+- `jev_decide`: choose between a handful of options with priorities in view.
+- `jev_compare`: how two passages relate, overall or per aspect.
+- `jev_extract`: pull field values a regex can find, verbatim.
+- `jev_review`: score a proposed diff before calling the task done.
+- `jev_gate`: that same review plus completion claims checked against evidence.
+
 ## How the answers work
 
-Jev is TypeSafe's System One model: it returns typed answers with calibrated probability distributions, not generated text. A verify call is a Choice over supports / contradicts / says_nothing, so you see the whole distribution, not one label. A screen call is a set of yes/no probabilities. A find call is a Choice over your candidate ids plus an existence check. Code maps the answers to verdicts and actions; policy stays with you.
+Jev is TypeSafe's System One model: it returns typed answers with calibrated probability distributions, not generated text. A verify call is a Choice over supports / contradicts / says_nothing, so you see the whole distribution, not one label. A screen call is a set of yes/no probabilities. A find call is a Choice over your candidate ids plus an existence check. A rerank call is one yes/no relevance question per candidate. A compare call is a Choice over three relations, repeated independently per aspect. An extract call is a Choice over the candidates your regex already found, so the model picks a value but never writes one. A review call is four Score rubrics plus one safe-to-apply probability; a gate adds one Choice per completion claim, judged from evidence only. Code maps the answers to verdicts and actions; policy stays with you.
 
 ## Limits and tuning
 
 - Thresholds (`auto_accept`, `block_at`, `review_at`, exists cutoffs) are starting points from the TypeSafe cookbooks. Tune them against your own data before you enforce them. See [how TypeSafe reports confidence](https://docs.typesafe.ai/confidence.md).
 - Jev is calibrated, not infallible. Typed output guarantees the interface, not the truth. Keep policy in code and escalate low-confidence results to a person or a bigger model.
-- Every result includes token usage, so you can see what each judgment costs.
+- Every result that calls the model includes token usage, so you can see what each judgment costs. A `jev_extract` call where no field reaches the model reports `usage: null`.
 
 ## Configuration