tool_use with JSON Schema guarantees two things: zero JSON syntax errors and zero schema violations. Every response is valid JSON with all required fields present at correct types. This is enforced at the API generation level — not probabilistic, not post-hoc.
What it cannot guarantee: semantic correctness. Author name in the version field. Line items that do not sum to the total. Fabricated data in required fields. Logically inconsistent dates.
The Three-Layer Error Model
| Layer | Error type | tool_use fixes? |
|---|---|---|
| 1 | Syntax (malformed JSON) | Yes — eliminated |
| 2 | Schema (missing fields, wrong types) | Yes — eliminated |
| 3 | Semantic (wrong values, logic errors) | No — unchanged |
Data from a three-phase improvement:
- Phase 1 (prompt-based JSON): 28% total errors (4.2% syntax + 8.1% missing fields + 12% semantic)
- Phase 2 (tool_use): 13% errors (0% syntax + 0% missing + 11% semantic)
- Phase 3 (tool_use + field descriptions + validation): 3% errors
Each phase addressed a distinct error class. tool_use alone cut errors by half but left semantic issues untouched. Application-layer validation handled the remaining gap.
Detailed Field Descriptions Reduce Semantic Errors
When 8% of extractions placed values in wrong fields, adding clear descriptions to tool parameters — explaining what value belongs in each field — guided Claude on the semantic mapping. This is the recommended approach for the gap between schema compliance and content correctness.
Prompt-Based JSON Is an Anti-Pattern
“Output as valid JSON” in a prompt cannot guarantee syntax correctness or schema compliance. Retry-on-parse-error is a reactive workaround that wastes API calls. tool_use provides structural guarantees by design.
tool_choice: forced vs auto
When tool_choice: auto is used with a virtual extraction tool, the model sometimes returns text instead of calling the tool, breaking downstream parsing. Switch to forced tool_choice to guarantee structured output on every call.
Validation Is Still Required
“Remove all validation — tool_use guarantees correctness” is wrong. tool_use guarantees structure, not semantics. For financial documents, business logic validation (line items sum to total, dates in sequence) remains essential. JSON Schema cannot express cross-field arithmetic constraints.
One-liner: tool_use eliminates syntax and schema errors at the API level, but semantic validation (cross-field logic, value correctness) is still your responsibility — structure is guaranteed, meaning is not.