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-betaMCP 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.
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.
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:
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 --> Icompleted 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 or Contextual Schema Optimization API polling guide.
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.