Claude Architect Lab

Structured Output via Tool Use & JSON Schemas

Core

Enforce structured output using tool use and JSON schemas · Difficulty 3/5

0%
structured-outputjson-schematool-use
Prerequisites
Few-Shot Prompting Techniques

For automated pipelines, you need guaranteed Structured Output -- not narrative text that might vary. Tool use with JSON schemas is the most reliable approach.

Approaches (Least to Most Reliable)

  • Prompt-based formatting: Ask for Structured Output in instructions -- unreliable
  • Few-shot examples: Demonstrate exact format -- good for interactive use
  • **CLI Structured Output**: --output-format json --json-schema -- guaranteed for CLI
  • API tool use: Define tools with JSON Schema for structured responses -- most reliable

    • Why Tool Use Wins

    Tool use with JSON schemas guarantees schema-compliant output. The model MUST return data matching the schema, eliminating JSON syntax errors entirely. However, it does NOT prevent semantic errors (e.g., line items that don't sum to total, values in wrong fields).

    Schema Design Best Practices

  • Required vs optional fields: Make fields optional (nullable) when source data may not contain the information. This prevents the model from fabricating values to satisfy required fields.
  • Enum fields: Use enum values like "unclear" for ambiguous cases.
  • Extensible categories: Use "other" + detail string pattern for categories that may expand.
  • Format normalization: Include normalization rules in prompts alongside strict schemas to handle inconsistent source formatting.

    • Key Takeaways

    • ✓Tool use with JSON schemas eliminates syntax errors but not semantic errors
    • ✓Make fields optional/nullable when source data may not contain the information
    • ✓Use enum + 'other' + detail string pattern for extensible categories
    • ✓Prompt-based formatting is unreliable for automated pipelines

    Glossary Terms

    Structured Output

    Guaranteed formatted output (typically JSON) from Claude. The most reliable method is to define a schema as a tool and set tool_choice to force its use — Claude's tool_use blocks are always valid JSON. Alternatively, use --output-format json with --json-schema in Claude Code CLI.

    tool_use

    A content block type in Claude's response indicating the model wants to call a specific tool. Contains 'id', 'name', and 'input' fields. The agent must execute the tool and return results in a tool_result content block for the conversation to continue.

    Related Concepts

    tool_choice Options & Forced Tool Selection

    tool_choice: 'auto' may return text; 'any' guarantees a tool call; forced selection guarantees a specific tool

    Retry-with-Error-Feedback Pattern

    Append specific validation errors to the retry prompt -- not just 'try again'

    Test Yourself1 of 1

    Your CI pipeline runs the Claude Code CLI using CLAUDE.md to provide project context for code reviews. However, developers report that integrating findings into your workflow is difficult — Claude produces narrative paragraphs that must be manually copied into PR comments. Your team wants to automatically post each finding as a separate inline PR comment at the relevant code location. What's the most effective approach?