For Agents

Machine-Readable Surfaces

Decision Procedure

1. Reading vs. structured data: use format: "markdown" (or the contrie_read MCP tool) when you just need to read a page. Use schema when downstream code depends on the exact shape; use free-text extract otherwise.
2. Check the acceptance evidence: require success: true. For structured output that already means valid: true and qualityScore ≥ 70; they are not a second gate. Inspect valid, schemaValid, requestedFields and groundingCoverage. These are local structure and text-support checks; verify field meaning, attribution and freshness before a consequential action. Acceptance requires at least half of all returned values (nulls excluded) to be found in the page text; booleans and strings under 3 characters are never found, so an answer made mostly of yes/no values or one- or two-letter codes is refused. Ask for such a value as the text the page shows (“the stock status as shown”). Above that floor, choose the bar each job needs and read groundingFields for the values that matter.
3. Retry once, narrower: on a lower qualityScore, retry a single time with a more specific extract prompt rather than repeating the same call.
4. Refused, read why before you retry: a refusal (success: false) carries no values and no groundingFields. Read metadata.requestedFields.missing and metadata.groundingCoverage and metadata.completeness. Acceptance requires more than 30% of the fields in the answer to be populated (completeness above 0.3), so an answer at or below that share is refused: request fewer fields. Otherwise retry once with nullable fields or values asked for as the page writes them.
5. Low grounding on an accepted answer, inspect before you retry: don't discard the whole result, and don't assume an unmatched value is wrong — it is unconfirmed, and a page that presents a value differently can fail the check. Read metadata.groundingFields, find the entries with grounded: false, and retry with a narrower extract naming only those paths. When a human needs to check the agent's work, the excerpt on each entry is the audit trail — it's the page text the check matched against, not just a verdict.
6. RENDER_REQUIRED isn't retryable as-is: the available page could not support this request. Check the source and its limits first. Eligible requests may use Contrie's rendering options; authorized callers can also supply captured HTML through /api/v1/extract. A login wall or unsupported source may still be refused.
7. Check credits and capacity: call contrie_account before new work, then inspect the extraction's metadata.credits. The account check reserves no capacity. Unused monthly credits alone do not guarantee availability.
8. One page per call: no crawling, no open-web search, no multi-step browsing — call once per URL you already have.

Worked Example: Retrying on Low Grounding

A product page extraction comes back with qualityScore: 78 but grounding: 0.67 — a third of the checkable values have no text support. Instead of retrying the whole request, check groundingFields for the failing path:

[
  {
    "path": "$.price",
    "value": "$49.99 (was $69.99)",
    "grounded": false
  },
  {
    "path": "$.name",
    "value": "Trail Runner Jacket",
    "grounded": true,
    "excerpt": "…lightweight trail runner jacket, packable, water-resistant shell…"
  }
]

Only $.price failed — the returned value may combine a sale price and a strikethrough price into one string that never appears verbatim on the page. Retry with a narrower extract targeting just that field ("the current price only, as a plain number") instead of re-running the full extraction.

Full Reference

For the complete parameter and response contract, see Scrape, Extract, Streaming, and Error Codes.