[DOCS] Contradictory information regarding JSON Schema numerical constraints support in Agent SDK and Structured Outputs

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/build-with-claude/structured-outputs - https://platform.claude.com/docs/en/agent-sdk/custom-tools

Section/Topic

• The "JSON Schema limitations" section in the Structured Outputs guide. - The "Type Safety with Python" section in the Custom Tools guide.

Current Documentation

On the Structured Outputs page:

"Not supported: ... Numerical constraints (minimum, maximum, multipleOf, etc.)"

On the Custom Tools page:
An example is provided that explicitly uses these "unsupported" constraints:

@tool(
    "advanced_process",
    "Process data with advanced validation",
    {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer", "minimum": 0, "maximum": 150},
            "email": {"type": "string", "format": "email"},
            "format": {"type": "string", "enum": ["json", "csv", "xml"], "default": "json"}
        },
        "required": ["name", "age", "email"]
    }
)

What's Wrong or Missing?

There is a direct contradiction between the "Not supported" list in the Structured Outputs guide and the code examples provided in the Agent SDK documentation.

While the underlying Claude API (via the structured-outputs-2025-11-13 header) may not support these as hard constraints for sampling, the Agent SDK (Python and TypeScript) handles these constraints by stripping them from the schema sent to the model, appending the requirement to the field's description, and performing client-side validation on the response.

The current documentation does not explain this distinction, leading developers to believe the examples in the SDK documentation are invalid or that the Structured Outputs guide is outdated.

Suggested Improvement

The "JSON Schema limitations" section should be updated to clarify how the Agent SDK handles these constraints.

Suggested text for the Structured Outputs page:

Note on SDK Behavior: If you are using the Claude Agent SDK (Python or TypeScript), constraints such as minimum, maximum, minLength, and maxLength are handled automatically. The SDK strips these from the schema sent to the model, injects the requirement into the text description (e.g., "Must be at least 0"), and enforces the constraint via client-side validation once the response is received.

Suggested update to the Custom Tools page:
Add a small callout to the "Advanced validation" example:

Note: While the model receives these numerical constraints as part of the text description rather than as hard sampling constraints, the Agent SDK will automatically validate the model's output against these values before returning the data to your application.

Impact

High - Prevents users from using a feature

Additional Context

• In the provided SDK documentation for TypeScript, it mentions that the SDK "Removes unsupported constraints" and "Updates descriptions with constraint info." This helpful context is missing from the main Python SDK and Structured Output pages, creating a documentation gap for Python developers and API-only users.