From 5e6a73ed65b1a5e6c694d8264778d8aa10cb5c7f Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Mon, 28 Sep 2026 09:34:46 -0700 Subject: [PATCH 1/2] docs: clarify descriptions for variadic tool parameters Explain the existing Field description limitation and document supported docstring and Annotated descriptions, including their precedence. Based on Subhash Polisetti's original clarification and example in #4954. Co-authored-by: subhash polisetti --- docs/tools.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/tools.md b/docs/tools.md index 1e8567147c..892141d659 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -521,7 +521,11 @@ 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 `Field(description=...)` in the annotation of a variadic parameter (`*args` or `**kwargs`). To describe the collected parameter, use a parameter entry in the function docstring or a string in `Annotated`, for example `*scores: Annotated[int, "Exam scores", Field(ge=0, le=100)]`. When docstring parsing is enabled and both sources provide a description, the docstring description takes precedence. + +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 From 644d1aa3412ab842af29fa735f8c09b2e6b1b936 Mon Sep 17 00:00:00 2001 From: Justin Beckwith Date: Mon, 28 Sep 2026 09:39:19 -0700 Subject: [PATCH 2/2] docs: explain non-strict variadic keyword tool arguments --- docs/tools.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools.md b/docs/tools.md index 892141d659..781c43e7af 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -525,6 +525,8 @@ For variadic parameters, an annotation describes each collected value. The SDK t The SDK ignores `Field(description=...)` in the annotation of a variadic parameter (`*args` or `**kwargs`). To describe the collected parameter, use a parameter entry in the function docstring or a string in `Annotated`, for example `*scores: Annotated[int, "Exam scores", Field(ge=0, le=100)]`. When docstring parsing is enabled and both sources provide a description, the docstring description takes precedence. +For `**kwargs`, use `@tool(strict_mode=False)` and supply the keyword values in the nested object named after the parameter. For example, a tool with `**scores: int` receives `{"scores": {"exam": 90}}`. + 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