---
title: "Contextual Schema Optimization"
description: "Build and improve extraction configurations from representative documents."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contextual Schema Optimization

Contextual Schema Optimization helps you create a new extraction configuration or improve an existing one. Give it representative documents, describe the output you need, and optionally attach expected JSON. Contextual Schema Optimization returns a schema, system prompt, evaluation evidence, and a report describing remaining assumptions.

During the private beta, Contextual Schema Optimization is available through two interfaces:

- **`reducto-beta` MCP** is the recommended interface for interactive work with a coding agent. It can inspect local documents, prepare inputs, ask for confirmation, submit the run, and present the result.
- **Contextual Schema Optimization API** is the lower-level interface for applications that need to submit runs, poll status, and receive completion webhooks directly.

- [Use reducto-beta](/contextual-schema-optimization/reducto-beta): Set up or improve an extraction configuration from Claude Code, Codex, Cursor, or another MCP client.

- [Use the Contextual Schema Optimization API](/contextual-schema-optimization/api): Integrate Contextual Schema Optimization into your own application or continuous optimization loop.

## Choose a workflow

| Goal | MCP tool | API endpoint |
|---|---|---|
| Create a schema and prompt for a new use case | `setup_use_case` | `POST /setup-use-case` |
| Improve an existing schema or prompt | `optimize_schema` | `POST /schema-optimize` |
| Check an existing production schema | Coming soon | Coming soon |
| Retrieve an accepted or finished run | `get_optimizer_run` | `GET /runs/{run_id}` |

Use at least three representative documents for setup or optimization. A broader sample usually produces a more useful result than the three-document minimum.

> **Note:** Health checks are not available during the current design-partner beta. Reducto will publish the workflow and its input conventions when it is ready.

## Ground truth

Ground truth pairs a document with expected JSON. It is optional, but it changes what Contextual Schema Optimization can measure:

- With ground truth, Contextual Schema Optimization can compare extraction output against expected values and report measured accuracy.
- Without ground truth, Contextual Schema Optimization uses document-backed evaluation and consistency checks. Treat unresolved ambiguities in the report as decisions for a human reviewer.

For schema optimization, attach ground truth as one JSON object per document. The JSON shape should match the extraction schema you want Contextual Schema Optimization to evaluate.

## Run lifecycle

Every workflow is asynchronous:

```mermaid
flowchart LR
    A[Prepare documents and requirements] --> B[Submit]
    B --> C[accepted]
    C --> D[running]
    D --> E{Final status}
    E --> F[completed]
    E --> G[partial]
    E --> H[failed]
    F --> I[Review and validate configuration]
    G --> I
```

`completed` means Contextual Schema Optimization produced the required artifacts. `partial` means Contextual Schema Optimization produced a usable result with warnings or missing supporting evidence. `failed` means Contextual Schema Optimization produced no usable configuration.

Always review the result report and validate the proposed configuration against your own acceptance criteria before promoting it to production.

## Limits

- Setup and optimization require 3–10,000 documents.
- Each document may be up to 50 MiB.
- Inline API inputs may total up to 150 MiB.
- Native workspace ZIPs may occupy up to 1.5 GiB both before and after expansion.
- Ground-truth JSON must be an object and may be up to 1 MB (1,000,000 bytes) per document.
- Requirement files may be up to 10 MiB each.
- A run may execute for up to four hours.

Contextual Schema Optimization does not support on-premises deployments or PrivateLink-only organizations. Reducto will confirm eligibility and provide the Contextual Schema Optimization API base URL during beta onboarding.

## Troubleshooting

### A run stays at `accepted` or `running`

**Problem**: The run has not reached a final status.

**Solution**: Continue polling with `get_optimizer_run` or `GET /runs/{run_id}` for up to four hours. See the [`reducto-beta` workflow](/contextual-schema-optimization/reducto-beta#recommended-workflow) or [Contextual Schema Optimization API polling guide](/contextual-schema-optimization/api#poll-a-run).

### Contextual Schema Optimization returns `partial` or `failed`

**Problem**: Contextual Schema Optimization found warnings, missing evidence, or an error.

**Solution**: Read `partial_reason`, `error`, and the result report before changing your production configuration. Keep the previous configuration active when Contextual Schema Optimization returns `failed`.

### You cannot access Contextual Schema Optimization

**Problem**: Your MCP client does not show Contextual Schema Optimization tools, or the API rejects your organization.

**Solution**: Confirm that Reducto enabled the private beta for your organization. Then reconnect `reducto-beta` or use the Contextual Schema Optimization API base URL from onboarding.

Source: https://docs.reducto.ai/contextual-schema-optimization/overview/index.mdx
