From 72fc9f138590fb8eb923b53ce10fe5414738aacf Mon Sep 17 00:00:00 2001 From: subhash polisetti Date: Thu, 10 Sep 2026 21:45:12 -0700 Subject: [PATCH] docs: clarify Field description handling for variadic tool parameters The section covers constraining and describing arguments with Field, and the variadic paragraph mentions only constraints, so the wording reads as though a Field description also reaches a variadic parameter. State that the SDK does not read Field(description=...) for a variadic parameter and name the two supported ways to supply that description. --- docs/tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 14384eed87..d91537ae2d 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -511,7 +511,7 @@ The code for the schema extraction lives in [`agents.function_schema`][]. You can use Pydantic's [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) to add constraints (e.g. min/max for numbers, length or pattern for strings) and descriptions to tool arguments. As in Pydantic, both forms are supported: default-based (`arg: int = Field(..., ge=1)`) and `Annotated` (`arg: Annotated[int, Field(..., ge=1)]`). The generated JSON schema and validation include these constraints. -For variadic parameters, an annotation describes each collected value. The SDK therefore applies `Annotated[..., Field(...)]` constraints to each value supplied through `*args` or `**kwargs`, while omitted variadic parameters remain valid empty collections. Annotate scalar positional values as `*args: T`. If each positional value is itself a homogeneous tuple, use `*args: tuple[T, ...]`; the SDK rejects fixed-length tuple annotations such as `*args: tuple[int, str]` because one fixed tuple shape cannot describe a variadic sequence of positional values. +For variadic parameters, an annotation describes each collected value. The SDK therefore applies `Annotated[..., Field(...)]` constraints to each value supplied through `*args` or `**kwargs`, while omitted variadic parameters remain valid empty collections. The SDK ignores a `description` passed to `Field(...)` on a variadic parameter; that parameter's description is taken from the function docstring or from a string in `Annotated`, for example `*scores: Annotated[int, "Exam scores", Field(ge=0, le=100)]`. Annotate scalar positional values as `*args: T`. If each positional value is itself a homogeneous tuple, use `*args: tuple[T, ...]`; the SDK rejects fixed-length tuple annotations such as `*args: tuple[int, str]` because one fixed tuple shape cannot describe a variadic sequence of positional values. ```python from typing import Annotated