Needle.Field Constraint Types: A Complete Guide to JSON-Schema Validation Parameters in Needle

needle.Field supports 14 JSON-Schema-based constraint types including numeric bounds (ge, le, gt, lt), string validators (min_length, max_length, pattern, format), array constraints (min_items, max_items, unique_items), and value restrictions (enum, const).

The needle.Field class provides a declarative way to attach validation constraints to function parameters when building AI tools with the needle library. When you use the @tool decorator, Field instances automatically translate into JSON Schema definitions that enforce type safety and input validation.

What Constraint Types Are Supported by needle.Field

needle.Field accepts keyword arguments that map directly to JSON Schema validation keywords. The constructor is implemented in needle/agent/tools.py at lines 17-30, with schema generation handled by the apply method at lines 35-48.

Value Metadata Constraints

These constraints control basic field properties and documentation:

• default — Fallback value used when the parameter is not supplied
• description — Human-readable explanation of the field's purpose
• enum — List of allowed literal values the parameter must match
• const — Single fixed value that the field must equal

These parameters appear in the Field constructor signature at needle/agent/tools.py lines 17-18.

Numeric Range Constraints

For int and float parameters, four bound types are available:

• ge — Inclusive minimum (≥), maps to JSON Schema minimum
• le — Inclusive maximum (≤), maps to JSON Schema maximum
• gt — Exclusive minimum (>), maps to JSON Schema exclusiveMinimum
• lt — Exclusive maximum (<), maps to JSON Schema exclusiveMaximum

You can combine inclusive and exclusive bounds as needed. The multiple_of constraint additionally requires values to be divisible by a specified number.

These numeric parameters are defined at needle/agent/tools.py lines 19-21.

String Validation Constraints

For str parameters, Field supports pattern and length validation:

• min_length — Minimum character count (inclusive)
• max_length — Maximum character count (inclusive)
• pattern — Regular expression the string must match
• format — JSON Schema format hint such as "date-time", "email", or "uri"

The string constraint implementation appears at needle/agent/tools.py lines 28-30.

Array/List Constraints

For collection types, three constraints control item count and uniqueness:

• min_items — Minimum number of elements in the array
• max_items — Maximum number of elements in the array
• unique_items — Boolean flag requiring all array elements to be distinct

These are also defined at needle/agent/tools.py line 30.

How needle.Field Translates Constraints to JSON Schema

The apply method at needle/agent/tools.py lines 35-48 performs the conversion from Field parameters to JSON Schema keys. This transformation follows standard JSON Schema naming conventions:

needle.Field Parameter	JSON Schema Output Key
ge	minimum
le	maximum
gt	exclusiveMinimum
lt	exclusiveMaximum
multiple_of	multipleOf
min_length	minLength
max_length	maxLength
min_items	minItems
max_items	maxItems
unique_items	uniqueItems
All others	Same name (e.g., enum, const, pattern, format)

Practical Code Examples

Basic Parameter Validation with Default Values

from needle import tool, Field

@tool
def generate(
    temperature: float = Field(default=0.7, ge=0, le=1, description="Sampling temperature"),
    max_tokens: int = Field(default=256, ge=1, le=1024),
    stop: str = Field(default=".", pattern=r"^\.$", description="Stop token")
):
    """Generate text using the model."""
    ...

This example demonstrates numeric bounds (ge, le) and regex pattern matching on the needle.Field parameters.

Using typing.Annotated with Required Parameters

from needle import tool, Field
from typing import Annotated

@tool
def classify(
    text: str,
    label: Annotated[str, Field(enum=["positive", "negative", "neutral"])]
):
    """Classify sentiment."""
    ...

When a parameter has no default value, wrap Field in typing.Annotated to attach constraints without providing a default.

Array Validation Example

from needle import tool, Field
from typing import Annotated, List

@tool
def process_tags(
    items: Annotated[List[str], Field(min_items=1, max_items=10, unique_items=True)]
):
    """Process a list of unique tags."""
    ...

Complete Constraint Reference Table

Constraint	Type	Applies To	JSON Schema Key
default	Any	All types	Used at runtime, not in schema
description	str	All types	description
enum	list	All types	enum
const	Any	All types	const
ge	float / int	Numbers	minimum
le	float / int	Numbers	maximum
gt	float / int	Numbers	exclusiveMinimum
lt	float / int	Numbers	exclusiveMaximum
multiple_of	float / int	Numbers	multipleOf
min_length	int	Strings	minLength
max_length	int	Strings	maxLength
pattern	str	Strings	pattern
format	str	Strings	format
min_items	int	Arrays	minItems
max_items	int	Arrays	maxItems
unique_items	bool	Arrays	uniqueItems

Summary

• needle.Field supports 14 constraint types covering metadata, numeric bounds, string patterns, and array validation as defined in needle/agent/tools.py
• Constraints map directly to JSON Schema via the apply method (lines 35-48), enabling automatic validation in AI tool interfaces
• Two usage patterns exist: as default values for optional parameters, or inside typing.Annotated for required parameters
• All constraints are optional — use only those relevant to your parameter's expected input
• Combine multiple constraints freely, such as ge + le for inclusive ranges or min_length + pattern for string validation

Frequently Asked Questions

Can I use multiple range constraints together in a single needle.Field?

Yes. According to the needle/agent/tools.py implementation, you can combine ge/le for inclusive bounds or gt/lt for exclusive bounds, and even mix them (e.g., gt=0 with le=100). The apply method processes each constraint independently and adds all valid keys to the generated JSON Schema.

Does needle.Field validate inputs at runtime or just generate schema?

The validation behavior depends on the Needle tool-binding system consuming the schema. The Field class itself, as implemented in lines 17-30 of needle/agent/tools.py, is purely declarative—it stores constraint values and generates JSON Schema via apply. Actual input validation occurs when the schema is used by the runtime system.

What is the difference between enum and const constraints in needle.Field?

enum accepts a list of allowed values, restricting the parameter to any member of that set, while const enforces a single fixed value. In needle/agent/tools.py, both appear as direct keyword parameters (lines 18-22) and pass through unchanged to the JSON Schema output. Use enum for categorical choices and const when the value must be invariant.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}