# Field Constraints for Tool Arguments in Needle: Complete JSON-Schema Reference

> Explore Needle's supported Field constraints for tool arguments. Discover how 15 parameters map to JSON-Schema keywords like ge, le, pattern, enum, and unique_items for robust validation.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-08-28

---

**Needle's `Field` class supports 15 constraint parameters—including `ge`, `le`, `pattern`, `enum`, and `unique_items`—that map directly to JSON-Schema keywords defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py).**

The Needle framework automatically generates OpenAI-compatible JSON schemas from Python function signatures. When you annotate tool arguments with the `Field` class, you specify precise validation rules that enforce data integrity before your functions execute.

## Complete List of Supported Field Constraints

The `Field.__init__` method in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) (lines 18-31) accepts the following constraint parameters, each mapping to a specific JSON-Schema keyword:

### Numeric Range Constraints

- **`ge`**: Minimum inclusive value (maps to `minimum`)
- **`le`**: Maximum inclusive value (maps to `maximum`)
- **`gt`**: Minimum exclusive value (maps to `exclusiveMinimum`)
- **`lt`**: Maximum exclusive value (maps to `exclusiveMaximum`)
- **`multiple_of`**: Value must be divisible by this number (maps to `multipleOf`)

### String Validation Constraints

- **`min_length`**: Minimum character count (maps to `minLength`)
- **`max_length`**: Maximum character count (maps to `maxLength`)
- **`pattern`**: Regular expression the string must match (maps to `pattern`)
- **`format`**: Pre-defined string format such as `"email"` (maps to `format`)

### Array Collection Constraints

- **`min_items`**: Minimum number of elements (maps to `minItems`)
- **`max_items`**: Maximum number of elements (maps to `maxItems`)
- **`unique_items`**: Requires all array elements to be distinct (maps to `uniqueItems`)

### Value Definition Constraints

- **`description`**: Human-readable documentation text (maps to `description`)
- **`enum`**: List of allowed literal values
- **`const`**: Single fixed value the argument must equal

## How Field Constraints Map to JSON-Schema

The transformation logic resides in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). When you instantiate a `Field` with constraints, the `apply` method (lines 36-49) injects these parameters into the generated schema dictionary using the corresponding JSON-Schema keywords listed above.

According to the source code, if you specify a `const` value, Needle adds it to the schema unconditionally, regardless of what other constraints are present. This ensures fixed-value arguments are strictly enforced at the schema level.

## Practical Code Examples

### Numeric Bounds with ge and le

Use inclusive bounds to restrict numeric arguments to valid operating ranges:

```python
from needle import tool, Field

@tool
def set_temperature(
    value: int = Field(description="Target temperature in °C", ge=0, le=100)
):
    """Set the thermostat to a specific temperature."""
    pass

```

### String Validation with pattern and min_length

Enforce username formats using regex patterns and length constraints:

```python
@tool
def create_user(
    username: str = Field(min_length=3, max_length=20, pattern=r"^[a-z0-9_]+$"),
    role: str = Field(enum=["admin", "editor", "viewer"], default="viewer")
):
    """Create a new user account."""
    pass

```

### Array Constraints with unique_items

Prevent duplicate task IDs and limit batch sizes:

```python
@tool
def schedule_tasks(
    tasks: list = Field(min_items=1, max_items=10, unique_items=True)
):
    """Schedule a list of task IDs."""
    pass

```

## Key Source Files and Implementation Details

Understanding these three files helps you master Needle's constraint system:

- **[`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)**: Contains the `Field` class definition, its constructor parameters (lines 18-31), and the `apply` method (lines 36-49) that maps constraints to JSON-Schema keys.
- **[`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)**: Exports `tool` and `Field` at the package level for convenient imports.
- **[`tests/test_tools.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_tools.py)**: Provides unit tests demonstrating valid usage patterns for constraints like `ge`, `le`, and `pattern`.

## Summary

- Needle's `Field` class supports **15 constraint parameters** ranging from numeric bounds to array uniqueness rules.
- Constraints are defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) and applied via the `apply` method to generate OpenAI-compatible JSON schemas.
- The `const` parameter takes precedence and is always included in the generated schema, independent of other constraints.
- Numeric constraints (`ge`, `le`, `gt`, `lt`) map directly to JSON-Schema minimum/maximum keywords.
- String and array constraints allow precise validation of text patterns and collection uniqueness.

## Frequently Asked Questions

### What is the difference between ge and gt in Needle Field constraints?

The `ge` parameter sets a minimum inclusive bound (greater than or equal to), mapping to JSON-Schema's `minimum` keyword. The `gt` parameter sets a minimum exclusive bound (strictly greater than), mapping to `exclusiveMinimum`. Use `ge` when the boundary value itself is acceptable, and `gt` when the value must be strictly larger than the threshold.

### Can I combine multiple constraints on a single Field argument?

Yes. According to [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), you can specify multiple constraints simultaneously in the `Field` constructor. For example, you can combine `min_length`, `max_length`, and `pattern` on string arguments, or `ge` and `le` for inclusive numeric ranges. The `apply` method processes all provided constraints and adds them to the generated schema.

### How does the const constraint differ from enum in Needle?

While `enum` accepts a list of allowable values, `const` enforces a single fixed value that the argument must equal. The source code specifically handles `const` separately in the `apply` method, ensuring it is always added to the schema regardless of other constraints present. Use `const` when an argument must exactly match one specific value.

### Where are Needle's Field constraints processed in the source code?

The constraint definitions reside in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). The `Field.__init__` method (lines 18-31) defines the accepted parameters, while `Field.apply` (lines 36-49) translates these into JSON-Schema keywords. Unit tests in [`tests/test_tools.py`](https://github.com/cactus-compute/needle/blob/main/tests/test_tools.py) verify the correct generation of schemas containing these constraints.